Overview

Use ByteRover CLI in CI/CD pipelines, automation scripts, and server environments

In ByteRover CLI v2.0.0, the daemon-first architecture means every CLI command runs headless by default. The background daemon handles all execution — the TUI is just another optional client. There is no special flag to enable headless mode. Run any brv command from a script, pipeline, or SSH session and it works out of the box.

NOTE

Daemon-first headless execution requires ByteRover CLI v2.0.0 or later.

Quick Start

Step 1: Connect a provider

To use the built-in ByteRover provider, authenticate first with brv login --api-key $BYTEROVER_API_KEY. Since v3.8.3, brv login defaults to a browser OAuth flow; in CI, SSH, or other non-interactive shells, always pass --api-key (SSH and non-interactive shells are auto-detected and will skip the browser, but passing --api-key explicitly is clearer). To use a third-party provider instead (no ByteRover login needed):

brv providers connect openrouter --api-key $OPENROUTER_API_KEY --model anthropic/claude-sonnet-4-20250514

Step 2: (Optional) Install a connector for your coding agent

brv connectors install "Claude Code"

Step 3: Run commands with structured output

brv query "How is auth implemented?" --format json

TIP

The daemon auto-starts on the first command — no manual setup needed. It shuts down automatically after 30 minutes of inactivity.

The --format json Flag

The --format json flag is the key to automation. It produces structured JSON output on every command, making it easy to parse results in scripts and pipelines.

Flag	Description	Default
--format <text|json>	Output format: text for human-readable, json for structured	text

All commands listed below support --format json.

Supported Commands

Command	Key Flags	Auth Required	Description
brv status	—	No	Show CLI and project status
brv query "<question>"	—	No	Query the context tree
brv curate "<context>"	--files, --folder, --detach	No	Curate context to the tree
brv curate view [id]	--status, --since, --before, --limit, --detail	No	View curate history and audit trail
brv providers connect <provider>	--api-key, --model, --base-url	No	Connect an LLM provider
brv providers list	—	No	List available providers and connection status
brv providers switch <provider>	—	No	Switch the active provider
brv providers disconnect <provider>	—	No	Disconnect an LLM provider
brv model	—	No	Show active model and provider
brv model list	--provider	No	List available models
brv model switch <model>	--provider	No	Switch the active model
brv connectors	—	No	List installed agent connectors
brv connectors install <agent>	--type	No	Install a coding agent connector
brv hub list	—	No	List available skills and bundles
brv hub install <id>	--agent, --scope, --registry	No	Install a skill or bundle from the hub
brv login --api-key <key>	—	—	Authenticate for cloud sync
brv vc push	--set-upstream	Yes	Push commits to cloud
brv vc pull	--allow-unrelated-histories	Yes	Pull commits from cloud
brv vc remote set-url origin <url>	—	Yes	Switch to a different remote space
brv vc remote remove origin	—	No	Disconnect the local space from ByteRover cloud
brv space list	—	Yes	List available teams and spaces

NOTE

Commands marked "No" under Auth Required work entirely locally — no account, no internet (when using a local or third-party LLM provider). Exception: brv providers connect byterover and brv providers switch byterover require a logged-in ByteRover account. See Local vs Cloud for a full breakdown.

For full command syntax, flags, and examples, see the CLI Reference. For detailed provider and model management, see External LLM Providers. For the skills and bundles registry, see BRV Hub.

JSON Output Format

When using --format json, every command outputs one or more JSON lines to stdout. Each line follows the same envelope structure.

Response Envelope

interface JsonResponse {
  command: string      // Command name (e.g., "status", "query", "push")
  data: object         // Command-specific payload
  success: boolean     // true for success, false for errors
  timestamp: string    // ISO 8601 timestamp
}

Single-Response Commands

Commands like status, vc push, vc pull, and vc status emit a single JSON line:

{"command":"status","data":{"authStatus":"logged_in","userEmail":"dev@example.com","currentDirectory":"/project","teamName":"my-team","spaceName":"my-space","contextTreeStatus":"no_changes","cliVersion":"2.0.0"},"success":true,"timestamp":"2026-01-15T10:30:00.000Z"}

Streaming Commands

