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

# CLI reference

> Complete reference for all RBS commands — available in the editor terminal and command palette

# CLI reference

All RBS commands run on your **branch server** via the integrated terminal in your code editor or through the command palette. Commands execute on the server, not on your local machine.

## Global options

These options can be used with any RBS command:

| Option            | Description                |
| ----------------- | -------------------------- |
| `--help`, `-h`    | Show help for any command. |
| `--verbose`, `-v` | Enable verbose output.     |
| `--version`       | Print the RBS version.     |

***

## `rbs build`

Build one or more targets.

### Syntax

```bash theme={null}
rbs build [target_pattern...] [options]
```

### Target patterns

| Pattern      | Description                                 | Example                           |
| ------------ | ------------------------------------------- | --------------------------------- |
| `name`       | Target in current package (natural syntax). | `rbs build hello`                 |
| `:name`      | Target in current package (traditional).    | `rbs build :hello`                |
| `pkg name`   | Target in a sub-package (natural).          | `rbs build services/api server`   |
| `//pkg:name` | Target in a sub-package (traditional).      | `rbs build //services/api:server` |
| `//...`      | All targets in entire workspace.            | `rbs build //...`                 |
| `:all`       | All targets in current package.             | `rbs build :all`                  |

### Examples

```bash theme={null}
# Build a single target
rbs build hello

# Build a target in a sub-package
rbs build services/api server

# Build all targets in the workspace
rbs build //...

# Build multiple targets
rbs build :hello :world :greet
```

***

## `rbs run`

Build and execute a single target.

### Syntax

```bash theme={null}
rbs run [target] [options] [-- args...]
```

### Examples

```bash theme={null}
# Run a target in the current package
rbs run hello

# Run a target in a sub-package
rbs run services/api server

# Pass arguments to the target
rbs run :server -- --port 8080 --debug
```

***

## `rbs test`

Build and run test targets.

### Syntax

```bash theme={null}
rbs test [target_pattern...] [options]
```

### Options

| Option                    | Description                                         |
| ------------------------- | --------------------------------------------------- |
| `--test_tag_filters=TAGS` | Filter tests by tags (e.g., `unit`, `integration`). |

### Examples

```bash theme={null}
# Run all tests in the workspace
rbs test //...

# Run tests in a specific package
rbs test services/api server_test

# Run only unit tests
rbs test //... --test_tag_filters=unit

# Run only integration tests
rbs test //... --test_tag_filters=integration
```

### Test output

Test results are displayed inline in your editor and stored on the server:

```
.rbs/testlogs/{platform}/
├── services/api/
│   └── server_test/
│       ├── test.log          # Full test output
│       └── test_result.xml   # JUnit XML report
└── libs/common/
    └── utils_test/
        ├── test.log
        └── test_result.xml
```

***

## `rbs coverage`

Run tests with code coverage analysis.

### Syntax

```bash theme={null}
rbs coverage [target_pattern...] [options]
```

### Options

| Option            | Description                                              |
| ----------------- | -------------------------------------------------------- |
| `--format=FORMAT` | Output format (`text`, `html`, `json`). Default: `text`. |
| `--threshold=N`   | Minimum coverage percentage required (fails if below).   |

### Examples

```bash theme={null}
# Run coverage for all tests
rbs coverage //...

# Require minimum 80% coverage
rbs coverage //... --threshold=80

# Generate HTML coverage report
rbs coverage //... --format=html
```

Coverage results are highlighted directly in your editor — green for covered lines, red for uncovered.

***

## `rbs workspace`

Display workspace information including targets, configurations, and server status.

### Syntax

```bash theme={null}
rbs workspace [options]
```

### Sample output

```
📦 RBS Workspace Information
============================
📍 Root: /workspace/my-project
🖥️  Server: rbs-server-feature-auth-abc123
🌿 Branch: feature/auth
👥 Connected: 2 developers

⚙️  Configuration:
   project_name = "my-project"
   version = "1.0.0"

🎯 Targets:
   //:hello (task)
   //services/api:server (java_binary)
   //services/api:server_test (java_test)
   //services/api:server_image (oci_image)

🔧 Toolchains:
   java: JDK 17.0.11 (ready)
   nodejs: Node.js 20.11.0 (ready)

📦 External Dependencies:
   spring_boot_web: 3.2.0 (cached)
   express_repo: 4.18.2 (cached)

🤖 Agents:
   review_bot: active (last triggered 2h ago)
   deploy_bot: active (idle)
```

***

## `rbs ci`

Run CI workflows.

### Syntax

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

### Options

| Option            | Description                                                       |
| ----------------- | ----------------------------------------------------------------- |
| `--workflow=NAME` | Run a specific workflow.                                          |
| `--affected`      | Run only on targets affected by recent changes.                   |
| `--base=REF`      | Git reference for computing affected targets (default: `HEAD~1`). |
| `--distributed`   | Enable distributed execution across workers.                      |
| `--dry-run`       | Show execution plan without running.                              |
| `--verbose`       | Show detailed execution output.                                   |

### Examples

