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

# Operations Commands

> Infrastructure, CI workflows, cluster jobs, database migrations, and remote build services.

Commands for operating what you build: infrastructure defined in `.rbs` files,
RBS-native CI, cluster jobs, SQL migrations, and remote build services. Global
flags are documented in the
[CLI overview](/reference/cli/overview#global-flags).

## rbs infra

Manage infrastructure defined purely in the build language using the `infra.*`
SDK: plan and apply changes, inspect state, and browse provider schemas.

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

Every infra subcommand accepts these shared flags:

| Flag                | Description                                                                            |
| ------------------- | -------------------------------------------------------------------------------------- |
| `-e, --env`         | Environment to operate on — an alias for `--workspace` (`dev`, `staging`, `prod`, ...) |
| `-p, --parallelism` | Maximum parallel operations (default `10`)                                             |
| `-w, --workspace`   | Workspace to operate on (default `default`)                                            |

<Note>
  Within `rbs infra`, `-e/--env` selects the infra workspace — it is not the
  build environment selector that `-e` means on every other command.
</Note>

### rbs infra plan

Generate a plan showing what infrastructure changes will be made: resources
created, updated, deleted, or unchanged. No actual changes are made.

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

| Flag        | Description                                                                 |
| ----------- | --------------------------------------------------------------------------- |
| `-o, --out` | Save the plan to a file (default: `.rbs/infra/plans/<workspace>.plan.json`) |

```bash theme={null}
rbs infra plan //infra:all
rbs infra plan --workspace=prod
```

### rbs infra apply

Apply the infrastructure changes described in the plan — creating, updating,
or deleting resources as needed to match the desired state defined in your
`.rbs` files.

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

| Flag                 | Description                                    |
| -------------------- | ---------------------------------------------- |
| `-y, --auto-approve` | Skip interactive approval                      |
| `--dry-run`          | Show what would be done without making changes |

```bash theme={null}
rbs infra apply //infra:all
rbs infra apply --workspace=prod --auto-approve
```

### rbs infra destroy

Destroy all infrastructure resources in the current workspace. This deletes
all managed resources — use with caution.

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

| Flag                 | Description               |
| -------------------- | ------------------------- |
| `-y, --auto-approve` | Skip interactive approval |

```bash theme={null}
rbs infra destroy //infra:all --workspace=staging
```

### rbs infra show

Display the current infrastructure state: all resources tracked in state along
with their attributes and dependencies.

```bash theme={null}
rbs infra show
```

```bash theme={null}
rbs infra show --workspace=prod
```

### rbs infra output

Display output values from the infrastructure. Without arguments, shows all
outputs; with a name argument, only that output.

```bash theme={null}
rbs infra output [name] [flags]
```

| Flag     | Description           |
| -------- | --------------------- |
| `--json` | Output in JSON format |

```bash theme={null}
rbs infra output vpc_id
```

### rbs infra env

Resolve the environment a service gets from the infra it uses. Each infra
resource type declares conventional env exports (a database exports
`DATABASE_HOST`/`DATABASE_PORT`, a bucket exports `STORAGE_BUCKET`, ...);
values are resolved from the applied state.

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

| Flag       | Description                                                           |
| ---------- | --------------------------------------------------------------------- |
| `--export` | Print as shell `export` statements                                    |
| `--json`   | Print as JSON                                                         |
| `--need`   | Explicit `NAME=resource.attribute` wiring (repeatable)                |
| `--uses`   | Infra resource whose conventional env exports to include (repeatable) |

```bash theme={null}
rbs infra env --uses maindb --uses sessions --need DB_PASSWORD=maindb.password
eval "$(rbs infra env --uses maindb --export)"
```

### rbs infra graph

Display the declared infrastructure resources and their dependency edges.

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

| Flag    | Description              |
| ------- | ------------------------ |
| `--dot` | Emit Graphviz DOT format |

```bash theme={null}
rbs infra graph --dot | dot -Tsvg -o infra.svg
```

### rbs infra refresh

Update the state file to match the actual infrastructure. Reads the current
state from cloud providers and updates the local state without making any
changes.

```bash theme={null}
rbs infra refresh
```

```bash theme={null}
rbs infra refresh --workspace=prod
```

### rbs infra import

Import an existing resource into RBS state management, bringing existing
infrastructure under RBS management without recreating it.

```bash theme={null}
rbs infra import <type.name> <id>
```

```bash theme={null}
rbs infra import aws_instance.web i-1234567890abcdef0
```

### rbs infra verify

Smoke-test declared infra against the real providers — no credentials, no
cloud calls. Every declared resource is expanded through its adapters and each
emitted concrete resource is validated against the pinned provider binaries:
schema validation plus a plan-time dry run. Catches wrong attributes, invalid
values, and missing requirements before anything reaches apply. Server-side
rules (quota, IAM, uniqueness) still need a real apply.

```bash theme={null}
rbs infra verify [targets...]
```

```bash theme={null}
rbs infra verify //infra:all
```

### rbs infra schema

Fetch a provider's complete schema (every resource type it supports) and
browse it. With a resource type argument, show that resource's full attribute
schema: types, required/optional/computed, sensitivity.

```bash theme={null}
rbs infra schema <provider> [resource_type] [flags]
```

| Flag        | Description                              |
| ----------- | ---------------------------------------- |
| `--filter`  | Substring filter for resource type names |
| `--version` | Provider version (default: latest)       |

```bash theme={null}
rbs infra schema aws --filter s3
rbs infra schema aws aws_s3_bucket
```

### rbs infra generate

Generate typed, validated `.rbs` resource definitions from a provider schema
into `infra/<provider>/`, grouped one file per service (`aws_s3_*` → `s3.rbs`).
Generated files use only public SDK builtins and are user-owned: edit them
freely or regenerate.

```bash theme={null}
rbs infra generate <provider> [resource_types...] [flags]
```

| Flag         | Description                                                                                |
| ------------ | ------------------------------------------------------------------------------------------ |
| `--abstract` | Also generate an abstraction skeleton with this name over the first resource type          |
| `--all`      | Generate every resource type the provider supports                                         |
| `--embed`    | Write into the embedded rules catalog (for use when run from the rbs repo itself)          |
| `--out`      | Output directory root — files land in `<out>/<provider>/` (default `rules/infra/embedded`) |
| `--version`  | Provider version (default: latest)                                                         |

```bash theme={null}
rbs infra generate aws aws_s3_bucket aws_sqs_queue
rbs infra generate aws aws_mq_broker --abstract message_broker
```

### rbs infra scaffold

Scaffold a cross-cloud abstraction from provider schemas: an abstract
resource type plus one adapter per provider mapping.

```bash theme={null}
rbs infra scaffold <abstraction-name> [flags]
```

| Flag      | Description                                                                       |
| --------- | --------------------------------------------------------------------------------- |
| `--embed` | Write into the embedded rules catalog (for use when run from the rbs repo itself) |
| `--map`   | `provider=concrete_type` (repeatable, one per provider)                           |
| `--out`   | Output directory root for workspace mode (default `infra`)                        |

```bash theme={null}
rbs infra scaffold object_store --map aws=aws_s3_bucket --map google=google_storage_bucket
```

## rbs ci

Run RBS-native CI workflows with DAG execution — an alternative to GitHub
Actions that uses RBS's DAG executor for parallel job execution, with support
for distributed workers.

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

### rbs ci run

Run one or more CI workflows declared in `WORKSPACE.rbs` or any `ci.rbs` file.
If no workflow name is given, all workflows matching the trigger event run.

```bash theme={null}
rbs ci run [workflow] [flags]
```

| Flag          | Description                                                                           |
| ------------- | ------------------------------------------------------------------------------------- |
| `--affected`  | Run only on affected packages                                                         |
| `--base`      | Base branch for PR                                                                    |
| `--branch`    | Branch name                                                                           |
| `--event`     | Trigger event type (`push`, `pull_request`, `manual`)                                 |
| `--fail-fast` | Stop on first failure (default `true`)                                                |
| `--json`      | Output results as JSON                                                                |
| `--pr`        | Pull request number                                                                   |
| `--ref`       | Fully-qualified ref (`refs/heads/…` or `refs/tags/…`); decides branch vs tag          |
| `--remote`    | Run workflow jobs on a remote cluster (`host:port`; `$RBS_REMOTE` with the bare flag) |
| `--tag`       | Tag name (a tag push, not a branch push)                                              |
| `--timeout`   | Workflow timeout (default `30m`)                                                      |
| `--verbose`   | Verbose output                                                                        |
| `--workers`   | Number of parallel workers (default `4`)                                              |

```bash theme={null}
rbs ci run --event push
rbs ci run main --affected
```

### rbs ci plan

Resolve a trigger event into the job DAG it would run, printed as JSON on
stdout. Nothing is executed and nothing is written. Matrix jobs are expanded
and `needs` is rewritten to name expanded jobs, so the DAG in the output is
the one that would actually be scheduled; `if` expressions are passed through
unevaluated. This is the seam an external scheduler uses — it can read a plan
without hosting an interpreter for the build language.

```bash theme={null}
rbs ci plan [flags]
```

| Flag       | Description                                                                  |
| ---------- | ---------------------------------------------------------------------------- |
| `--base`   | Base branch for PR                                                           |
| `--branch` | Branch name                                                                  |
| `--event`  | Trigger event type (`push`, `pull_request`, `schedule`, `manual`)            |
| `--pr`     | Pull request number                                                          |
| `--ref`    | Fully-qualified ref (`refs/heads/…` or `refs/tags/…`); decides branch vs tag |
| `--tag`    | Tag name (a tag push, not a branch push)                                     |

```bash theme={null}
rbs ci plan --event push --branch main
rbs ci plan --event pull_request --base main --pr 42
```

### rbs ci list

List all CI workflows defined in the workspace.

```bash theme={null}
rbs ci list [flags]
```

| Flag     | Description    |
| -------- | -------------- |
| `--json` | Output as JSON |

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

### rbs ci affected

Detect and display packages affected by git changes — used by CI workflows to
run only on changed packages.

```bash theme={null}
rbs ci affected [flags]
```

| Flag        | Description                    |
| ----------- | ------------------------------ |
| `--base`    | Base branch/ref for comparison |
| `--json`    | Output as JSON                 |
| `--verbose` | Show detailed info             |

```bash theme={null}
rbs ci affected --base main --json
```

### rbs ci status

Show the status of CI workflow runs.

```bash theme={null}
rbs ci status [run-id] [flags]
```

| Flag     | Description    |
| -------- | -------------- |
| `--json` | Output as JSON |

```bash theme={null}
rbs ci status
```

### rbs ci trigger

Display the current CI trigger context based on git state.

```bash theme={null}
rbs ci trigger
```

## rbs job

Submit and manage cluster jobs (scheduler mode). Every subcommand talks to the
cluster named by `--server`, defaulting to `$RBS_REMOTE`.

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

### rbs job submit

Submit a job to the cluster.

```bash theme={null}
rbs job submit [flags] -- command [args...]
```

| Flag                | Description                                                                                                                                                                                                                                                                                               |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--array`           | Array spec: `0-99`, `1,3,7`, or `0-99%10` (throttle)                                                                                                                                                                                                                                                      |
| `--container`       | Run the payload inside this OCI image                                                                                                                                                                                                                                                                     |
| `--cpus`            | CPUs to reserve (default `1`)                                                                                                                                                                                                                                                                             |
| `--deps`            | Dependencies: `afterok:ID,afterany:ID,afternotok:ID`                                                                                                                                                                                                                                                      |
| `--env`             | Environment `KEY=VALUE` (repeatable)                                                                                                                                                                                                                                                                      |
| `--gpus`            | GPUs to reserve                                                                                                                                                                                                                                                                                           |
| `--inputs`          | Content to place in the job's working directory: a path, a built `//pkg:target`, or `DEST=SRC` to land it in a subdirectory (repeatable). Directories skip `.git` and `.rbs`. A target stages the outputs already built for `RBS_TARGET_PLATFORM`, so cross-platform clusters want that set when building |
| `-i, --interactive` | Attach stdin/stdout after submitting                                                                                                                                                                                                                                                                      |
| `--memory-gb`       | Memory to reserve (GiB)                                                                                                                                                                                                                                                                                   |
| `--name`            | Job name                                                                                                                                                                                                                                                                                                  |
| `--no-requeue`      | Fail on worker loss instead of requeuing                                                                                                                                                                                                                                                                  |
| `--nodes`           | Gang-allocate N workers for one job (MPI); `RBS_NODELIST`/`RANK` are injected (default `1`)                                                                                                                                                                                                               |
| `--outputs`         | A file or directory the job produces, relative to its working directory (repeatable). Collected when the job ends — including when it fails — and fetched with `rbs job outputs <id>`                                                                                                                     |
| `--preemptible`     | Allow higher-priority work to preempt this job                                                                                                                                                                                                                                                            |
| `--priority`        | Priority (higher runs first; age prevents starvation)                                                                                                                                                                                                                                                     |
| `--queue`           | Queue (default `batch`)                                                                                                                                                                                                                                                                                   |
| `--script`          | Submit a shell script instead of a command                                                                                                                                                                                                                                                                |
| `--server`          | Cluster address (default: `$RBS_REMOTE`)                                                                                                                                                                                                                                                                  |
| `--time`            | Time limit (e.g. `30m`, `2h`); exceeded jobs are marked `TIMEOUT`                                                                                                                                                                                                                                         |

```bash theme={null}
rbs job submit --name train --gpus 2 --time 2h --outputs checkpoints -- python train.py
rbs job submit --array 0-99%10 -- ./process-shard.sh
```

### rbs job list

List jobs — active by default; `--history` includes finished jobs.

```bash theme={null}
rbs job list [flags]
```

| Flag        | Description                              |
| ----------- | ---------------------------------------- |
| `--history` | Include finished jobs                    |
| `--queue`   | Filter by queue                          |
| `--server`  | Cluster address (default: `$RBS_REMOTE`) |
| `--state`   | Filter by state                          |

```bash theme={null}
rbs job list --history --queue batch
```

### rbs job show

Show one job in full detail.

```bash theme={null}
rbs job show <job-id> [flags]
```

| Flag       | Description                              |
| ---------- | ---------------------------------------- |
| `--server` | Cluster address (default: `$RBS_REMOTE`) |

```bash theme={null}
rbs job show 1234
```

### rbs job logs

Print a job's output.

```bash theme={null}
rbs job logs <job-id> [flags]
```

| Flag           | Description                              |
| -------------- | ---------------------------------------- |
| `-f, --follow` | Follow output until the job ends         |
| `--server`     | Cluster address (default: `$RBS_REMOTE`) |

```bash theme={null}
rbs job logs 1234 -f
```

### rbs job outputs

Download the files a job declared with `--outputs`. The worker collects those
paths into the cluster's content store when the job ends — including when it
fails, so a crashed run's checkpoints and logs are still recoverable. Files
are written under `--dest` with the layout the job wrote them in.

```bash theme={null}
rbs job outputs <job-id> [flags]
```

| Flag       | Description                                         |
| ---------- | --------------------------------------------------- |
| `--dest`   | Where to write them (default: `./job-<id>-outputs`) |
| `--server` | Cluster address (default: `$RBS_REMOTE`)            |

```bash theme={null}
rbs job outputs 1234 --dest ./results
```

### rbs job wait

Block until jobs finish; exits non-zero if any failed.

```bash theme={null}
rbs job wait <job-id...> [flags]
```

| Flag       | Description                              |
| ---------- | ---------------------------------------- |
| `--server` | Cluster address (default: `$RBS_REMOTE`) |

```bash theme={null}
rbs job wait 1234 1235
```

### rbs job cancel

Cancel jobs.

```bash theme={null}
rbs job cancel <job-id...> [flags]
```

| Flag       | Description                              |
| ---------- | ---------------------------------------- |
| `--server` | Cluster address (default: `$RBS_REMOTE`) |

```bash theme={null}
rbs job cancel 1234
```

### rbs job queues

List queues, their limits, and occupancy.

```bash theme={null}
rbs job queues [flags]
```

| Flag       | Description                              |
| ---------- | ---------------------------------------- |
| `--server` | Cluster address (default: `$RBS_REMOTE`) |

```bash theme={null}
rbs job queues
```

### rbs job reserve

Create or cancel a maintenance window: new work stops and running work drains.

```bash theme={null}
rbs job reserve <name> [flags]
```

| Flag       | Description                                       |
| ---------- | ------------------------------------------------- |
| `--cancel` | Cancel the named reservation                      |
| `--for`    | Window length (default `1h`)                      |
| `--in`     | Start the window this far from now (default `0s`) |
| `--reason` | Why the window exists (default `maintenance`)     |
| `--server` | Cluster address (default: `$RBS_REMOTE`)          |

```bash theme={null}
rbs job reserve kernel-upgrade --in 30m --for 2h --reason "host reboot"
rbs job reserve kernel-upgrade --cancel
```

## rbs migrate

Manage SQL database migrations, Flyway-style: versioned and repeatable
migration files with a history table per target database.

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

### rbs migrate create

Create a new versioned or repeatable migration SQL file.

```bash theme={null}
rbs migrate create <target> <description> [flags]
```

| Flag           | Description                                                              |
| -------------- | ------------------------------------------------------------------------ |
| `--repeatable` | Create a repeatable migration (`R__desc.sql`) instead of a versioned one |

```bash theme={null}
rbs migrate create users_db "create users table"
rbs migrate create --repeatable users_db "update permissions"
```

### rbs migrate info

Show migration status for a target: which migrations are applied, pending,
failed, and so on.

```bash theme={null}
rbs migrate info <target>
```

```bash theme={null}
rbs migrate info users_db
```

### rbs migrate validate

Validate that all applied migrations match their files on disk; exits non-zero
if any issues are found. Use in CI to catch files modified after being applied
(checksum mismatch), files deleted after being applied, and previously failed
migrations that need attention.

```bash theme={null}
rbs migrate validate <target>
```

```bash theme={null}
rbs migrate validate users_db
```

### rbs migrate apply

Apply all pending versioned and outdated repeatable migrations in order. Each
migration runs in its own transaction; on failure, the migration is recorded
as failed and execution stops. A migration whose leading comments contain
`-- rbs:no-transaction` runs its statements individually outside any
transaction (for statements like `CREATE INDEX CONCURRENTLY`). Concurrent
applies are safe: a database-side lock serializes migrators.

```bash theme={null}
rbs migrate apply <target> [flags]
```

| Flag             | Description                                                                                                            |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `--dry-run`      | Show SQL without executing                                                                                             |
| `--out-of-order` | Apply pending migrations with versions lower than already-applied ones instead of failing (a stale branch merged late) |

```bash theme={null}
rbs migrate apply users_db --dry-run
rbs migrate apply users_db
```

### rbs migrate baseline

Mark all versioned migrations up to and including the given version as
applied, without executing them. Use this when adopting RBS migrations on a
database that already has the schema in place.

```bash theme={null}
rbs migrate baseline <target> <version>
```

```bash theme={null}
rbs migrate baseline users_db 1709141200
```

### rbs migrate repair

Fix the migration history table: remove all entries for failed migrations (so
they can be retried) and realign checksums for applied migrations to match the
current files on disk. A recovery command — use it after fixing a broken
migration or when intentionally modifying an already-applied migration file.

```bash theme={null}
rbs migrate repair <target>
```

```bash theme={null}
rbs migrate repair users_db
```

## rbs remote

Remote build services: a REAPI remote cache today, with execution and workers
in the same cluster.

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

### rbs remote serve

Serve a REAPI remote cache over the shared store.

```bash theme={null}
rbs remote serve [flags]
```

| Flag         | Description                                                                 |
| ------------ | --------------------------------------------------------------------------- |
| `--dir`      | Store directory (default: the shared per-user store)                        |
| `--insecure` | Disable authentication entirely                                             |
| `--port`     | gRPC port for REAPI clients (default `8980`)                                |
| `--token`    | Bearer token (default: auto-generated and persisted)                        |
| `--workers`  | Colocated workers to start (`0` = serve cache/scheduler only) (default `1`) |

```bash theme={null}
rbs remote serve --port 8980 --workers 4
```

### rbs remote worker

Join this machine to a remote build cluster as a worker.

```bash theme={null}
rbs remote worker [flags]
```

| Flag             | Description                                                                       |
| ---------------- | --------------------------------------------------------------------------------- |
| `--address`      | Reachable host for MPI rendezvous (default: hostname)                             |
| `--health-check` | Script run periodically; a non-zero exit drains this worker                       |
| `--job-slots`    | Concurrent scheduler-mode jobs, separate from build-action capacity (default `2`) |
| `--jobs`         | Concurrent leases (default: CPU count)                                            |
| `--name`         | Worker name (default: hostname)                                                   |
| `--server`       | Cluster address (`host:port`)                                                     |
| `--token`        | Bearer token (default: `$RBS_REMOTE_TOKEN`)                                       |
| `--work-dir`     | Exec-root parent directory                                                        |

```bash theme={null}
rbs remote worker --server build-host:8980 --jobs 8
```

### rbs remote status

Show cluster status: workers, queue, and jobs.

```bash theme={null}
rbs remote status [flags]
```

| Flag       | Description                              |
| ---------- | ---------------------------------------- |
| `--server` | Cluster address (default: `$RBS_REMOTE`) |

```bash theme={null}
rbs remote status
```