> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reasonos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Everyday commands

> Build, test, run, query, graph, and coverage — the rbs commands you use all day

Six commands cover the day-to-day loop. They all accept the same
[labels and target patterns](/build/packages-and-targets#target-patterns), and they all
share three global flags:

| Flag                      | Purpose                                                                                 |
| ------------------------- | --------------------------------------------------------------------------------------- |
| `-e, --env <name>`        | Select an [environment](/build/environments) declared in `.env.schema` (also `RBS_ENV`) |
| `--platforms <os-arch>`   | Target platform to build for (e.g. `linux-amd64`)                                       |
| `--workspace-root <path>` | Explicit workspace root (also `RBS_WORKSPACE_ROOT`)                                     |

## rbs build

Builds one or more targets, resolving the full dependency closure, executing in
dependency order, and running independent targets in parallel. Results come from the
shared cache when nothing relevant changed.

```bash theme={null}
rbs build :hello                  # one target in the current package
rbs build //services/api:server   # one target by full label
rbs build //...                   # everything in the workspace
rbs build :all                    # everything in the current package (the default)
rbs build services/api server migrate   # several targets in one package
```

Key flags:

| Flag                   | Purpose                                                            |
| ---------------------- | ------------------------------------------------------------------ |
| `-j, --jobs <n>`       | Cap parallel jobs (`0` = unlimited, the default)                   |
| `--no-cache`           | Re-run every action for this build instead of using cached results |
| `--cache-mode <mode>`  | `auto` (default), `force-miss`, or `force-hit`                     |
| `-w, --watch`          | Rebuild automatically when source files change                     |
| `--remote <host:port>` | Use a remote cache (defaults to `$RBS_REMOTE` when set)            |
| `--remote-exec`        | Execute cache misses on the remote cluster's workers               |

```bash theme={null}
rbs build //app:lib --watch                       # auto-rebuild on change
rbs build //... --remote cache.internal:8980       # share results with your team
```

Before executing, rbs prints the execution plan — every target in the closure and what
it depends on — so you can see exactly what a build will do.

## rbs test

Builds the requested targets and runs the ones that are tests. Test targets are the
ones declared with a test rule (`go_test`, `py_test`, `vitest_test`, and so on — any
rule whose kind ends in `_test` or is registered as a test).

```bash theme={null}
rbs test :all                      # all tests in the current package (the default)
rbs test //...                     # every test in the workspace
rbs test //services/api:api_test   # one test target
rbs test :api_test --watch         # TDD: re-run on every file change
```

Test output is captured under `.rbs/testlogs/<platform>/<package>/<name>/test.log`, so
a noisy suite doesn't scroll your terminal history away.

<Note>
  `rbs test` does **not** enforce coverage thresholds. If a test target declares
  `min_line_coverage` (or branch/function thresholds), `rbs test` runs it and prints a
  reminder — the gate only fires under `rbs coverage`.
</Note>

## rbs run

Builds a target (and its dependencies), then executes it.

```bash theme={null}
rbs run :server                    # build and run 'server' in the current package
rbs run //tools:migrate            # full label
rbs run services/api server        # natural syntax
```

### Multiple targets in parallel

Pass several targets — or `-p/--parallel` — and rbs builds them all first, then runs
them simultaneously. `Ctrl+C` stops every process. This is the standard way to bring up
a local stack:

```bash theme={null}
rbs run //services/api:server //web/shell:dev --parallel
rbs run shell:shell remote:counter      # two or more targets imply parallel mode
```

### Watch mode

`--watch` rebuilds and restarts the process whenever source files change:

```bash theme={null}
rbs run :server --watch
```

### Side-effect targets

Building stays pure — nothing a build does touches the outside world. Rules whose whole
point is a side effect (pushing an image, applying manifests) perform it at **run**
time instead:

```bash theme={null}
rbs run //services/api:push        # push the built image to its registry
rbs run //services/api:deploy      # apply the rendered Kubernetes manifests
```

## rbs query

Lists targets matching a pattern without building anything. Useful for exploring a
workspace and for scripting.

```bash theme={null}
rbs query                          # every target in the workspace (//...)
rbs query //services/...           # everything under services/
rbs query //services/api:all       # one package
rbs query :dev                     # one target in the current package
```

| Flag                 | Purpose                                                                                                                |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `-o, --output <fmt>` | `label` (default, one label per line), `kind` (`<kind> <label>`), or `json` (full details: srcs, deps, where declared) |
| `--kind <kind>`      | Only targets whose kind matches (exact or substring)                                                                   |

```bash theme={null}
rbs query --kind=test //...             # every test target
rbs query -o json //services/api:all    # machine-readable target details
```

## rbs graph

Emits the unified dependency graph of the whole workspace — build targets, infra
resources, CI workflows, and external dependencies — by evaluating every `.rbs` file
and walking the result.

```bash theme={null}
rbs graph                            # JSON on stdout (default)
rbs graph --format=dot | dot -Tpng -o graph.png
rbs graph --format=mermaid
```

| Flag                  | Purpose                                                                        |
| --------------------- | ------------------------------------------------------------------------------ |
| `-f, --format <fmt>`  | `json` (default), `dot`, or `mermaid`                                          |
| `--filter <type>`     | Only nodes of one type: `build`, `infra`, `ci`, `external`, `container`, `job` |
| `--package <path>`    | Subgraph for one package                                                       |
| `-o, --output <file>` | Write to a file instead of stdout                                              |

Progress messages while the workspace loads go to **stderr**, so stdout carries only
the document and stays pipeable:

```bash theme={null}
rbs graph 2>/dev/null | jq '.nodes[].id'
```

## rbs coverage

Runs test targets with coverage collection and **enforces the thresholds the targets
declare**. This is the coverage gate for CI.

```bash theme={null}
rbs coverage :all                    # all tests in the current package
rbs coverage //...                   # the whole workspace
rbs coverage //web/app:counter_test  # one test
```

A test rule declares its thresholds as attributes; the run fails if the measured
coverage drops below them:

```python theme={null}
vitest_test(
    name = "counter_coverage_test",
    srcs = ["src/Counter.tsx", "src/Counter.test.tsx"],
    deps = ["@external://react:19.0.0"],
    min_line_coverage = 80,        # `rbs coverage` FAILS below 80% lines
    min_branch_coverage = 70,
    min_function_coverage = 75,
)
```

`go_test` supports `min_line_coverage`; the JavaScript test rules
(`vitest_test`, `nodejs_test`) additionally support `min_branch_coverage` and
`min_function_coverage`. A threshold of `0` (the default) means no gate.

Coverage reports and logs land under
`.rbs/testlogs/<platform>/<package>/<name>/coverage/`.

<Tip>
  Make `rbs coverage //...` part of your CI workflow. Since `rbs test` deliberately does
  not enforce thresholds, teams typically run `rbs test` in the inner loop and
  `rbs coverage` as the merge gate.
</Tip>