Skip to main content
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:
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.
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

CommandDescription
brvStart interactive TUI
brv loginAuthenticate with API key
brv statusShow CLI and project status
brv locationsList registered projects and context tree status
brv restartRestart the background daemon
brv queryQuery the context tree
brv curateCurate context to the context tree
brv curate viewView curate operation history
brv pushPush context tree to cloud
brv pullPull context tree from cloud
brv providersManage LLM providers
brv modelManage LLM models
brv connectorsManage coding agent connectors
brv hubBrowse and install skills and bundles
brv spaceManage teams and spaces

CLI Command Reference

brv

Start the interactive TUI with a React/Ink-based terminal interface. Arguments: None Flags: None Examples
brv
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
FlagDescriptionDefault
-k, --api-key <key>API key for authentication (required)
--format <text|json>Output formattext
Examples
brv login --api-key brv_your_api_key_here
brv login --api-key brv_your_api_key_here --format json
Get your API key from app.byterover.dev/settings/keys. For interactive OAuth login, use the /login slash command in the TUI instead.

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
FlagDescriptionDefault
--format <text|json>Output formattext
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
FlagDescriptionDefault
-f, --format <text|json>Output formattext
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
FlagDescriptionDefault
-f, --format <text|json>Output formattext
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 restart

brv query

Query the context tree using natural language. Auto-starts the daemon if not already running. Arguments
ArgumentTypeRequiredDescription
querystringYesNatural language question about your project
Flags
FlagDescriptionDefault
--format <text|json>Output formattext
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
ArgumentTypeRequiredDescription
contextstringNoKnowledge to store — triggers autonomous mode if provided
Flags
FlagDescriptionDefault
-f, --files <path>File path to include (repeatable, max 5)
-d, --folder <path>Folder path to pack and analyze
--detachQueue the task and return immediately without waiting for completionfalse
--format <text|json>Output formattext
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
ArgumentTypeRequiredDescription
idstringNoLog entry ID to view in detail
Flags
FlagDescriptionDefault
--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, processingAll
--detailShow operations for each entry in list viewfalse
--limit <n>Maximum number of entries to display (minimum 1)10
--format <text|json>Output formattext
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
FlagDescriptionDefault
-b, --branch <name>ByteRover branch name (not Git branch)main
--format <text|json>Output formattext
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
FlagDescriptionDefault
-b, --branch <name>ByteRover branch name (not Git branch)main
--format <text|json>Output formattext
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
FlagDescriptionDefault
--format <text|json>Output formattext
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
FlagDescriptionDefault
--format <text|json>Output formattext
Examples
brv providers list
brv providers list --format json

brv providers connect

Connect to an LLM provider and optionally set the active model. Arguments
ArgumentTypeRequiredDescription
providerstringYesProvider ID (e.g., anthropic, openai, openrouter, openai-compatible)
Flags
FlagDescriptionDefault
-k, --api-key <key>API key for the provider
--oauthConnect 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 formattext
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
ArgumentTypeRequiredDescription
providerstringYesProvider ID to disconnect
Flags
FlagDescriptionDefault
--format <text|json>Output formattext
Examples
brv providers disconnect openrouter

brv providers switch

Switch the active provider. The provider must already be connected. Arguments
ArgumentTypeRequiredDescription
providerstringYesProvider ID to switch to
Flags
FlagDescriptionDefault
--format <text|json>Output formattext
Examples
brv providers switch anthropic
brv providers switch byterover

brv model

Show the currently active model and provider. Arguments: None Flags
FlagDescriptionDefault
--format <text|json>Output formattext
Examples
brv model
brv model --format json

brv model list

List available models from all connected providers. Arguments: None Flags
FlagDescriptionDefault
-p, --provider <id>Filter to a specific providerAll connected
--format <text|json>Output formattext
Examples
brv model list
brv model list --provider anthropic
brv model list --format json

brv model switch

