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

# CLI reference

> Complete reference for all ByteRover CLI commands, flags, and examples

ByteRover CLI (`brv`) manages your AI development workflow — context curation, querying, version control, LLM provider and model management, cloud sync, and coding agent integration. With the [daemon-first architecture](/daemon-first-architecture/overview), every command works standalone without requiring an interactive session.

<Note>
  **v3.0.0 migration:** `brv push`, `brv pull`, `brv space switch`, and `/reset` are deprecated. Use Git-Semantic version control commands (`brv vc push`, `brv vc pull`, `brv vc remote set-url`, `brv vc reset`) instead. See [Git-Semantic Version Control](/git-semantic/overview) for the full guide and [Command Reference](/git-semantic/command-reference) for all `brv vc` commands.
</Note>

For help with any command, run `brv --help` or `brv <command> --help`.

## Getting Started

ByteRover CLI offers two ways to interact: the **interactive TUI** and **standalone CLI commands**.

### Interactive TUI

Start the terminal UI by running `brv` with no arguments:

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

This launches a persistent session with a React/Ink-based interface where you can use slash commands (e.g., `/curate`, `/query`, `/providers`). First-time users get an interactive onboarding flow. Press `Esc` to cancel streaming responses or skip onboarding.

### Standalone CLI Commands

In v2.0.0, every `brv` command auto-starts the background daemon if needed. No TUI session required. Use `--format json` for structured output in scripts and CI/CD pipelines.

```bash theme={null}
brv query "How is auth implemented?"          # Auto-starts daemon, runs query, returns result
brv curate "JWT tokens expire in 24h" -f src/auth.ts  # Curate context with file reference
brv providers connect anthropic --api-key sk-xxx       # Connect an LLM provider
brv status --format json                               # Structured output for scripting
```

### Command Overview

| Command                | Description                                                                                                                               |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `brv`                  | Start interactive TUI                                                                                                                     |
| `brv login`            | Authenticate with API key                                                                                                                 |
| `brv status`           | Show CLI and project status                                                                                                               |
| `brv locations`        | List registered projects and context tree status                                                                                          |
| `brv restart`          | Restart the background daemon                                                                                                             |
| `brv query`            | Query the context tree                                                                                                                    |
| `brv curate`           | Curate context to the context tree                                                                                                        |
| `brv curate view`      | View curate operation history                                                                                                             |
| `brv review`           | Show or toggle the project-scoped HITL review log                                                                                         |
| `brv review pending`   | List pending review operations                                                                                                            |
| `brv review approve`   | Approve pending review operations for a task                                                                                              |
| `brv review reject`    | Reject pending review operations for a task                                                                                               |
| `brv vc init`          | Initialize version control                                                                                                                |
| `brv vc config`        | Get or set commit author identity                                                                                                         |
| `brv vc clone`         | Clone a remote space                                                                                                                      |
| `brv vc add`           | Stage files for commit                                                                                                                    |
| `brv vc commit`        | Save staged changes as a commit                                                                                                           |
| `brv vc status`        | Show working tree status                                                                                                                  |
| `brv vc diff`          | Show context tree changes — staged, unstaged, or between refs                                                                             |
| `brv vc log`           | Show commit history                                                                                                                       |
| `brv vc reset`         | Unstage files or undo commits                                                                                                             |
| `brv vc branch`        | List, create, or delete branches                                                                                                          |
| `brv vc checkout`      | Switch branches                                                                                                                           |
| `brv vc merge`         | Merge branches                                                                                                                            |
| `brv vc remote`        | Manage remote connection                                                                                                                  |
| `brv vc fetch`         | Fetch refs from cloud                                                                                                                     |
| `brv vc pull`          | Pull commits from cloud (fetch + merge)                                                                                                   |
| `brv vc push`          | Push commits to cloud                                                                                                                     |
| `brv worktree add`     | Link a directory to share this project's context tree                                                                                     |
| `brv worktree list`    | Show worktree status and registrations                                                                                                    |
| `brv worktree remove`  | Remove a worktree link                                                                                                                    |
| `brv source add`       | Add a read-only knowledge source from another project                                                                                     |
| `brv source list`      | Show configured sources and validation status                                                                                             |
| `brv source remove`    | Remove a knowledge source reference                                                                                                       |
| `brv swarm onboard`    | Interactive setup wizard for Memory Swarm providers                                                                                       |
| `brv swarm status`     | Check Memory Swarm provider health and write targets                                                                                      |
| `brv swarm query`      | Search across all active memory providers                                                                                                 |
| `brv swarm curate`     | Store knowledge in the best available provider                                                                                            |
| `brv providers`        | Manage LLM providers                                                                                                                      |
| `brv model`            | Manage LLM models                                                                                                                         |
| `brv connectors`       | Manage coding agent connectors                                                                                                            |
| `brv hub`              | Browse and install skills and bundles                                                                                                     |
| `brv settings`         | [Inspect and override runtime settings](/reference/brv-settings) — agent pool, LLM time budgets, task-history retention                   |
| `brv space`            | Manage teams and spaces                                                                                                                   |
| `brv vc *`             | [Git-Semantic version control](/git-semantic/command-reference) — init, add, commit, reset, branch, checkout, merge, push, pull, and more |
| ~~`brv push`~~         | ~~Push context tree to cloud~~ **(deprecated in v3.0.0 — use `brv vc push`)**                                                             |
| ~~`brv pull`~~         | ~~Pull context tree from cloud~~ **(deprecated in v3.0.0 — use `brv vc pull`)**                                                           |
| ~~`brv space switch`~~ | ~~Switch active space~~ **(deprecated in v3.0.0 — use `brv vc remote set-url origin <url>`)**                                             |

## Environment Variables

ByteRover CLI auto-detects API keys from environment variables (e.g., `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`). The following additional environment variables configure network and proxy behavior:

