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

# Workspace Commands

> Scaffold code, manage environments and caches, sync dependencies, and manage external rules.

Commands for working with the workspace itself: generating code, resolving the
environment, managing the shared cache, syncing dependencies, and managing rule
packages. Global flags are documented in the
[CLI overview](/reference/cli/overview#global-flags).

## rbs scaffold

Generate boilerplate code from a scaffolding template, with variable
substitution in both file names and content.

```bash theme={null}
rbs scaffold [scaffold-target] [destination-package] [flags]
```

* File name variables: `__variableName__` is replaced with the variable value (`__className__.py` becomes `MyClass.py`).
* Content variables: `<%= variableName %>` is replaced with the variable value.

| Flag                | Description                                                                                 |
| ------------------- | ------------------------------------------------------------------------------------------- |
| `--non-interactive` | Never prompt: use `--var` values plus declared defaults, and fail if a variable has neither |
| `--var`             | Set a scaffold variable as `key=value` (repeatable). Skips the prompt for that variable     |

```bash theme={null}
rbs scaffold :component //src/components                     # scaffold into src/components
rbs scaffold //templates:service //services/auth --var name=auth --non-interactive
```

### rbs scaffold list

List all scaffolding templates defined in the workspace.

```bash theme={null}
rbs scaffold list
```

## rbs env

Resolve, validate, and explain the environment declared by `.env.schema` and
supplied by the layered `.env` files. Environments are whatever your
`.env.schema` declares with `env.environment()` — rbs hardcodes none. Select
one with `-e` (or `RBS_ENV`).

```bash theme={null}
rbs env [command]
```

### rbs env check

Validate every package that declares a schema; exits non-zero on failure. This
is the gate to run in CI.

```bash theme={null}
rbs env check [flags]
```

| Flag       | Description                                                                                                                                  |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `--strict` | Ignore `.env.local` (so the result is reproducible from committed files alone) and fail on variables set in a file but declared in no schema |

```bash theme={null}
rbs env check --strict
```

### rbs env print

Print the resolved environment, with secrets redacted.

```bash theme={null}
rbs env print [flags]
```

| Flag        | Description                                                        |
| ----------- | ------------------------------------------------------------------ |
| `--format`  | Output format: `dotenv`, `export`, or `json` (default `dotenv`)    |
| `--package` | Package to resolve for (default: workspace root)                   |
| `--reveal`  | Show secret values in full (refused when stdout is not a terminal) |

```bash theme={null}
rbs env print -e prod --format json
```

### rbs env explain

Show where a variable's value came from — which file, line, and source won —
and what it shadowed.

```bash theme={null}
rbs env explain <VAR> [flags]
```

| Flag        | Description                                      |
| ----------- | ------------------------------------------------ |
| `--package` | Package to resolve for (default: workspace root) |

```bash theme={null}
rbs env explain DATABASE_URL
```

### rbs env diff

Show what differs between two environments.

```bash theme={null}
rbs env diff <envA> <envB> [flags]
```

| Flag        | Description                                      |
| ----------- | ------------------------------------------------ |
| `--package` | Package to resolve for (default: workspace root) |

```bash theme={null}
rbs env diff dev prod
```

### rbs env environments

List every environment declared with `env.environment()` in `.env.schema`; the
selected environment is marked. Counts cover every package that declares a
schema, and come from the schema — so a required secret nothing has set yet is
reported rather than silently missing. "unset" is how many declared variables
have no value in that environment. Alias: `rbs env envs`.

```bash theme={null}
rbs env environments [flags]
```

| Flag        | Description                                                |
| ----------- | ---------------------------------------------------------- |
| `--json`    | Output as JSON                                             |
| `--package` | Narrow the counts to one package (default: workspace root) |

```bash theme={null}
rbs env environments --json
```

### rbs env template

Generate a `.env.example` from the schema.

```bash theme={null}
rbs env template [flags]
```

| Flag        | Description                                      |
| ----------- | ------------------------------------------------ |
| `--package` | Package to resolve for (default: workspace root) |

```bash theme={null}
rbs env template -e prod
```

## rbs cache

Manage rbs's caches. There is exactly one action/content cache: the user-global
content-addressed store (`~/.cache/rbs`, or `$RBS_CACHE_DIR`), shared by every
workspace on the machine. The per-workspace `.rbs/` directory holds only
materialized state — outputs, toolchains, external deps — rebuilt on demand.

```bash theme={null}
rbs cache [command]
```

### rbs cache stats

Report disk usage of the shared content-addressed store and, when run inside a
workspace, the workspace's materialized `.rbs/` state.

```bash theme={null}
rbs cache stats
```

### rbs cache gc

Garbage-collect the shared content-addressed store, bounding it by age and
size. This is the recommended way to reclaim space.

```bash theme={null}
rbs cache gc [flags]
```

| Flag        | Description                                                                           |
| ----------- | ------------------------------------------------------------------------------------- |
| `--max-age` | Collect anything not accessed within this window (supports `d`, `w`) (default `30d`)  |
| `--max-gb`  | Size budget in GiB — least-recently-used blobs beyond it are collected (default `20`) |

```bash theme={null}
rbs cache gc --max-age 14d --max-gb 10
```

### rbs cache clean

Remove entries from the shared content-addressed store. `--max-age` removes
only entries older than a given age (supports `w`, `d`, `h`, `m`, `s`); the
user-global OCI image cache is swept by the same bound. `--all` removes
everything, including the image cache.

```bash theme={null}
rbs cache clean [flags]
```

| Flag        | Description                                                                     |
| ----------- | ------------------------------------------------------------------------------- |
| `--all`     | Remove every entry from the shared store (affects all workspaces for this user) |
| `--max-age` | Only remove entries older than this (e.g. `7d`, `2w`, `24h`)                    |

```bash theme={null}
rbs cache clean --max-age 7d
```

<Warning>
  Bare `rbs cache clean` is refused: the store is shared across every workspace
  for your user, so emptying it is never what "clean this project" means. Prefer
  `rbs cache gc`; use `--max-age` or an explicit `--all` if you really mean to
  remove entries.
</Warning>

## rbs sync

Download and resolve all external dependencies for the specified targets into
`.rbs/external-deps/`, so language servers (LSP) can provide autocomplete,
go-to-definition, and type checking.

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

| Flag            | Description                                   |
| --------------- | --------------------------------------------- |
| `--dry-run`     | Show what would be synced without downloading |
| `-v, --verbose` | Show detailed sync progress                   |

```bash theme={null}
rbs sync //...                                # sync every target in the workspace
rbs sync //examples/django-blog:prod_server   # sync one target's dependencies
```

## rbs ext

Manage external rule packages. Each package is declared in `ext.rbs` under a
namespace you choose and loaded as `@<namespace>//<path>.rbs`:

```python theme={null}
# ext.rbs
ext(name = "java", git = "https://github.com/acme/java-rules", ref = "v1.2.0")

# BUILD.rbs
load("@java//jvm/rules.rbs", "java_binary")
```

Refs resolve to a commit once and the commit is recorded in `rbs.lock`, so
builds are reproducible and a moved tag cannot change your rules silently.
`rbs ext update` is the only thing that re-reads a moving ref.

```bash theme={null}
rbs ext [command]
```

### rbs ext add

Add an entry to `ext.rbs`, resolve it, and record the pin.

```bash theme={null}
rbs ext add <git-url|org/name> [flags]
```

| Flag        | Description                                                 |
| ----------- | ----------------------------------------------------------- |
| `--as`      | Namespace to load it under (default: derived from the name) |
| `--ref`     | Tag, branch, or commit (git sources)                        |
| `--version` | Version tag (`org/name` coordinates)                        |

```bash theme={null}
rbs ext add https://github.com/acme/java-rules --ref v1.2.0 --as jvm
rbs ext add acme/shared-rules --version 2.0.0
```

### rbs ext list

Show declared packages, their pins, and what they pull in.

```bash theme={null}
rbs ext list
```

### rbs ext update

Forget the recorded commit for a ref and resolve it again. Everywhere else the
pin in `rbs.lock` wins, which is what stops a moved tag from changing a build.

```bash theme={null}
rbs ext update [namespace]
```

### rbs ext remove

Drop a package from `ext.rbs`.

```bash theme={null}
rbs ext remove <namespace>
```

## rbs rules

Manage and test rules.

```bash theme={null}
rbs rules [command]
```

### rbs rules test

Run unit tests for custom rules and functions. Discovers and runs test files
matching the pattern (default: `*_test.rbs`). Test files use `assert`
functions: `assert.equals`, `assert.true`, `assert.false`, `assert.contains`,
`assert.fails`.

```bash theme={null}
rbs rules test [pattern]
```

```bash theme={null}
rbs rules test            # run all rule tests
rbs rules test genrule    # run tests matching 'genrule'
```

### rbs rules integration

Run integration tests for rules with real RBS workspace execution. Discovers
and runs files matching the pattern (default: `*_integration_test.rbs`).
Integration tests can create temporary workspaces, run rbs commands, and assert
on outputs via the `integration.*` functions (`create_workspace`, `copy_rules`,
`run_rbs`, `assert_file`, `assert_output`, `write_file`, `read_file`,
`cleanup`).

```bash theme={null}
rbs rules integration [pattern]
```

```bash theme={null}
rbs rules integration           # run all integration tests
rbs rules integration python    # run integration tests matching 'python'
```