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.
rbs scaffold
Generate boilerplate code from a scaffolding template, with variable
substitution in both file names and content.
- File name variables:
__variableName__ is replaced with the variable value (__className__.py becomes MyClass.py).
- Content variables:
<%= variableName %> is replaced with the variable value.
rbs scaffold list
List all scaffolding templates defined in the workspace.
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).
rbs env check
Validate every package that declares a schema; exits non-zero on failure. This
is the gate to run in CI.
rbs env print
Print the resolved environment, with secrets redacted.
rbs env explain
Show where a variable’s value came from — which file, line, and source won —
and what it shadowed.
rbs env diff
Show what differs between two environments.
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.
rbs env template
Generate a .env.example from the schema.
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.
rbs cache stats
Report disk usage of the shared content-addressed store and, when run inside a
workspace, the workspace’s materialized .rbs/ state.
rbs cache gc
Garbage-collect the shared content-addressed store, bounding it by age and
size. This is the recommended way to reclaim space.
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.
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.
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.
rbs ext
Manage external rule packages. Each package is declared in ext.rbs under a
namespace you choose and loaded as @<namespace>//<path>.rbs:
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.
rbs ext add
Add an entry to ext.rbs, resolve it, and record the pin.
rbs ext list
Show declared packages, their pins, and what they pull in.
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.
rbs ext remove
Drop a package from ext.rbs.
rbs rules
Manage and test rules.
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.
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).