Switch the active model. Arguments
ArgumentTypeRequiredDescription
modelstringYesModel ID to switch to
Flags
FlagDescriptionDefault
-p, --provider <id>Provider for the model (defaults to active provider)Active provider
--format <text|json>Output formattext
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
FlagDescriptionDefault
--format <text|json>Output formattext
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
ArgumentTypeRequiredDescription
agentstringYesAgent name (e.g., "Claude Code", Cursor, Windsurf)
Flags
FlagDescriptionDefault
-t, --type <type>Connector type: rules, hook, mcp, skillAgent’s recommended type
--format <text|json>Output formattext
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

brv hub list

List all available skills and bundles from configured registries. Arguments: None Flags
FlagDescriptionDefault
-f, --format <text|json>Output formattext
Examples
brv hub list
brv hub list --format json

brv hub install

Install a skill or bundle from the hub. Arguments
ArgumentTypeRequiredDescription
idstringYesEntry ID to install
Flags
FlagDescriptionDefault
-a, --agent <agent>Target agent for skill install (required for skills)
-s, --scope <scope>Install scope: global or projectproject
-r, --registry <name>Registry to install from (when ID exists in multiple registries)
-f, --format <text|json>Output formattext
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

brv hub registry list

List all configured hub registries with connection status. Arguments: None Flags
FlagDescriptionDefault
-f, --format <text|json>Output formattext
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
ArgumentTypeRequiredDescription
namestringYesRegistry name (used in --registry flag)
Flags
FlagDescriptionDefault
-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 formattext
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
See Custom Registries for the full guide on hosting your own registry.

brv hub registry remove

Remove a custom registry and its stored credentials. Arguments
ArgumentTypeRequiredDescription
namestringYesRegistry name to remove
Flags
FlagDescriptionDefault
-f, --format <text|json>Output formattext
Examples
brv hub registry remove myco

brv space list

List all available teams and spaces. Requires authentication. Arguments: None Flags
FlagDescriptionDefault
-f, --format <text|json>Output formattext
Examples
brv space list
brv space list --format json

brv space switch

Switch to a different team and space. Requires authentication. Arguments: None Flags
FlagDescriptionDefault
-t, --team <name>Team name (required)
-n, --name <name>Space name (required)
-f, --format <text|json>Output formattext
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.
CommandAliasesDescription
/statusShow CLI status and project information
/locationsList registered projects and context tree status
/curate [context] [@paths]Curate context to the context tree
/query <query>Query the context tree
/connectorsManage coding agent connectors
/hub listBrowse and install skills and bundles
/hub registry listList configured hub registries
/hub registry add <name>Add a hub registry
/hub registry remove <name>Remove a hub registry
/pushPush context tree to cloud
/pullPull context tree from cloud
/providersConnect to an LLM provider
/modelSelect a model from the active provider
/space listList all spaces
/space switchSwitch to a different space
/resetReset context tree to empty
/newStart a fresh session
/loginAuthenticate via OAuth browser flow
/logoutLog out and clear credentials
/exitExit 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
/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.
ArgumentTypeRequiredDescription
contextstringNoKnowledge 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.
ArgumentTypeRequiredDescription
querystringYesNatural 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.
ArgumentTypeRequiredDescription
namestringYesRegistry name
FlagDescription
-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.
ArgumentTypeRequiredDescription
namestringYesRegistry name to remove
/hub registry remove myco

/push

Push context tree to ByteRover cloud storage.
FlagDescriptionDefault
-b, --branch <name>ByteRover branch namemain
-y, --yesSkip confirmation prompt
/push
/push -b feature-auth
/push -y

/pull

Pull context tree from ByteRover cloud storage.
FlagDescriptionDefault
-b, --branch <name>ByteRover branch namemain
/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.
FlagDescriptionDefault
-j, --jsonOutput in JSON formatfalse

/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.
FlagDescription
-y, --yesSkip confirmation prompt
/reset
/reset -y
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.
FlagDescription
-y, --yesSkip confirmation prompt
/new
/new -y

/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.
FlagDescription
-y, --yesSkip 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:
ToolDescriptionInputBehavior
brv-queryQuery the context treequery (required), cwd (optional)Synchronous — waits for result
brv-curateCurate context to the context treecontext (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

FlagDescriptionExample
--helpShow help for a commandbrv --help, brv query --help
--versionShow CLI versionbrv --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.