> ## 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.

# Build Commands

> Build, test, and run targets; query the target graph; generate coverage.

All of these commands accept the label and pattern syntax described in the
[CLI overview](/reference/cli/overview#target-labels-and-patterns). Global flags
(`-e/--env`, `--platforms`, `--workspace-root`, `--config`) apply to every
command and are documented there.

## rbs build

Build one or more targets with proper dependency handling. Dependencies are
resolved automatically and independent tasks run in parallel.

```bash theme={null}
rbs build [targets...] [flags]
```

| Flag                | Description                                                                                                         |
| ------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `--cache-mode`      | Cache mode: `auto`, `force-miss`, `force-hit` (default `auto`)                                                      |
| `-j, --jobs`        | Maximum number of parallel jobs (default `0` = unlimited)                                                           |
| `--no-cache`        | Disable the action cache for this build                                                                             |
| `--remote`          | Remote cache address (`host:port`); defaults to `$RBS_REMOTE` when set                                              |
| `--remote-download` | Which remote outputs to download: `all` (default), `toplevel`, `minimal`. Needs `RBS_EXECROOT=1`; ignored otherwise |
| `--remote-exec`     | Execute cache misses on the remote cluster's workers                                                                |
| `-w, --watch`       | Watch mode — automatically rebuild on file changes                                                                  |

```bash theme={null}
rbs build //...                                    # build everything in the workspace
rbs build //app:lib --watch                        # rebuild on file changes
rbs build //... --remote host:8980 --remote-exec   # shared cache + remote execution
```

## rbs test

Run one or more test targets.

```bash theme={null}
rbs test [targets...] [flags]
```

| Flag          | Description                                                   |
| ------------- | ------------------------------------------------------------- |
| `-w, --watch` | Watch mode — automatically re-run tests on file changes (TDD) |

```bash theme={null}
rbs test //...                # run all test targets in the workspace
rbs test //app:test --watch   # re-run one test target on every change
```

## rbs run

Run a single target, or multiple targets in parallel. Deliberate side-effect
targets (e.g. an `oci_push` or `k8s_deploy` target) perform their effect at run
time — the build itself stays pure.

```bash theme={null}
rbs run [target...] or [package target] [flags]
```

| Flag             | Description                                                    |
| ---------------- | -------------------------------------------------------------- |
| `-p, --parallel` | Run multiple targets in parallel (Ctrl+C stops all)            |
| `-w, --watch`    | Watch mode — automatically rebuild and restart on file changes |

```bash theme={null}
rbs run //examples:demo                          # run one target
rbs run shell:shell remote:counter --parallel    # run several apps together
rbs run //services/api:deploy                    # side-effect target: kubectl-apply rendered manifests
```

## rbs query

List and inspect build targets matching a pattern, without building anything.
With no pattern, queries the whole workspace (`//...`).

```bash theme={null}
rbs query [patterns...] [flags]
```

| Flag           | Description                                               |
| -------------- | --------------------------------------------------------- |
| `--kind`       | Only show targets whose kind matches (exact or substring) |
| `-o, --output` | Output format: `label`, `kind`, `json` (default `label`)  |

```bash theme={null}
rbs query //client/...            # all targets under client/
rbs query --kind=test -o kind     # every test target, printed as "<kind> <label>"
```

## rbs graph

Generate a full dependency graph of the workspace by executing all `.rbs` files
and walking every registry: build targets, infra resources, CI workflows, and
external dependencies.

```bash theme={null}
rbs graph [flags]
```

| Flag           | Description                                                                  |
| -------------- | ---------------------------------------------------------------------------- |
| `--filter`     | Filter nodes by type: `build`, `infra`, `ci`, `external`, `container`, `job` |
| `-f, --format` | Output format: `json`, `dot`, `mermaid` (default `json`)                     |
| `-o, --output` | Write the graph to a file instead of stdout                                  |
| `--package`    | Show the subgraph for a specific package                                     |

```bash theme={null}
rbs graph --format=dot | dot -Tpng -o graph.png   # render with Graphviz
rbs graph --filter=infra --package=services/api   # infra nodes for one package
```

<Note>
  Workspace-loading progress goes to stderr, so stdout carries only the graph
  document — `rbs graph | jq '.nodes[].id'` works as-is. Redirect stderr
  (`2>/dev/null`) to silence the progress output.
</Note>

## rbs coverage

Generate coverage reports for one or more test targets.

```bash theme={null}
rbs coverage [targets...] [flags]
```

This command has no flags of its own beyond the global set.

```bash theme={null}
rbs coverage //...              # coverage for every test target in the workspace
rbs coverage //examples:test    # coverage for one test target
```