```bash theme={null}
# Run default CI workflow
rbs ci

# Run only affected targets (ideal for PRs)
rbs ci --affected --base=origin/main

# Run a specific workflow
rbs ci --workflow=build_and_test

# Dry run to see what would execute
rbs ci --dry-run
```

***

## `rbs infra`

Manage infrastructure provisioning.

### Syntax

```bash theme={null}
rbs infra [subcommand] [options]
```

### Subcommands

| Subcommand | Description                                            |
| ---------- | ------------------------------------------------------ |
| `plan`     | Generate an execution plan for infrastructure changes. |
| `apply`    | Apply infrastructure changes.                          |
| `destroy`  | Destroy managed infrastructure.                        |
| `show`     | Display current infrastructure state.                  |
| `refresh`  | Update state from actual infrastructure.               |
| `import`   | Import existing resources into state.                  |
| `output`   | Show output values.                                    |
| `graph`    | Generate dependency graph.                             |

### Options

| Option             | Description                                                    |
| ------------------ | -------------------------------------------------------------- |
| `--workspace=NAME` | Use a specific infrastructure workspace (e.g., `dev`, `prod`). |
| `--auto-approve`   | Skip interactive approval for apply/destroy.                   |

### Examples

```bash theme={null}
# Plan infrastructure changes
rbs infra plan //...

# Apply with a specific workspace
rbs infra apply --workspace=prod --auto-approve

# Show current state
rbs infra show

# Import an existing resource
rbs infra import aws_instance.web i-0abc123
```

***

## `rbs agent`

Start the built-in AI coding agent — an interactive assistant that can read, edit, build, test, and deploy your codebase through natural language. See [Coding agent](/agent-builder) for full documentation.

### Syntax

```bash theme={null}
rbs agent [flags] [prompt]
```

### Flags

| Flag                    | Description                            |
| ----------------------- | -------------------------------------- |
| `-m, --model`           | Model to use (auto-detects provider).  |
| `-f, --files`           | Comma-separated list of context files. |
| `-s, --system`          | Custom system prompt.                  |
| `-n, --non-interactive` | Run once without interactive mode.     |
| `--full-docs`           | Enable full documentation access.      |

### Examples

```bash theme={null}
# Start interactive mode
rbs agent

# Run with a prompt
rbs agent "Add a /health endpoint that returns JSON status"

# Use a specific model
rbs agent --model "claude-sonnet-4" "Explain this codebase"

# With context files
rbs agent --files "main.py,config.py" "Explain the entry point"

# Non-interactive (single prompt, then exit)
rbs agent -n "What targets are available?"
```

***

## `rbs agent-builder`

Build, serve, and test custom AI agents defined in your `BUILD.rbs` files. See [Agent Builder SDK](/platform/agent-builder-sdk) for full documentation.

### Syntax

```bash theme={null}
rbs agent-builder [subcommand] [target] [options]
```

### Subcommands

| Subcommand     | Description                           |
| -------------- | ------------------------------------- |
| `serve`        | Start an agent system.                |
| `test`         | Test an agent with events.            |
| `list`         | List registered agent components.     |
| `dag show`     | Display DAG workflow structure.       |
| `dag validate` | Validate a DAG workflow.              |
| `dag export`   | Export DAG as Mermaid or DOT diagram. |

### Examples

```bash theme={null}
# Serve an agent system
rbs agent-builder serve //support:customer_support

# Serve on a custom port with hot reload
rbs agent-builder serve //support:customer_support --port 9000 --watch

# Test with a single event
rbs agent-builder test //support:customer_support \
    --event "user.message" \
    --data '{"content": "I need help with my order"}'

# Interactive testing
rbs agent-builder test //support:customer_support --interactive

# List registered components
rbs agent-builder list --verbose

# Show DAG structure
rbs agent-builder dag show order_workflow

# Export DAG as Mermaid diagram
rbs agent-builder dag export order_workflow --format mermaid
```

***

## `rbs distributed`

Manage distributed build execution.

### Syntax

```bash theme={null}
rbs distributed [subcommand] [options]
```

### Subcommands

| Subcommand | Description                         |
| ---------- | ----------------------------------- |
| `status`   | Show status of distributed workers. |

### Examples

```bash theme={null}
# Check worker status
rbs distributed status
```

***

## Exit codes

| Code | Description                    |
| ---- | ------------------------------ |
| `0`  | Success.                       |
| `1`  | Build or test failure.         |
| `2`  | Command-line usage error.      |
| `3`  | Workspace configuration error. |

***

## Common workflows

### Development cycle

```bash theme={null}
# 1. View available targets
rbs workspace

# 2. Build your target
rbs build services/api server

# 3. Run your target
rbs run services/api server

# 4. Run tests
rbs test services/api server_test

# 5. Check coverage
rbs coverage services/api server_test --threshold=80
```

### PR workflow

```bash theme={null}
# 1. Build and test only affected targets
rbs ci --affected --base=origin/main

# 2. Build container images
rbs build //services/api:server_image

# 3. View results (also visible inline in editor)
rbs workspace
```