| Variable              | Description                                                               | Example                      |
| --------------------- | ------------------------------------------------------------------------- | ---------------------------- |
| `HTTPS_PROXY`         | Proxy server for HTTPS traffic                                            | `http://proxy.corp.com:8080` |
| `HTTP_PROXY`          | Proxy server for HTTP traffic                                             | `http://proxy.corp.com:8080` |
| `NO_PROXY`            | Comma-separated list of hosts that bypass the proxy                       | `localhost,127.0.0.1`        |
| `NODE_EXTRA_CA_CERTS` | Path to additional CA certificates (e.g., corporate SSL inspection certs) | `/etc/ssl/certs/corp-ca.pem` |
| `BYTEROVER_API_KEY`   | API key for cloud sync in headless/CI environments                        | `brv_your_api_key_here`      |

<Note>
  Proxy support requires ByteRover CLI v2.4.0 or later. See [Troubleshooting — Proxy Configuration](/faqs/troubleshooting#how-do-i-configure-byterover-cli-to-work-behind-a-corporate-proxy) for setup details.
</Note>

***

## CLI Command Reference

### `brv`

Start the interactive TUI with a React/Ink-based terminal interface.

**Arguments:** None

**Flags:** None

**Examples**

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

<Note>Press `Esc` to cancel streaming responses. Press `Ctrl+C` to exit.</Note>

***

### `brv login`

Authenticate with ByteRover for cloud sync features. By default, opens your browser for OAuth sign-in. On CI, SSH, or other non-interactive shells (auto-detected), pass `--api-key <key>` instead. Authentication is optional for local-only usage.

**Arguments:** None

**Flags**

| Flag                    | Description                                                                             | Default           |
| ----------------------- | --------------------------------------------------------------------------------------- | ----------------- |
| `-k, --api-key <key>`   | API key for authentication — use on CI or remote shells where a browser isn't available | — (browser OAuth) |
| `--format <text\|json>` | Output format                                                                           | `text`            |

**Examples**

```bash theme={null}
# Interactive: opens your browser for OAuth
brv login

# CI / SSH / non-interactive: pass an API key
brv login --api-key brv_your_api_key_here
brv login --api-key brv_your_api_key_here --format json
```

<Note>
  Get an API key from [app.byterover.dev/settings/keys](https://app.byterover.dev/settings/keys). SSH and non-interactive shells are detected automatically and skip the browser step — if you see a "not an interactive terminal" message, use `--api-key`.
</Note>

***

### `brv logout`

Disconnect from ByteRover cloud and clear stored credentials. This is the non-interactive counterpart to the `/logout` TUI slash command.

**Arguments:** None

**Flags**

| Flag                    | Description   | Default |
| ----------------------- | ------------- | ------- |
| `--format <text\|json>` | Output format | `text`  |

**Examples**

```bash theme={null}
brv logout
brv logout --format json
```

<Note>
  You can log back in at any time with `brv login` (browser OAuth) or `brv login --api-key <key>` on CI / SSH. Logging out does not delete your local context tree — it only clears cloud credentials.
</Note>

***

### `brv locations`

List all registered projects and their context tree status — which are initialized, which is current, and which have active connections.

**Arguments:** None

**Flags**

| Flag                        | Description   | Default |
| --------------------------- | ------------- | ------- |
| `-f, --format <text\|json>` | Output format | `text`  |

**Examples**

```bash theme={null}
brv locations
brv locations --format json
```

**Notes**

* Projects are sorted: current first, then active, then initialized, then the rest
* The `[current]` label marks the project you're running from; `[active]` marks projects with connected clients

***

### `brv status`

Show CLI version, authentication state, project configuration, and context tree status.

**Arguments:** None

**Flags**

| Flag                        | Description   | Default |
| --------------------------- | ------------- | ------- |
| `-f, --format <text\|json>` | Output format | `text`  |

**Examples**

```bash theme={null}
brv status
brv status --format json
```

***

### `brv restart`

Restart ByteRover — stop everything and start fresh. Run this when ByteRover is unresponsive, stuck, or after installing an update. All open sessions and background processes are stopped. The daemon will restart automatically on the next `brv` command.

Also use it when the REPL header shows `[outdated, daemon vX.Y.Z]` after an upgrade — that tag means the background daemon is still on the previous CLI version.

**Arguments:** None

**Flags:** None

**Examples**

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

***

### `brv query`

Query the context tree using natural language. Auto-starts the daemon if not already running.

**Arguments**

| Argument | Type   | Required | Description                                  |
| -------- | ------ | -------- | -------------------------------------------- |
| `query`  | string | Yes      | Natural language question about your project |

**Flags**

| Flag                    | Description                                                                                       | Default |
| ----------------------- | ------------------------------------------------------------------------------------------------- | ------- |
| `--cancel <taskId>`     | Cancel a running query task by ID instead of starting a new one. The `query` argument is ignored. | —       |
| `--format <text\|json>` | Output format                                                                                     | `text`  |

**Examples**

```bash theme={null}
brv query "How is user authentication implemented?"
brv query "What testing strategies are used?"
brv query "What are the API endpoints?" --format json

# Cancel a task started from another terminal or with --detach
brv query --cancel qry-1739700001000
```

**Notes**

* Uses a multi-tier retrieval strategy: exact cache, fuzzy cache, direct search, then LLM synthesis
* Best results with specific, detailed questions
* With `--format json`, emits streaming JSON lines — see [Headless Mode](/headless-mode/overview) for the output format
* **Cancelling a running task**: in the foreground, press `Ctrl+C` once to gracefully cancel the running task (stderr shows `Cancelling task... (Ctrl-C again to force exit)`). A second press hard-exits with code 130. To cancel a task started elsewhere (other terminal, `--detach`, REPL), run `brv query --cancel <taskId>`.

***

### `brv curate`

Curate knowledge into the context tree. When `context`, `--files`, or `--folder` is provided, runs in autonomous mode with AI classification.

**Arguments**

| Argument  | Type   | Required | Description                                               |
| --------- | ------ | -------- | --------------------------------------------------------- |
| `context` | string | No       | Knowledge to store — triggers autonomous mode if provided |

**Flags**

| Flag                    | Description                                                                                                            | Default |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------- |
| `-f, --files <path>`    | File path to include (repeatable, max 5)                                                                               | —       |
| `-d, --folder <path>`   | Folder path to pack and analyze                                                                                        | —       |
| `--detach`              | Queue the task and return immediately without waiting for completion                                                   | `false` |
| `--cancel <taskId>`     | Cancel a running curate task by ID instead of starting a new one. The `context` argument and other inputs are ignored. | —       |
| `--format <text\|json>` | Output format                                                                                                          | `text`  |

**Examples**

```bash theme={null}
# Autonomous mode with AI classification
brv curate "JWT tokens expire in 24h"
brv curate "React components follow atomic design" --format json

# Include file references
brv curate "Session handling logic" -f src/auth/session.ts
brv curate "Auth implementation" -f src/auth.ts -f src/middleware/auth.ts

# Folder pack — analyze and curate entire folder
brv curate "Auth module overview" -d src/auth/
brv curate -d src/auth/

# Fire-and-forget for CI/CD
brv curate "Build passed: commit abc1234" --detach --format json

# Cancel a task started from another terminal or with --detach
brv curate --cancel cur-1739700001000
```

**Notes**

* **Autonomous mode** (with context): The AI agent determines the best domain/topic and writes structured markdown to the context tree
* **Interactive mode** (without context): Available in the TUI only — navigate the context tree and select where to curate
* **File references**: Up to 5 files with `-f` / `--files`. Files must be text files within the project directory
* **Folder pack**: The `-d` / `--folder` flag packs a single folder's contents (code, config, docs, PDFs, Office files) into a structured format for analysis
* **Detached mode**: Use `--detach` in CI/CD pipelines to queue curation and exit immediately
* **Cancelling a running task**: in the foreground, press `Ctrl+C` once to gracefully cancel the running task (stderr shows `Cancelling task... (Ctrl-C again to force exit)`). A second press hard-exits with code 130. To cancel a task started elsewhere (other terminal, `--detach`, REPL), run `brv curate --cancel <taskId>`.

***

### `brv curate view`

View curate operation history and detailed logs. Useful for auditing curations and debugging failures.

**Arguments**

| Argument | Type   | Required | Description                    |
| -------- | ------ | -------- | ------------------------------ |
| `id`     | string | No       | Log entry ID to view in detail |

**Flags**

| Flag                    | Description                                                                          | Default |
| ----------------------- | ------------------------------------------------------------------------------------ | ------- |
| `--since <time>`        | Show entries after this time (ISO date or relative: `30m`, `1h`, `24h`, `7d`, `2w`)  | —       |
| `--before <time>`       | Show entries before this time (ISO date or relative: `30m`, `1h`, `24h`, `7d`, `2w`) | —       |
| `--status <status>`     | Filter by status (repeatable): `cancelled`, `completed`, `error`, `processing`       | All     |
| `--detail`              | Show operations for each entry in list view                                          | `false` |
| `--limit <n>`           | Maximum number of entries to display (minimum 1)                                     | `10`    |
| `--format <text\|json>` | Output format                                                                        | `text`  |

**Examples**

```bash theme={null}
# List recent curate operations
brv curate view

# Filter by status and time
brv curate view --status completed --since 1h
brv curate view --status completed --status error --limit 5

# View a specific entry in detail
brv curate view cur-1739700001000

# JSON output for scripting
brv curate view --format json
```

***

### `brv review`

Show or toggle the project-scoped HITL (human-in-the-loop) review log. With no flags, prints whether the log is currently enabled or disabled. Pass `--disable` or `--enable` to change it. Persists across CLI and daemon restarts. See [Review Changes](/review/overview) for the full review workflow.

**Arguments:** None

**Flags**

| Flag                    | Description                                                                     | Default |
| ----------------------- | ------------------------------------------------------------------------------- | ------- |
| `--disable`             | Disable the review log for this project (mutually exclusive with `--enable`)    | `false` |
| `--enable`              | Re-enable the review log for this project (mutually exclusive with `--disable`) | `false` |
| `--format <text\|json>` | Output format                                                                   | `text`  |

**Examples**

```bash theme={null}
# Show current state
brv review

# Disable for unattended workflows (--detach curates, autonomous agents, headless CI)
brv review --disable

# Re-enable
brv review --enable

# Structured output
brv review --format json
```

**Notes**

* When disabled: `brv curate` skips the "*N* operations require review" prompt, `--detach` curate-log entries omit the per-operation review marker, `brv dream` no longer surfaces `needsReview` operations, and no review backups are written.
* Pending reviews created before the log was disabled remain visible in `brv review pending` and can still be approved or rejected.
* See [Disable the review log](/review/manage-reviews#disable-the-review-log) for the full behavior.

***

### `brv review pending`

List all pending review operations for the current project, grouped by task.

**Arguments:** None

**Flags**

| Flag                    | Description   | Default |
| ----------------------- | ------------- | ------- |
| `--format <text\|json>` | Output format | `text`  |

**Examples**

```bash theme={null}
# List pending reviews
brv review pending

# Structured output for agent-driven workflows
brv review pending --format json
```

***

### `brv review approve`

Approve pending review operations for a curate task. The current file content becomes the new baseline and the pre-change backup is deleted.

**Arguments**

| Argument | Type   | Required | Description                        |
| -------- | ------ | -------- | ---------------------------------- |
| `taskId` | string | Yes      | Task ID shown in the curate output |

**Flags**

| Flag                    | Description                                                                      | Default |
| ----------------------- | -------------------------------------------------------------------------------- | ------- |
| `--file <path>`         | Approve only the specified file path (repeatable, relative to context tree root) | —       |
| `--format <text\|json>` | Output format                                                                    | `text`  |

**Examples**

```bash theme={null}
# Approve all pending changes for a task
brv review approve abc-123

# Approve specific files only
brv review approve abc-123 --file architecture/security/audit.md
brv review approve abc-123 --file auth/jwt.md --file auth/oauth.md

# Structured output
brv review approve abc-123 --format json
```

***

### `brv review reject`

Reject pending review operations for a curate task. Files are restored from the pre-change backup, deleted files are restored to disk, and the change is discarded.

**Arguments**

| Argument | Type   | Required | Description                        |
| -------- | ------ | -------- | ---------------------------------- |
| `taskId` | string | Yes      | Task ID shown in the curate output |

**Flags**

| Flag                    | Description                                                                     | Default |
| ----------------------- | ------------------------------------------------------------------------------- | ------- |
| `--file <path>`         | Reject only the specified file path (repeatable, relative to context tree root) | —       |
| `--format <text\|json>` | Output format                                                                   | `text`  |

**Examples**

```bash theme={null}
# Reject all pending changes for a task
brv review reject abc-123

# Reject specific files only
brv review reject abc-123 --file architecture/security/audit.md

# Structured output
brv review reject abc-123 --format json
```

**Notes**

* **DELETE rejection** restores the deleted file (or folder contents) to disk.
* **MERGE rejection** restores both the target file and the deleted source file.

***

### `brv swarm onboard`

Interactive setup wizard for Memory Swarm. Detects available providers, guides configuration, sets enrichment topology, and writes `.brv/swarm/config.yaml`.

**Arguments:** None

**Examples**

```bash theme={null}
brv swarm onboard
```

See [Memory Swarm Setup](/memory-swarm/setup) for full details.

***

### `brv swarm status`

Check Memory Swarm provider health, write targets, and configuration status.

**Arguments:** None

**Flags**

| Flag                    | Description   | Default |
| ----------------------- | ------------- | ------- |
| `--format <text\|json>` | Output format | `text`  |

**Examples**

```bash theme={null}
brv swarm status
brv swarm status --format json
```

***

### `brv swarm query`

Search across all active memory providers. Results are ranked using Reciprocal Rank Fusion (RRF). No LLM call — pure algorithmic search.

**Arguments**

| Argument | Description                 |
| -------- | --------------------------- |
| `query`  | The search query (required) |

**Flags**

| Flag                        | Description                                                           | Default |
| --------------------------- | --------------------------------------------------------------------- | ------- |
| `--explain`                 | Show query classification, provider selection, and enrichment details | off     |
| `--format <text\|json>`     | Output format                                                         | `text`  |
| `-n, --max-results <count>` | Maximum number of results                                             | `10`    |

**Examples**

```bash theme={null}
brv swarm query "How does JWT refresh work?"
brv swarm query "authentication patterns" --explain
brv swarm query "rate limiting" --format json
brv swarm query "testing strategy" -n 5
```

See [Memory Swarm Query](/memory-swarm/query) for full details.

***

### `brv swarm curate`

Store knowledge in the best available external memory provider. Falls back to ByteRover context tree if no writable providers are available.

**Arguments**

| Argument  | Description                       |
| --------- | --------------------------------- |
| `content` | The knowledge to store (required) |

**Flags**

| Flag                    | Description                                                         | Default |
| ----------------------- | ------------------------------------------------------------------- | ------- |
| `-p, --provider <id>`   | Target a specific provider (e.g., `gbrain`, `local-markdown:notes`) | auto    |
| `--format <text\|json>` | Output format                                                       | `text`  |

**Examples**

```bash theme={null}
brv swarm curate "Jane Smith is the CTO of TechCorp"
brv swarm curate "meeting notes: decided on JWT" --provider local-markdown:notes
brv swarm curate "Architecture uses event sourcing" -p gbrain --format json
```

See [Memory Swarm Curate](/memory-swarm/curate) for full details.

***

### `brv push`

<Warning>
  **Deprecated in v3.0.0.** Use `brv vc push` instead. See [Git-Semantic Remote Sync](/git-semantic/remote-sync) and [Command Reference](/git-semantic/command-reference). If Git-Semantic version control is initialized, this command is blocked with a `VC_GIT_INITIALIZED` error.
</Warning>

Push the local context tree to ByteRover cloud storage. Requires authentication.

**Arguments:** None

**Flags**

| Flag                    | Description                            | Default |
| ----------------------- | -------------------------------------- | ------- |
| `-b, --branch <name>`   | ByteRover branch name (not Git branch) | `main`  |
| `--format <text\|json>` | Output format                          | `text`  |

**Examples**

```bash theme={null}
brv push
brv push --branch feature-auth
brv push --format json
```

***

### `brv pull`

<Warning>
  **Deprecated in v3.0.0.** Use `brv vc pull` instead. See [Git-Semantic Remote Sync](/git-semantic/remote-sync) and [Command Reference](/git-semantic/command-reference). If Git-Semantic version control is initialized, this command is blocked with a `VC_GIT_INITIALIZED` error.
</Warning>

Pull the context tree from ByteRover cloud storage. Requires authentication.

**Arguments:** None

**Flags**

| Flag                    | Description                            | Default |
| ----------------------- | -------------------------------------- | ------- |
| `-b, --branch <name>`   | ByteRover branch name (not Git branch) | `main`  |
| `--format <text\|json>` | Output format                          | `text`  |

**Examples**

```bash theme={null}
brv pull
brv pull --branch feature-auth
brv pull --format json
```

***

### `brv providers`

Show the currently active LLM provider and model. Use sub-commands to list, connect, disconnect, or switch providers.

**Arguments:** None

**Flags**

| Flag                    | Description   | Default |
| ----------------------- | ------------- | ------- |
| `--format <text\|json>` | Output format | `text`  |

**Examples**

```bash theme={null}
brv providers
brv providers --format json
```

***

### `brv providers list`

List all available LLM providers with their connection status. Each provider is shown with a short description (e.g., what its models are known for) so you can pick by capability rather than brand recognition. Connected providers display `[OAuth]` or `[API Key]` badges indicating their authentication method.

**Arguments:** None

**Flags**

| Flag                    | Description   | Default |
| ----------------------- | ------------- | ------- |
| `--format <text\|json>` | Output format | `text`  |

**Examples**

```bash theme={null}
brv providers list
brv providers list --format json
```

***

### `brv providers connect`

Connect to an LLM provider and optionally set the active model.

**Arguments**

| Argument   | Type   | Required | Description                                                                  |
| ---------- | ------ | -------- | ---------------------------------------------------------------------------- |
| `provider` | string | Yes      | Provider ID (e.g., `anthropic`, `openai`, `openrouter`, `openai-compatible`) |

**Flags**

| Flag                    | Description                                                                       | Default |
| ----------------------- | --------------------------------------------------------------------------------- | ------- |
| `-k, --api-key <key>`   | API key for the provider                                                          | —       |
| `--oauth`               | Connect via OAuth (browser-based authentication)                                  | `false` |
| `-b, --base-url <url>`  | Base URL for OpenAI-compatible providers (e.g., `http://localhost:11434/v1`)      | —       |
| `-m, --model <id>`      | Set the active model after connecting                                             | —       |
| `--team <name>`         | Pin this project to a billing team (`byterover` only). Accepts team name or slug. | —       |
| `--format <text\|json>` | Output format                                                                     | `text`  |

**Examples**

```bash theme={null}
# Connect with API key
brv providers connect anthropic --api-key sk-xxx
brv providers connect openrouter --api-key sk-xxx --model claude-sonnet-4-5

# Connect via OAuth (opens browser for authentication)
brv providers connect openai --oauth

# Connect to local models via OpenAI-compatible endpoint
brv providers connect openai-compatible --base-url http://localhost:11434/v1
brv providers connect openai-compatible --base-url http://localhost:11434/v1 --api-key sk-xxx --model llama3

# Switch to the built-in provider (requires brv login)
brv providers connect byterover

# Pin this project to a paid team's credits (byterover only; accepts name or slug)
brv providers connect byterover --team acme
```

**Notes**

* API keys are stored securely.
* OpenAI supports OAuth authentication. Use `--oauth` to sign in via your browser instead of providing an API key. Cannot be combined with `--api-key`.
* The **ByteRover** built-in provider requires a logged-in ByteRover account. Run `brv login` before connecting. Third-party providers only require an API key — no ByteRover login needed.
* `--team <name>` is only supported for `byterover`. Passing it to any other provider fails with `--team is only supported for the "byterover" provider.` Matching is case-insensitive against team name first, then slug. On success the CLI prints `ByteRover usage on this project will be billed to <team>.`
* ByteRover CLI auto-detects API keys from environment variables (e.g., `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`)
* If the server rejects the connection (e.g., missing authentication), the error is displayed in the command output.
* See [LLM Providers](/external-llm-providers/overview) for the full list of supported providers and environment variables

***

### `brv providers disconnect`

Disconnect an LLM provider and remove its stored API key.

**Arguments**

| Argument   | Type   | Required | Description               |
| ---------- | ------ | -------- | ------------------------- |
| `provider` | string | Yes      | Provider ID to disconnect |

**Flags**

| Flag                    | Description   | Default |
| ----------------------- | ------------- | ------- |
| `--format <text\|json>` | Output format | `text`  |

**Examples**

```bash theme={null}
brv providers disconnect openrouter
```

***

### `brv providers switch`

Switch the active provider. The provider must already be connected.

**Arguments**

| Argument   | Type   | Required | Description              |
| ---------- | ------ | -------- | ------------------------ |
| `provider` | string | Yes      | Provider ID to switch to |

**Flags**

| Flag                    | Description   | Default |
| ----------------------- | ------------- | ------- |
| `--format <text\|json>` | Output format | `text`  |

**Examples**

```bash theme={null}
brv providers switch anthropic
brv providers switch byterover
```

<Note>
  Switching to the **ByteRover** built-in provider requires authentication. Run `brv login` first if you haven't already. If authentication fails, the error is displayed in the command output.
</Note>

***

### `brv model`

Show the currently active model and provider.

**Arguments:** None

**Flags**

| Flag                    | Description   | Default |
| ----------------------- | ------------- | ------- |
| `--format <text\|json>` | Output format | `text`  |

**Examples**

```bash theme={null}
brv model
brv model --format json
```

***

### `brv model list`

List available models from all connected providers.

**Arguments:** None

**Flags**

| Flag                    | Description                   | Default       |
| ----------------------- | ----------------------------- | ------------- |
| `-p, --provider <id>`   | Filter to a specific provider | All connected |
| `--format <text\|json>` | Output format                 | `text`        |

**Examples**

```bash theme={null}
brv model list
brv model list --provider anthropic
brv model list --format json
```

***

### `brv model switch`

Switch the active model.

**Arguments**

| Argument | Type   | Required | Description           |
| -------- | ------ | -------- | --------------------- |
| `model`  | string | Yes      | Model ID to switch to |

**Flags**

| Flag                    | Description                                          | Default         |
| ----------------------- | ---------------------------------------------------- | --------------- |
| `-p, --provider <id>`   | Provider for the model (defaults to active provider) | Active provider |
| `--format <text\|json>` | Output format                                        | `text`          |

**Examples**

```bash theme={null}
brv model switch claude-sonnet-4-5
brv model switch gpt-4.1 --provider openai
```

***

### `brv connectors`

List installed coding agent connectors.

**Arguments:** None

**Flags**

| Flag                    | Description   | Default |
| ----------------------- | ------------- | ------- |
| `--format <text\|json>` | Output format | `text`  |

**Examples**

```bash theme={null}
brv connectors
brv connectors list
brv connectors --format json
```

***

### `brv connectors install`

Install or switch a connector for a coding agent. Creates the appropriate config files, rule files, or skill files for the selected agent.

**Arguments**

| Argument | Type   | Required | Description                                              |
| -------- | ------ | -------- | -------------------------------------------------------- |
| `agent`  | string | Yes      | Agent name (e.g., `"Claude Code"`, `Cursor`, `Windsurf`) |

**Flags**

| Flag                    | Description                                     | Default                  |
| ----------------------- | ----------------------------------------------- | ------------------------ |
| `-t, --type <type>`     | Connector type: `rules`, `hook`, `mcp`, `skill` | Agent's recommended type |
| `--format <text\|json>` | Output format                                   | `text`                   |

**Examples**

```bash theme={null}
# Install with agent's default connector type
brv connectors install "Claude Code"
brv connectors install Cursor

# Override connector type
brv connectors install "Claude Code" --type mcp
brv connectors install Cursor --type rules
```

**Notes**

* **Skill**: Writes SKILL.md and workflow files to agent-specific skill directories. Default for Claude Code and Cursor.
* **MCP**: Configures the MCP server (`brv mcp`) for direct tool integration. Default for most agents.
* **Rules**: Generates markdown rule files that agents read for instructions.
* **Hook**: Uses agent-specific hook systems (Claude Code only, legacy).
* See [Coding Agent Connectors](/connectors/overview) for the full supported agents table with default connector types.

***

### `brv hub`

Browse skills and bundles from the BRV Hub. Delegates to `brv hub list`.

**Arguments:** None

**Flags:** None (delegates to `brv hub list`, which accepts `--format`)

**Examples**

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

***

### `brv hub list`

List all available skills and bundles from configured registries.

**Arguments:** None

**Flags**

| Flag                        | Description   | Default |
| --------------------------- | ------------- | ------- |
| `-f, --format <text\|json>` | Output format | `text`  |

**Examples**

```bash theme={null}
brv hub list
brv hub list --format json
```

***

### `brv hub install`

Install a skill or bundle from the hub.

**Arguments**

| Argument | Type   | Required | Description         |
| -------- | ------ | -------- | ------------------- |
| `id`     | string | Yes      | Entry ID to install |

**Flags**

| Flag                        | Description                                                      | Default   |
| --------------------------- | ---------------------------------------------------------------- | --------- |
| `-a, --agent <agent>`       | Target agent for skill install (required for skills)             | —         |
| `-s, --scope <scope>`       | Install scope: `global` or `project`                             | `project` |
| `-r, --registry <name>`     | Registry to install from (when ID exists in multiple registries) | —         |
| `-f, --format <text\|json>` | Output format                                                    | `text`    |

**Examples**

```bash theme={null}
# Install a skill to a coding agent
brv hub install byterover-review --agent "Claude Code"
brv hub install byterover-plan --agent Cursor

# Install a context bundle (goes to .brv/context-tree/)
brv hub install typescript-kickstart

# Install from a specific private registry
brv hub install my-skill --registry myco --agent "Claude Code"

# Install globally
brv hub install byterover-debug --agent "Claude Code" --scope global
```

**Notes**

* **Skills** are agent-specific workflows installed to the agent's skill directory
* **Bundles** are context packs installed directly to `.brv/context-tree/`
* See [BRV Hub](/brv-hub/overview) for the full list of available skills and bundles

***

### `brv hub registry`

Manage hub registries. Delegates to `brv hub registry list`.

**Arguments:** None

**Flags:** None

**Examples**

```bash theme={null}
brv hub registry
```

***

### `brv hub registry list`

List all configured hub registries with connection status.

**Arguments:** None

**Flags**

| Flag                        | Description   | Default |
| --------------------------- | ------------- | ------- |
| `-f, --format <text\|json>` | Output format | `text`  |

**Examples**

```bash theme={null}
brv hub registry list
brv hub registry list --format json
```

***

### `brv hub registry add`

Add a custom hub registry for private skills and bundles.

**Arguments**

| Argument | Type   | Required | Description                               |
| -------- | ------ | -------- | ----------------------------------------- |
| `name`   | string | Yes      | Registry name (used in `--registry` flag) |

**Flags**

| Flag                         | Description                                                      | Default |
| ---------------------------- | ---------------------------------------------------------------- | ------- |
| `-u, --url <url>`            | Registry URL (required)                                          | —       |
| `-t, --token <token>`        | Auth token for private registries                                | —       |
| `-s, --auth-scheme <scheme>` | Auth scheme: `bearer`, `token`, `basic`, `custom-header`, `none` | —       |
| `--header-name <name>`       | Custom header name (for `custom-header` auth scheme)             | —       |
| `-f, --format <text\|json>`  | Output format                                                    | `text`  |

**Examples**

```bash theme={null}
# Add a public registry
brv hub registry add myco --url https://example.com/registry.json

# Add a private registry with token auth
brv hub registry add myco --url https://example.com/registry.json --token secret123

# Add a GitHub-hosted private registry
brv hub registry add ghrepo \
  --url https://raw.githubusercontent.com/org/repo/main/registry.json \
  --auth-scheme token --token ghp_xxx
```

<Tip>See [Custom Registries](/brv-hub/registries) for the full guide on hosting your own registry.</Tip>

***

### `brv hub registry remove`

Remove a custom registry and its stored credentials.

**Arguments**

| Argument | Type   | Required | Description             |
| -------- | ------ | -------- | ----------------------- |
| `name`   | string | Yes      | Registry name to remove |

**Flags**

| Flag                        | Description   | Default |
| --------------------------- | ------------- | ------- |
| `-f, --format <text\|json>` | Output format | `text`  |

**Examples**

```bash theme={null}
brv hub registry remove myco
```

***

### `brv space list`

<Warning>
  **Deprecated in v3.0.0.** Space management is being replaced by Git-Semantic version control. Use `brv vc remote` to manage remote connections.
</Warning>

List all available teams and spaces. Requires authentication.

**Arguments:** None

**Flags**

| Flag                        | Description   | Default |
| --------------------------- | ------------- | ------- |
| `-f, --format <text\|json>` | Output format | `text`  |

**Examples**

```bash theme={null}
brv space list
brv space list --format json
```

***

### `brv space switch`

<Warning>
  **Deprecated in v3.0.0.** Use `brv vc remote set-url origin <url>` instead. See [Git-Semantic Remote Sync](/git-semantic/remote-sync) and [Command Reference](/git-semantic/command-reference).
</Warning>

Switch to a different team and space. Requires authentication.

**Arguments:** None

**Flags**

| Flag                        | Description           | Default |
| --------------------------- | --------------------- | ------- |
| `-t, --team <name>`         | Team name (required)  | —       |
| `-n, --name <name>`         | Space name (required) | —       |
| `-f, --format <text\|json>` | Output format         | `text`  |

**Examples**

```bash theme={null}
brv space switch --team my-team --name my-space
brv space switch --team my-team --name my-space --format json
```

***

## TUI Slash Commands

These commands are available inside the interactive TUI session (start with `brv`). Slash commands provide interactive UI elements like selection prompts and real-time feedback that are not available via standalone CLI commands.

| Command                       | Aliases | Description                                                                          |
| ----------------------------- | ------- | ------------------------------------------------------------------------------------ |
| `/status`                     | —       | Show CLI status and project information                                              |
| `/locations`                  | —       | List registered projects and context tree status                                     |
| `/curate [context] [@paths]`  | —       | Curate context to the context tree                                                   |
| `/query <query>`              | —       | Query the context tree                                                               |
| `/connectors`                 | —       | Manage coding agent connectors                                                       |
| `/hub list`                   | —       | Browse and install skills and bundles                                                |
| `/hub registry list`          | —       | List configured hub registries                                                       |
| `/hub registry add <name>`    | —       | Add a hub registry                                                                   |
| `/hub registry remove <name>` | —       | Remove a hub registry                                                                |
| `/push`                       | —       | Push context tree to cloud **(deprecated — use `/vc push`)**                         |
| `/pull`                       | —       | Pull context tree from cloud **(deprecated — use `/vc pull`)**                       |
| `/providers`                  | —       | Connect to an LLM provider                                                           |
| `/model`                      | —       | Select a model from the active provider                                              |
| `/space list`                 | —       | List all spaces **(deprecated)**                                                     |
| `/space switch`               | —       | Switch to a different space **(deprecated — use `/vc remote set-url origin <url>`)** |
| `/reset`                      | —       | Reset context tree to empty **(deprecated — use `/vc reset`)**                       |
| `/new`                        | —       | Start a fresh session                                                                |
| `/login`                      | —       | Authenticate via OAuth browser flow                                                  |
| `/logout`                     | —       | Log out and clear credentials                                                        |
| `/exit`                       | —       | Exit the ByteRover REPL                                                              |

### Slash Command Details

#### `/status`

Show CLI status including authentication state, project configuration, and context tree state.

**Flags:** None

***

#### `/locations`

List all registered projects and their context tree status.

**Flags:** None

```bash theme={null}
/locations
```

***

#### `/curate`

Curate context to the context tree. Without arguments, opens interactive mode for navigating the context tree and selecting where to curate. With a context argument, runs in autonomous mode.

| Argument  | Type   | Required | Description                                  |
| --------- | ------ | -------- | -------------------------------------------- |
| `context` | string | No       | Knowledge context — triggers autonomous mode |

Use `@path` syntax to include file or folder references (up to 5 total):

```bash theme={null}
# Interactive mode
/curate

# Autonomous mode with AI classification
/curate "Authentication uses JWT with 24h expiry"

# Include file references
/curate "Session handling logic" @src/auth/session.ts @src/middleware/auth.ts

# Include folder reference
/curate "Auth module overview" @src/auth/
```

<Note>Press `Ctrl+Q` to cancel the active curate or query task. The footer shows `ctrl+q cancel task` exactly while a cancellable task is in flight. With multiple tasks in flight, Ctrl+Q targets the oldest running task (then the oldest queued) so the agent slot drains in FIFO order.</Note>

***

#### `/query`

Query the context tree using natural language.

| Argument | Type   | Required | Description               |
| -------- | ------ | -------- | ------------------------- |
| `query`  | string | Yes      | Natural language question |

```bash theme={null}
/query "How is user authentication implemented?"
/query "What testing strategies are used?"
```

<Note>Press `Ctrl+Q` to cancel the active query (or curate) task — same FIFO behaviour and footer hint as `/curate`.</Note>

***

#### `/connectors`

Manage coding agent connectors. Opens an interactive UI for selecting an agent and choosing a connector type (skill, MCP, rules, or hook).

**Flags:** None

***

#### `/hub list`

Browse available skills and bundles from the hub. Opens an interactive browser with search and one-click install.

**Flags:** None

***

#### `/hub registry list`

List all configured hub registries.

**Flags:** None

***

#### `/hub registry add`

Add a custom hub registry.

| Argument | Type   | Required | Description   |
| -------- | ------ | -------- | ------------- |
| `name`   | string | Yes      | Registry name |

| Flag                         | Description                                                      |
| ---------------------------- | ---------------------------------------------------------------- |
| `-u, --url <url>`            | Registry URL (required)                                          |
| `-t, --token <token>`        | Auth token                                                       |
| `-s, --auth-scheme <scheme>` | Auth scheme: `bearer`, `token`, `basic`, `custom-header`, `none` |
| `--header-name <name>`       | Custom header name (for `custom-header` scheme)                  |

```bash theme={null}
/hub registry add myco --url https://example.com/registry.json --token secret123
```

***

#### `/hub registry remove`

Remove a custom hub registry.

| Argument | Type   | Required | Description             |
| -------- | ------ | -------- | ----------------------- |
| `name`   | string | Yes      | Registry name to remove |

```bash theme={null}
/hub registry remove myco
```

***

#### `/push`

<Warning>
  **Deprecated in v3.0.0.** Use `/vc push` instead. See [Git-Semantic Remote Sync](/git-semantic/remote-sync).
</Warning>

Push context tree to ByteRover cloud storage.

| Flag                  | Description              | Default |
| --------------------- | ------------------------ | ------- |
| `-b, --branch <name>` | ByteRover branch name    | `main`  |
| `-y, --yes`           | Skip confirmation prompt | —       |

```bash theme={null}
/push
/push -b feature-auth
/push -y
```

***

#### `/pull`

<Warning>
  **Deprecated in v3.0.0.** Use `/vc pull` instead. See [Git-Semantic Remote Sync](/git-semantic/remote-sync).
</Warning>

Pull context tree from ByteRover cloud storage.

| Flag                  | Description           | Default |
| --------------------- | --------------------- | ------- |
| `-b, --branch <name>` | ByteRover branch name | `main`  |

```bash theme={null}
/pull
/pull -b feature-auth
```

***

#### `/providers`

Connect to an LLM provider. Opens an interactive selection prompt listing all available providers with connection status indicators. Providers that support OAuth (currently OpenAI) present an auth method choice — "Sign in with OAuth" or "API Key". Other providers prompt for an API key directly. Already-connected OAuth providers show a "Reconnect OAuth" option. Selecting the ByteRover built-in provider when not logged in triggers an inline login prompt.

**Flags:** None

***

#### `/model`

Select a model from the currently active LLM provider. Displays models with pricing, context window size, and status indicators.

**Flags:** None

<Note>Requires an active external provider. If the active provider is ByteRover (built-in), run `/providers` first to connect an external provider.</Note>

***

#### `/space list`

<Warning>
  **Deprecated in v3.0.0.** Space management is being replaced by Git-Semantic version control.
</Warning>

List all spaces for the current team.

| Flag         | Description           | Default |
| ------------ | --------------------- | ------- |
| `-j, --json` | Output in JSON format | `false` |

***

#### `/space switch`

<Warning>
  **Deprecated in v3.0.0.** Use `/vc remote set-url origin <url>` instead. See [Git-Semantic Remote Sync](/git-semantic/remote-sync).
</Warning>

Switch to a different space. Opens an interactive selection prompt.

**Flags:** None

***

#### `/reset`

<Warning>
  **Deprecated in v3.0.0.** Use `/vc reset` instead. See [Git-Semantic Command Reference](/git-semantic/command-reference).
</Warning>

Reset the context tree to an empty state. This is a destructive operation.

| Flag        | Description              |
| ----------- | ------------------------ |
| `-y, --yes` | Skip confirmation prompt |

```bash theme={null}
/reset
/reset -y
```

<Warning>This permanently deletes all curated context in the local context tree. Use `brv vc push` to back up first.</Warning>

***

#### `/new`

Start a fresh session. Ends the current session and clears conversation history. Does **not** affect the context tree.

| Flag        | Description              |
| ----------- | ------------------------ |
| `-y, --yes` | Skip confirmation prompt |

```bash theme={null}
/new
/new -y
```

***

#### `/login`

Authenticate with ByteRover using OAuth 2.0 + PKCE. Opens your default browser for secure authentication. This is the TUI slash-command equivalent of running `brv login` in the shell, which also defaults to browser OAuth.

**Flags:** None

<Note>For non-interactive authentication (CI, SSH, or other non-TTY shells), use `brv login --api-key <key>` instead.</Note>

***

#### `/logout`

Log out of ByteRover and clear authentication credentials.

| Flag        | Description              |
| ----------- | ------------------------ |
| `-y, --yes` | Skip confirmation prompt |

***

#### `/exit`

Exit the ByteRover REPL. Alternative to `Ctrl+C` for gracefully closing the session.

**Flags:** None

***

## Agent Integration

These internal commands are used by coding agents and the connector system. You do not need to run them directly — they are managed automatically by `brv connectors install`.

### `brv mcp`

Start an MCP (Model Context Protocol) server for coding agent integration. This command is spawned automatically by agents that use the MCP connector type. It communicates over stdio and connects to the running daemon via Socket.IO.

**MCP Tools**

The MCP server exposes two tools to coding agents:

| Tool         | Description                        | Input                                                                                  | Behavior                           |
| ------------ | ---------------------------------- | -------------------------------------------------------------------------------------- | ---------------------------------- |
| `brv-query`  | Query the context tree             | `query` (required), `cwd` (optional)                                                   | Synchronous — waits for result     |
| `brv-curate` | Curate context to the context tree | `context` (optional), `cwd` (optional), `files` (optional, max 5), `folder` (optional) | Asynchronous — returns immediately |

**Notes on `brv-curate`:**

* At least one of `context`, `files`, or `folder` must be provided
* When `folder` is provided, it takes precedence — any supplied `files` are ignored

**Daemon-version drift.** When the running daemon was started by a different `brv` build than the one spawning `brv mcp`, every `brv-query` / `brv-curate` text response ends with a short footer naming both versions, and `brv mcp` writes a one-line drift notice to stderr on connect and on every reconnect. Run `brv restart` (and restart the agent's host IDE so it respawns `brv mcp`) to clear it.

### `brv hook-prompt-submit`

Pre-prompt hook command for agents that use the hook connector type (Claude Code legacy). Outputs ByteRover workflow instructions to stdout before each prompt submission.

<Note>Both commands are hidden from `brv --help`. Install them via `brv connectors install <agent>` rather than running manually. See [Coding Agent Connectors](/connectors/overview) for setup instructions.</Note>

## Global Options

| Flag        | Description             | Example                          |
| ----------- | ----------------------- | -------------------------------- |
| `--help`    | Show help for a command | `brv --help`, `brv query --help` |
| `--version` | Show CLI version        | `brv --version`                  |

## Project File Structure

ByteRover CLI creates the following directory structure in your project:

```
.brv/
├── config.json                # Project configuration (team/space)
└── context-tree/              # Your knowledge base (starts empty)
    └── .git/                  # Created by brv vc init (git-semantic projects)
```

**Key files:**

* **config.json**: Stores team ID, space ID, and project metadata. Created during project initialization.
* **context-tree/**: Hierarchical structure organizing project knowledge by domains and topics.
* **.git/**: Internal Git repository for [git-semantic version control](/git-semantic/overview). Created when you run `brv vc init`.

**Example after curating:**

```
.brv/context-tree/
├── authentication/
│   ├── context.md
│   └── jwt/
│       ├── context.md
│       ├── token_refresh_strategy.md
│       └── token_validation.md
├── api/
│   └── endpoints/
│       └── rate_limiting.md
└── testing/
    └── integration_tests/
        └── api_testing_patterns.md
```

Each file contains YAML frontmatter (title, tags, keywords, related) and structured content sections.