> ## Documentation Index
> Fetch the complete documentation index at: https://docs-dev.byterover.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

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

In ByteRover CLI v2.0.0, the [daemon-first architecture](/daemon-first-architecture/overview) 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.
</Note>

## Quick Start

<Steps>
  <Step title="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):

    ```bash theme={null}
    brv providers connect openrouter --api-key $OPENROUTER_API_KEY --model anthropic/claude-sonnet-4-20250514
    ```
  </Step>

  <Step title="(Optional) Install a connector for your coding agent">
    ```bash theme={null}
    brv connectors install "Claude Code"
    ```
  </Step>

  <Step title="Run commands with structured output">
    ```bash theme={null}
    brv query "How is auth implemented?" --format json
    ```
  </Step>
</Steps>

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

## 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](/local-vs-cloud) for a full breakdown.
</Note>

For full command syntax, flags, and examples, see the [CLI Reference](/reference/cli-reference). For detailed provider and model management, see [External LLM Providers](/external-llm-providers/overview). For the skills and bundles registry, see [BRV Hub](/brv-hub/overview).

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

```typescript theme={null}
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:

```json theme={null}
{"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:

```json theme={null}
{"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`:

```json theme={null}
{"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:

  ```bash theme={null}
  brv status --format json | jq '.data.spaceName'
  brv vc status | jq '.currentBranch'
  ```
</Tip>

## 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](/connectors/overview). For details on how the MCP server connects to the daemon and reuses the agent pool, see [Daemon-First Architecture](/daemon-first-architecture/overview).

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

```bash theme={null}
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:**

```bash theme={null}
# 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

<Tabs>
  <Tab title="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.

    ```yaml theme={null}
    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
    ```
  </Tab>

  <Tab title="GitHub Actions (Cloud Sync)">
    Includes authentication for push/pull to ByteRover cloud using Git-Semantic version control.

    ```yaml theme={null}
    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
    ```
  </Tab>

  <Tab title="GitLab CI (Cloud Sync)">
    ```yaml theme={null}
    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
    ```
  </Tab>
</Tabs>

<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.
</Info>

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

## 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](https://app.byterover.dev/settings/keys)
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.
</Warning>

```bash theme={null}
# 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:

```bash theme={null}
# 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:**

```yaml theme={null}
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:**

```yaml theme={null}
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.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Daemon fails to start in CI/CD">
    **Cause:** Container restrictions, port access issues, or stale lock files.

    **Solution:** Force a clean restart:

    ```bash theme={null}
    brv restart
    ```

    Check daemon logs for details:

    ```bash theme={null}
    ls ~/.local/share/brv/logs/
    cat ~/.local/share/brv/logs/server-*.log | tail -50
    ```
  </Accordion>

  <Accordion title="Space not configured">
    **Cause:** Running cloud commands without setting up a space first.

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

    ```bash theme={null}
    brv vc clone https://byterover.dev/my-team/my-space.git
    ```

    Use `brv space list --format json` to see available teams and spaces.
  </Accordion>

  <Accordion title="Provider not configured">
    **Cause:** `brv query` or `brv curate` fails with "No provider connected".

    **Solution:** Connect a provider:

    ```bash theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="JSON output not appearing">
    **Cause:** Errors are written to stderr, not stdout.

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

    ```bash theme={null}
    brv status --format json 2>&1
    ```

    Or capture them separately:

    ```bash theme={null}
    brv query "question" --format json 2>/dev/null
    ```
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="Permission denied for token storage">
    **Cause:** Cannot write to `~/.local/share/brv/` directory.

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

    ```bash theme={null}
    mkdir -p ~/.local/share/brv
    chmod 700 ~/.local/share/brv
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Daemon-First Architecture" icon="server" href="/daemon-first-architecture/overview">
    How the background daemon powers instant startup, agent pool reuse, and shared state
  </Card>

  <Card title="Coding Agent Connectors" icon="plug" href="/connectors/overview">
    Connect coding agents like Cursor, Claude Code, and Windsurf via MCP
  </Card>

  <Card title="CLI Reference" icon="book" href="/reference/cli-reference">
    Complete command reference for all ByteRover CLI commands
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/faqs/troubleshooting">
    Common issues and solutions for ByteRover CLI
  </Card>
</CardGroup>