CLI reference - Byterover

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, every command works standalone without requiring an interactive session.

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 for the full guide and Command Reference for all brv vc commands.

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

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 — agent pool, LLM time budgets, task-history retention
`brv space`	Manage teams and spaces
`brv vc *`	Git-Semantic version control — 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`

Proxy support requires ByteRover CLI v2.4.0 or later. See Troubleshooting — Proxy Configuration for setup details.

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.

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

# 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

Get an API key from 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.

`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 (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.

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

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

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

# 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

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

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

# 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

# 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

# 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

brv swarm onboard

See 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

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

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

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 for full details.

`brv push`

Deprecated in v3.0.0. Use brv vc push instead. See Git-Semantic Remote Sync and Command Reference. If Git-Semantic version control is initialized, this command is blocked with a VC_GIT_INITIALIZED error.

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`

Deprecated in v3.0.0. Use brv vc pull instead. See Git-Semantic Remote Sync and Command Reference. If Git-Semantic version control is initialized, this command is blocked with a VC_GIT_INITIALIZED error.

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

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

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

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.

`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

`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

`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

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

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`

Deprecated in v3.0.0. Space management is being replaced by Git-Semantic version control. Use brv vc remote to manage remote connections.

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`

Deprecated in v3.0.0. Use brv vc remote set-url origin <url> instead. See Git-Semantic Remote Sync and Command Reference.

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

/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):

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

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.

`/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?"

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

`/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`

Deprecated in v3.0.0. Use /vc push instead. See Git-Semantic Remote Sync.

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`

Deprecated in v3.0.0. Use /vc pull instead. See Git-Semantic Remote Sync.

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

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

`/space list`

Deprecated in v3.0.0. Space management is being replaced by Git-Semantic version control.

List all spaces for the current team.

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

`/space switch`

Deprecated in v3.0.0. Use /vc remote set-url origin <url> instead. See Git-Semantic Remote Sync.

Switch to a different space. Opens an interactive selection prompt. Flags: None

`/reset`

Deprecated in v3.0.0. Use /vc reset instead. See Git-Semantic Command Reference.

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

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

/reset
/reset -y

This permanently deletes all curated context in the local context tree. Use brv vc 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

/new
/new -y

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

For non-interactive authentication (CI, SSH, or other non-TTY shells), use brv login --api-key <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

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.

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)
    └── .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. 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.

​Getting Started

​Interactive TUI

​Standalone CLI Commands

​Command Overview

​Environment Variables

​CLI Command Reference

​brv

​brv login

​brv logout

​brv locations

​brv status

​brv restart

​brv query

​brv curate

​brv curate view

​brv review

​brv review pending

​brv review approve

​brv review reject

​brv swarm onboard

​brv swarm status

​brv swarm query

​brv swarm curate

​brv push

​brv pull

​brv providers

​brv providers list

​brv providers connect

​brv providers disconnect

​brv providers switch

​brv model

​brv model list

​brv model switch

​brv connectors

​brv connectors install

​brv hub

​brv hub list

​brv hub install

​brv hub registry

​brv hub registry list

​brv hub registry add

​brv hub registry remove

​brv space list

​brv space switch

​TUI Slash Commands

​Slash Command Details

​/status

​/locations

​/curate

​/query

​/connectors

​/hub list

​/hub registry list

​/hub registry add

​/hub registry remove

​/push

​/pull

​/providers

​/model

​/space list

​/space switch

​/reset

​/new

​/login

​/logout

​/exit

​Agent Integration

​brv mcp

​brv hook-prompt-submit

​Global Options

​Project File Structure

Getting Started

Interactive TUI

Standalone CLI Commands

Command Overview

Environment Variables

CLI Command Reference

`brv`

`brv login`

`brv logout`

`brv locations`

`brv status`

`brv restart`

`brv query`

`brv curate`

`brv curate view`

`brv review`

`brv review pending`

`brv review approve`

`brv review reject`

`brv swarm onboard`

`brv swarm status`

`brv swarm query`

`brv swarm curate`

`brv push`

`brv pull`

`brv providers`

`brv providers list`

`brv providers connect`

`brv providers disconnect`

`brv providers switch`

`brv model`

`brv model list`

`brv model switch`

`brv connectors`

`brv connectors install`

`brv hub`

`brv hub list`

`brv hub install`

`brv hub registry`

`brv hub registry list`

`brv hub registry add`

`brv hub registry remove`

`brv space list`

`brv space switch`

TUI Slash Commands

Slash Command Details

`/status`

`/locations`

`/curate`

`/query`

`/connectors`

`/hub list`

`/hub registry list`

`/hub registry add`

`/hub registry remove`

`/push`

`/pull`

`/providers`

`/model`

`/space list`

`/space switch`

`/reset`

`/new`

`/login`

`/logout`

`/exit`

Agent Integration

`brv mcp`

`brv hook-prompt-submit`

Global Options

Project File Structure