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

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

# 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

rbs run [target] [options] [-- args...]

Examples

# 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

rbs test [target_pattern...] [options]

Options

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

Examples

# 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

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

# 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

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

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

# 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

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

# 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 for full documentation.

Syntax

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

# 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 for full documentation.

Syntax

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

# 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

rbs distributed [subcommand] [options]

Subcommands

Subcommand	Description
`status`	Show status of distributed workers.

Examples

# 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

# 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

# 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

Commands

Documentation Index

​CLI reference

​Global options

​rbs build

​Syntax

​Target patterns

​Examples

​rbs run

​Syntax

​Examples

​rbs test

​Syntax

​Options

​Examples

​Test output

​rbs coverage

​Syntax

​Options

​Examples

​rbs workspace

​Syntax

​Sample output

​rbs ci

​Syntax

​Options

​Examples

​rbs infra

​Syntax

​Subcommands

​Options

​Examples

​rbs agent

​Syntax

​Flags

​Examples

​rbs agent-builder

​Syntax

​Subcommands

​Examples

​rbs distributed

​Syntax

​Subcommands

​Examples

​Exit codes

​Common workflows

​Development cycle

​PR workflow

CLI reference

Global options

`rbs build`

Syntax

Target patterns

Examples

`rbs run`

Syntax

Examples

`rbs test`

Syntax

Options

Examples

Test output

`rbs coverage`

Syntax

Options

Examples

`rbs workspace`

Syntax

Sample output

`rbs ci`

Syntax

Options

Examples

`rbs infra`

Syntax

Subcommands

Options

Examples

`rbs agent`

Syntax

Flags

Examples

`rbs agent-builder`

Syntax

Subcommands

Examples

`rbs distributed`

Syntax

Subcommands

Examples

Exit codes

Common workflows

Development cycle

PR workflow