ByteRover CLI (brv) manages your AI development workflow — context curation, querying, LLM provider and model management, cloud sync, and coding agent integration. With the daemon-first architecture, every command works standalone without requiring an interactive session.
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:
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.
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 push | Push context tree to cloud |
brv pull | Pull context tree from cloud |
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 space | Manage teams and spaces |
CLI Command Reference
brv
Start the interactive TUI with a React/Ink-based terminal interface.
Arguments: None
Flags: None
Examples
Press Esc to cancel streaming responses. Press Ctrl+C to exit.
brv login
Authenticate with ByteRover using an API key for cloud sync features. Authentication is optional for local-only usage.
Arguments: None
Flags
| Flag | Description | Default |
|---|
-k, --api-key <key> | API key for authentication (required) | — |
--format <text|json> | Output format | text |
Examples
brv login --api-key brv_your_api_key_here
brv login --api-key brv_your_api_key_here --format json
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
brv logout
brv logout --format json
You can log back in at any time with brv login --api-key <key>. Logging out does not delete your local context tree — it only clears cloud credentials.
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
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
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.
Arguments: None
Flags: None
Examples
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 |
|---|
--format <text|json> | Output format | text |
Examples
brv query "How is user authentication implemented?"
brv query "What testing strategies are used?"
brv query "What are the API endpoints?" --format json
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 for the output format
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 |
--format <text|json> | Output format | text |
Examples
# 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
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
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
# 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 push
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
brv push
brv push --branch feature-auth
brv push --format json
brv pull
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
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
brv providers
brv providers --format json
brv providers list
List all available LLM providers with their connection status. 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
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 | — |
--format <text|json> | Output format | text |
Examples
# 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 free built-in provider
brv providers connect byterover
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.
- ByteRover CLI auto-detects API keys from environment variables (e.g.,
ANTHROPIC_API_KEY, OPENAI_API_KEY)
- See LLM Providers 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
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
brv providers switch anthropic
brv providers switch byterover
brv model
Show the currently active model and provider.
Arguments: None
Flags
| Flag | Description | Default |
|---|
--format <text|json> | Output format | text |
Examples
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
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
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
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
# 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 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
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
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
# 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 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
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
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
# 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
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
brv hub registry remove myco
brv space list
List all available teams and spaces. Requires authentication.
Arguments: None
Flags
| Flag | Description | Default |
|---|
-f, --format <text|json> | Output format | text |
Examples
brv space list
brv space list --format json
brv space switch
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
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 |
/pull | — | Pull context tree from cloud |
/providers | — | Connect to an LLM provider |
/model | — | Select a model from the active provider |
/space list | — | List all spaces |
/space switch | — | Switch to a different space |
/reset | — | Reset context tree to empty |
/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
/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):
# 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/
/query
Query the context tree using natural language.
| Argument | Type | Required | Description |
|---|
query | string | Yes | Natural language question |
/query "How is user authentication implemented?"
/query "What testing strategies are used?"
/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) |
/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 |
/hub registry remove myco
/push
Push context tree to ByteRover cloud storage.
| Flag | Description | Default |
|---|
-b, --branch <name> | ByteRover branch name | main |
-y, --yes | Skip confirmation prompt | — |
/push
/push -b feature-auth
/push -y
/pull
Pull context tree from ByteRover cloud storage.
| Flag | Description | Default |
|---|
-b, --branch <name> | ByteRover branch name | main |
/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.
Flags: None
/model
Select a model from the currently active LLM provider. Displays models with pricing, context window size, and status indicators.
Flags: None
Requires an active external provider. If the active provider is ByteRover (built-in), run /providers first to connect an external provider.
/space list
List all spaces for the current team.
| Flag | Description | Default |
|---|
-j, --json | Output in JSON format | false |
/space switch
Switch to a different space. Opens an interactive selection prompt.
Flags: None
/reset
Reset the context tree to an empty state. This is a destructive operation.
| Flag | Description |
|---|
-y, --yes | Skip confirmation prompt |
This permanently deletes all curated context in the local context tree. Use brv push to back up first.
/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 |
/login
Authenticate with ByteRover using OAuth 2.0 + PKCE. Opens your default browser for secure authentication.
Flags: None
This is the interactive OAuth flow. For non-interactive authentication (CI/CD), use brv login --api-key instead.
/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
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.
Both commands are hidden from
brv --help. Install them via
brv connectors install <agent> rather than running manually. See
Coding Agent Connectors for setup instructions.
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)
└── .snapshot.json # Context tree version snapshot
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.
- .snapshot.json: Version control snapshot for tracking context tree changes.
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 (tags, keywords, importance, maturity) and structured content sections.