Overview

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

The free built-in provider works out of the box — no API key needed. To bring your own:

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 push`	`--branch`	Yes	Push context tree to cloud
`brv pull`	`--branch`	Yes	Pull context tree from cloud
`brv space switch`	`--team`, `--name`	Yes	Switch to a team and space
`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 LLM provider). 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, push, pull, and space switch 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 push --format json | jq '.data | {status, added, edited, deleted}'

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

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 free built-in)
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 authentication needed — uses the built-in provider or your own API key for local operations only.

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.

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: Set up space
        run: brv space switch --team "${{ vars.BRV_TEAM }}" --name "${{ vars.BRV_SPACE }}" --format json

      - name: Pull latest context
        run: brv pull --format json

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

      - name: Push context tree
        run: brv push --format json

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 space switch --team "$BRV_TEAM" --name "$BRV_SPACE" --format json
    - brv pull --format json
    - brv curate "CI build passed on main — commit $CI_COMMIT_SHA" --format json
    - brv push --format json

The cloud sync examples above use brv login, brv push, and brv pull — these require authentication. If you only need local operations (curate, query, status), skip the authentication and space setup 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: push, pull, space switch, 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

Troubleshooting

Do I need to authenticate?

Short answer: Only for cloud sync features.Local operations (status, query, curate, providers, connectors, model) work without authentication.Cloud operations (push, pull, space switch, 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: Switch to a space before running cloud commands:

brv space switch --team my-team --name my-space

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 free built-in provider
brv providers connect byterover

# Or bring your own API key
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

Getting Started

LLM Providers

Agent Connectors

Context Tree

Autonomous Agents

BRV Hub

Headless Mode

Daemon-First Architecture

Reference

FAQs

Security

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

Troubleshooting

Next Steps

Daemon-First Architecture

Coding Agent Connectors

CLI Reference

Troubleshooting

Getting Started

LLM Providers

Agent Connectors

Context Tree

Autonomous Agents

BRV Hub

Headless Mode

Daemon-First Architecture

Reference

FAQs

Security

​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

​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

Troubleshooting

Next Steps