Commands like query and curate emit multiple JSON lines as the task progresses. Each line includes a data.event field:

Event	Description
thinking	LLM reasoning started
toolCall	Tool invoked (includes toolName, args)
toolResult	Tool completed (includes success)
response	LLM final answer content
completed	Task finished (includes result, status)
error	Task failed (includes message, status)

Example stream for a query:

{"command":"query","data":{"event":"thinking","taskId":"a1b2c3"},"success":true,"timestamp":"2026-01-15T10:30:00.000Z"}
{"command":"query","data":{"event":"response","taskId":"a1b2c3","content":"Authentication uses JWT tokens with 24-hour expiry..."},"success":true,"timestamp":"2026-01-15T10:30:03.000Z"}
{"command":"query","data":{"event":"completed","taskId":"a1b2c3","result":"Authentication uses JWT tokens with 24-hour expiry...","status":"completed"},"success":true,"timestamp":"2026-01-15T10:30:03.000Z"}

Error Responses

Errors set success: false and include error details in data:

{"command":"query","data":{"error":"No provider connected","status":"error"},"success":false,"timestamp":"2026-01-15T10:30:00.000Z"}

TIP

Use jq to extract specific fields from JSON output:

brv status --format json | jq '.data.spaceName'
brv vc status | jq '.currentBranch'

Coding Agent Integration (brv mcp)

The brv mcp command starts an MCP (Model Context Protocol) server that coding agents use to access your project's context tree. It is a hidden command — coding agents spawn it automatically; you don't run it directly.

How It Works

Coding Agent (Claude Code / Cursor / Windsurf)
    │
    │ stdio (MCP protocol)
    ▼
brv mcp (MCP Server)
    │
    │ Socket.IO
    ▼
Daemon (brv-server)
    │
    ▼
Agent Pool (LLM workers)

The MCP server connects to the running daemon (auto-starting it if needed) and exposes ByteRover's context management as tools that the coding agent can call.

Available MCP Tools

Tool	Parameters	Description
brv-query	query (required)	Query the context tree for project knowledge
brv-curate	context, files, folder	Store context to the context tree

If the running daemon was started by a different brv build than the one spawning brv mcp, the text responses from both tools end with a daemon-version drift footer, and brv mcp logs a one-line drift notice to stderr on connect/reconnect. This matters for headless and CI agents where stderr is the only signal that the new release isn't actually serving requests yet — run brv restart to align the daemon.

Setup

The easiest way to configure MCP integration is through the TUI's /connectors command, which sets up the MCP configuration for your coding agent automatically.

For manual setup and supported agents, see Coding Agent Connectors. For details on how the MCP server connects to the daemon and reuses the agent pool, see Daemon-First Architecture.

Curate History (brv curate view)

The brv curate view command lets you inspect curate operation history — useful for CI/CD audit trails, debugging failed curations, and verifying what was curated.

brv curate view [id] [--status <status>...] [--since <time>] [--before <time>] [--limit <n>] [--detail] [--format json]

Flag	Description	Default
--status <status>	Filter by status: cancelled, completed, error, processing (repeatable)	All
--since <time>	Show entries after this time (ISO date or relative: 1h, 24h, 7d)	—
--before <time>	Show entries before this time (ISO date or relative)	—
--limit <n>	Maximum number of entries to return	10
--detail	Include operations for each entry	false

Pass an entry ID as the first argument to view a single entry in detail.

Examples:

# View recent curate history
brv curate view --format json

# Check only completed curations from the last hour
brv curate view --status completed --since 1h --format json

# View a specific curate entry
brv curate view cur-1739700001000 --format json

# CI audit: verify last 5 curations succeeded
brv curate view --limit 5 --status completed --status error --format json

CI/CD Integration

All CLI commands work in CI/CD environments out of the box. The daemon auto-starts, handles execution, and shuts down after 30 minutes of inactivity — no cleanup step needed.

Common Patterns

Local-only (no auth needed):

1. Install ByteRover CLI
2. Connect a provider (or use the built-in — requires brv login first)
3. Run commands (query, curate, status)

Cloud sync (auth required):

1. Install ByteRover CLI
2. Authenticate with an API key
3. Set up space for the project
4. Run commands (query, curate, push, pull)

