Overview - Byterover

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.

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

Quick Start

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

(Optional) Install a connector for your coding agent

brv connectors install "Claude Code"

Run commands with structured output

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

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

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"}

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):

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

Cloud sync (auth required):

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

Workflow Examples

Local-Only
GitHub Actions (Cloud Sync)
GitLab CI (Cloud Sync)

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

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

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

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.

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

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

Secure Storage

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

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 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:

brv restart

Check daemon logs for details:

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:

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:

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

brv status --format json 2>&1

Or capture them separately:

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

Authentication fails in CI/CD

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

Verify the API key is correct and not expired
Ensure the BYTEROVER_API_KEY secret is properly configured in your CI/CD platform
Re-run brv login --api-key $BYTEROVER_API_KEY
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:

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

​Quick Start

​The --format json Flag

​Supported Commands

​JSON Output Format

​Response Envelope

​Single-Response Commands

​Streaming Commands

​Error Responses

​Coding Agent Integration (brv mcp)

​How It Works

​Available MCP Tools

​Setup

​Curate History (brv curate view)

​CI/CD Integration

​Common Patterns

​Workflow Examples

​Authentication for Cloud Sync

​Generate an API Key

​Secure Storage

​Environment & Token Storage

​Proxy Configuration

​Troubleshooting

​Next Steps

Daemon-First Architecture

Coding Agent Connectors

CLI Reference

Troubleshooting

Quick Start

The `--format json` Flag

Supported Commands

JSON Output Format

Response Envelope

Single-Response Commands

Streaming Commands

Error Responses

Coding Agent Integration (`brv mcp`)

How It Works

Available MCP Tools

Setup

Curate History (`brv curate view`)

CI/CD Integration

Common Patterns

Workflow Examples

Authentication for Cloud Sync

Generate an API Key

Secure Storage

Environment & Token Storage

Proxy Configuration

Troubleshooting

Next Steps