Workflow Examples

Local-Only

No ByteRover authentication needed when using your own API key. To use the built-in ByteRover provider in CI/CD, add a brv login step first.

name: Curate Build Context

on:
  push:
    branches: [main]

jobs:
  curate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Install ByteRover CLI
        run: curl -fsSL https://byterover.dev/install.sh | sh

      - name: Connect provider
        run: brv providers connect openrouter --api-key ${{ secrets.OPENROUTER_API_KEY }} --model anthropic/claude-sonnet-4-20250514

      - name: Curate build context
        run: brv curate "CI build passed on main — commit ${{ github.sha }}" --format json

GitHub Actions (Cloud Sync)

Includes authentication for push/pull to ByteRover cloud using Git-Semantic version control.

name: Sync Context Tree

on:
  push:
    branches: [main]

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Install ByteRover CLI
        run: curl -fsSL https://byterover.dev/install.sh | sh

      - name: Authenticate
        run: brv login --api-key ${{ secrets.BYTEROVER_API_KEY }} --format json

      - name: Clone space
        run: brv vc clone https://byterover.dev/${{ vars.BRV_TEAM }}/${{ vars.BRV_SPACE }}.git

      - name: Configure identity
        run: |
          brv vc config user.name "CI Bot"
          brv vc config user.email "ci@example.com"

      - name: Pull latest context
        run: brv vc pull

      - name: Curate build context
        run: brv curate "CI build passed on main — commit ${{ github.sha }}" --format json

      - name: Stage, commit, and push
        run: |
          brv vc add .
          brv vc commit -m "ci: update context for ${{ github.sha }}"
          brv vc push

GitLab CI (Cloud Sync)

sync-context:
  image: node:20
  stage: deploy
  only:
    - main
  script:
    - curl -fsSL https://byterover.dev/install.sh | sh
    - brv login --api-key $BYTEROVER_API_KEY --format json
    - brv vc clone https://byterover.dev/$BRV_TEAM/$BRV_SPACE.git
    - brv vc config user.name "CI Bot"
    - brv vc config user.email "ci@example.com"
    - brv vc pull
    - brv curate "CI build passed on main — commit $CI_COMMIT_SHA" --format json
    - brv vc add .
    - brv vc commit -m "ci: update context for $CI_COMMIT_SHA"
    - brv vc push

INFO

The cloud sync examples above use brv login, brv vc clone, brv vc push, and brv vc pull — these require authentication. If you only need local operations (curate, query, status), skip the authentication and clone steps.

TIP

Store your API key in your CI/CD platform's secret manager. Never commit keys to version control.

Authentication for Cloud Sync

Authentication is only required for cloud features: vc push, vc pull, vc clone, vc remote, and space list. Local operations — status, query, curate, providers, connectors, model — work without any authentication.

CI/CD and automation environments use API key authentication instead of browser-based OAuth.

Generate an API Key

1. Go to ByteRover Dashboard
2. Click Create API Key
3. Copy the key (starts with brv_)
4. Store securely in your CI/CD secrets

Secure Storage

WARNING

Never commit API keys to version control. Use environment variables or secret managers.

# Set as environment variable
export BYTEROVER_API_KEY=brv_your_api_key_here

# Use in commands
brv login --api-key "$BYTEROVER_API_KEY"

CI/CD Secret Storage:

• GitHub Actions: Repository secrets (Settings > Secrets > Actions)
• GitLab CI: CI/CD variables (Settings > CI/CD > Variables, masked)
• Jenkins: Credentials plugin with secret text

Environment & Token Storage

ByteRover stores authentication tokens as AES-256-GCM encrypted files in a platform-specific data directory:

Platform	Storage Location
macOS	~/Library/Application Support/brv/
Linux / CI runners	~/.local/share/brv/
Windows	%LOCALAPPDATA%/brv/

If storage fails due to permissions, ensure the directory exists and is writable:

# Linux / CI runners
mkdir -p ~/.local/share/brv && chmod 700 ~/.local/share/brv

# macOS
mkdir -p ~/Library/Application\ Support/brv && chmod 700 ~/Library/Application\ Support/brv

Proxy Configuration

CI/CD runners and enterprise build environments often route traffic through a corporate proxy. ByteRover CLI (v2.4.0+) respects standard proxy environment variables — set them in your pipeline and ByteRover's internal service traffic (cloud sync, hub, authentication) will route through the proxy automatically. Traffic to external LLM providers is not proxied.

GitHub Actions:

jobs:
  byterover:
    runs-on: ubuntu-latest
    env:
      HTTPS_PROXY: http://proxy.corp.com:8080
      HTTP_PROXY: http://proxy.corp.com:8080
      NO_PROXY: localhost,127.0.0.1
      NODE_EXTRA_CA_CERTS: /usr/local/share/ca-certificates/corp-ca.pem
    steps:
      - uses: actions/checkout@v4
      - run: brv query "How is auth implemented?" --format json

GitLab CI:

variables:
  HTTPS_PROXY: http://proxy.corp.com:8080
  HTTP_PROXY: http://proxy.corp.com:8080
  NO_PROXY: localhost,127.0.0.1
  NODE_EXTRA_CA_CERTS: /usr/local/share/ca-certificates/corp-ca.pem

byterover:
  script:
    - brv query "How is auth implemented?" --format json

TIP

If your CI runners use SSL inspection, set NODE_EXTRA_CA_CERTS to the path of your corporate CA certificate bundle. Without this, TLS handshakes with external services will fail.

Troubleshooting

Do I need to authenticate?

Short answer: Only for cloud sync features and the ByteRover built-in provider.

**Local operations** (`status`, `query`, `curate`, `connectors`) work without authentication. Provider and model commands also work without authentication when using third-party providers.

**Requires authentication:**

* **ByteRover built-in provider** — `brv providers connect byterover` and `brv providers switch byterover` require `brv login --api-key`.
* **Cloud operations** — `vc push`, `vc pull`, `vc clone`, `vc remote`, `space list` require `brv login --api-key`.

See [Local vs Cloud](/local-vs-cloud) for a full breakdown.

Daemon fails to start in CI/CD

Cause: Container restrictions, port access issues, or stale lock files.

**Solution:** Force a clean restart:

```bash
brv restart
```

Check daemon logs for details:

```bash
ls ~/.local/share/brv/logs/
cat ~/.local/share/brv/logs/server-*.log | tail -50
```

Space not configured

Cause: Running cloud commands without setting up a space first.

**Solution:** Clone a space before running cloud commands:

```bash
brv vc clone https://byterover.dev/my-team/my-space.git
```

Use `brv space list --format json` to see available teams and spaces.

Provider not configured

Cause: brv query or brv curate fails with "No provider connected".

**Solution:** Connect a provider:

```bash
# Use the built-in provider (requires brv login first)
brv login --api-key $BYTEROVER_API_KEY
brv providers connect byterover

# Or bring your own API key (no login needed)
brv providers connect openrouter --api-key $OPENROUTER_API_KEY --model anthropic/claude-sonnet-4-20250514
```

JSON output not appearing

Cause: Errors are written to stderr, not stdout.

**Solution:** Redirect both streams when capturing output:

```bash
brv status --format json 2>&1
```

Or capture them separately:

```bash
brv query "question" --format json 2>/dev/null
```

Authentication fails in CI/CD

Cause: Keychain unavailable, token expired, or incorrect API key.

**Solution:**

1. Verify the API key is correct and not expired
2. Ensure the `BYTEROVER_API_KEY` secret is properly configured in your CI/CD platform
3. Re-run `brv login --api-key $BYTEROVER_API_KEY`
4. Check that the secret is not masked in a way that corrupts special characters

Permission denied for token storage

Cause: Cannot write to ~/.local/share/brv/ directory.

**Solution:** Ensure the directory exists and is writable:

```bash
mkdir -p ~/.local/share/brv
chmod 700 ~/.local/share/brv
```

Next Steps

• Daemon-First Architecture — How the background daemon powers instant startup, agent pool reuse, and shared state

• Coding Agent Connectors — Connect coding agents like Cursor, Claude Code, and Windsurf via MCP

• CLI Reference — Complete command reference for all ByteRover CLI commands

• Troubleshooting — Common issues and solutions for ByteRover CLI