CLI reference

​

Installation

npm install -g byterover-cli

brv --version

​

Prerequisites

• Node.js: Version 20.0.0 or higher
• Supported platforms: macOS, Windows, Linux

​

Getting Started

​

Interactive REPL Mode (Recommended)

brv

/status                 # Show auth, config, and context tree state
/curate [context] [@paths]  # Curate context to the context tree
/query <query>          # Query information from context tree (alias: /q)
/connector              # Manage coding agent connectors (alias: /connectors)
/provider               # Connect to an LLM provider (aliases: /providers, /connect)
/model                  # Select a model from the active provider (alias: /models)
/push [-b branch] [-y]  # Push context tree to ByteRover memory storage
/pull [-b branch]       # Pull context tree from ByteRover memory storage
/space list [-a] [-j]   # List all spaces
/space switch           # Switch to a different space
/reset [-y] [directory] # Reset context tree to an empty state
/new [-y]               # Start fresh session (clears conversation)
/init [-f]              # Initialize project (select team/space)
/login                  # Authenticate with ByteRover
/logout [-y]            # Log out

​

Standalone CLI Commands

brv status                              # Show CLI and project status
brv query "How is auth implemented?"    # Query context tree
brv curate "JWT tokens expire in 24h"   # Curate context to context tree
brv init --headless --team <id> --space <id>  # Initialize project (headless)
brv login --api-key <key>               # Authenticate with API key
brv push -y                             # Push context tree
brv pull                                # Pull context tree

​

CLI Commands

Note: Commands logout, space, connector, provider, model, reset, and new are only available as slash commands in REPL mode. Run brv to start REPL mode.

Important: In interactive mode, the brv query and brv curate commands require a running brv instance in the same directory (start with brv first). In headless mode (--headless flag), these commands run independently.

​

Command Details

​

Headless Mode

• Runs without requiring an interactive terminal (no TTY)
• Outputs structured data in text or JSON format
• Fails gracefully when interactive prompts would be required

# Initialize project in CI pipeline
brv init --headless --team my-team --space my-space --format json

# Query context tree and get JSON response
brv query "How is auth implemented?" --headless --format json

# Push changes without confirmation
brv push --headless -y --format json

# Get status as JSON for scripting
brv status --headless --format json

​

brv

# Start interactive REPL mode
brv

• Persistent session: Stay in the CLI and run multiple commands without restarting
• Slash commands: Use /command syntax for all operations (e.g., /login, /push, /query)
• Interactive onboarding: First-time users get a guided setup flow (press Esc to skip)
• Real-time feedback: See streaming responses and progress indicators
• Escape to cancel: Press Esc to cancel streaming responses and long-running commands
• Tab completion: Auto-complete slash commands as you type

• REPL mode is the primary way to use ByteRover CLI for an interactive experience
• Commands like logout, space, connector, provider, model, reset, and new are only available in REPL mode
• Press Esc to cancel streaming responses or long-running commands
• Use Ctrl+C to exit REPL mode

​

Slash Command Details

​

/status

​

/curate

# Interactive mode (manually choose domain/topic)
/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 "Authentication module overview" @src/auth/

​

/query (alias: /q)

/query "How is user authentication implemented?"
/q "What testing strategies are used?"

​

/push

/push                    # Push to main branch
/push -b feature-auth    # Push to feature-auth branch
/push -y                 # Push without confirmation

​

/pull

/pull                    # Pull from main branch
/pull -b feature-auth    # Pull from feature-auth branch

​

/space list

​

/space switch

​

/connector (alias: /connectors)

• Skill: Writes comprehensive documentation files (SKILL.md, TROUBLESHOOTING.md, WORKFLOWS.md) to agent-specific directories. Default for Claude Code and Cursor.
• MCP: Uses Model Context Protocol for direct tool integration (brv-query, brv-curate). Default for most other agents.
• Rules: Generates markdown rule files that agents read for instructions. Fallback option for all agents.
• Hook: Uses agent-specific hook systems for tighter integration (Claude Code only, legacy)

• SKILL.md: Quick reference with command examples and best practices
• TROUBLESHOOTING.md: Common errors, required user actions, and diagnostics
• WORKFLOWS.md: Step-by-step patterns for 6 common scenarios (Research, Debug, Multi-file changes, etc.)

• Claude Code: .claude/skills/byterover/ (project-level)
• Cursor: .cursor/skills/byterover/ (project-level)
• Github Copilot: .github/skills/byterover/ (project-level)
• Codex: ~/.codex/skills/byterover/ (global)

• Auto setup: ByteRover automatically writes the MCP config file (most agents)
• Manual setup: User must manually configure per agent’s documentation (Augment Code, Cline, Qoder, Qwen Code, Trae.ai, Warp)

​

/provider (aliases: /providers, /connect)

• Displays a selection prompt listing all available providers with connection status indicators
• If the selected provider is already connected, it is set as the active provider immediately
• If the selected provider requires an API key, prompts for the key and validates it before connecting
• API keys are stored securely in the system keychain

# Open provider selection dialog
/provider

# Also accessible via aliases
/providers
/connect

​

/model (alias: /models)

• Requires an active external provider (ByteRover uses an internal model with no selection)
• Fetches available models from the active provider’s API
• Displays models sorted by: favorites first, then recently used, then by provider and model name
• Shows pricing information (input/output cost per million tokens), context window size, and status indicators (Current, Favorite, Free)
• Selected model is saved as the active model for the provider

# Open model selection dialog (requires active external provider)
/model

# Also accessible via alias
/models

• If no external provider is connected, run /provider first
• If the active provider is ByteRover, the command will prompt you to switch to an external provider
• Model list depends on the connected provider (e.g., OpenRouter provides 200+ models)

​

/init

​

/login

​

/logout

​

/reset

/reset                       # Reset with confirmation
/reset -y                    # Reset without confirmation
/reset -y /path/to/project   # Reset specific project

​

/new

/new                         # Start new session with confirmation
/new -y                      # Start new session without confirmation

​

brv init

# Interactive initialization
brv init

# Force re-initialization
brv init --force

# Headless initialization for CI/CD
brv init --headless --team my-team --space my-space
brv init --headless --team team-abc123 --space space-xyz789 --format json

​

brv login

# Authenticate with API key
brv login --api-key brv_your_api_key_here

• Get your API key from https://app.byterover.dev/settings/keys
• This command uses API key authentication, different from the OAuth-based /login slash command in REPL mode
• The API key is stored securely in the system keychain

​

brv status

# Show status for current directory
brv status

# Show status for a specific directory
brv status /path/to/project

# Output status as JSON
brv status --format json

# Headless mode for CI/CD
brv status --headless --format json

• CLI version
• Authentication status (logged in user or “Not logged in”)
• Current directory
• Project initialization status (team and space info if initialized)
• Context tree changes (git-style diff showing modified/added/deleted files)

​

brv query

# Query about implementation details
brv query "How is user authentication implemented?"
brv query "What are the API rate limits and where are they enforced?"

# Query about project structure
brv query "What testing strategies are used?"

# Headless mode for scripting
brv query "What are the API endpoints?" --headless --format json

• Interactive mode: Requires a running brv instance in the same directory (start with brv in another terminal)
• Headless mode: Runs independently without requiring a separate instance
• Context tree must exist (run /init or brv init first)
• Uses AI to search and analyze your context tree
• Best results with specific, detailed questions
• Avoid vague queries like “auth” or “show me code”

​

brv curate

# Interactive mode (manually choose domain/topic)
brv curate

# Autonomous mode with AI classification
brv curate "User authentication uses JWT tokens with 24h expiry"
brv curate "React components follow atomic design pattern"

# Include file references for context
brv curate "This module handles user sessions" -f src/auth/session.ts
brv curate "JWT authentication implementation" --files src/auth/jwt.ts --files docs/auth.md
brv curate "Auth logic" -f src/auth.ts -f src/middleware/auth.ts

# Folder pack - analyze and curate entire folder
brv curate "Authentication module overview" --folder src/auth/
brv curate --folder src/auth/
brv curate "Analyze authentication module" -d src/auth/

# Headless mode for CI/CD
brv curate "Auth uses JWT tokens" --headless --format json

• Interactive mode: Requires a running brv instance in the same directory (start with brv in another terminal)
• Headless mode: Runs independently without requiring a separate instance
• Context tree must exist (run /init or brv init first)
• Interactive mode (without context): Navigate context tree, select domain/topic, creates markdown file with descriptive name
• Autonomous mode (with context): ByteRover agent automatically determines best location and adds content
• File references: Up to 5 files with --files / -f flag in CLI mode, or @path syntax in REPL mode. Files must be text files within the project directory
• Folder references: Use --folder / -d flag in CLI mode, or @folder/ syntax in REPL mode. Folder contents are packed into a structured format for analysis

​

brv push

# Push to main branch with confirmation
brv push

# Push to feature branch
brv push --branch feature-auth

# Push without confirmation (for scripts)
brv push -y

# Headless mode for CI/CD
brv push --headless -y --format json

​

brv pull

# Pull from main branch
brv pull

# Pull from feature branch
brv pull --branch feature-auth

# Headless mode for CI/CD
brv pull --headless --format json

​

Global Options

​

File Structure

.brv/
├── config.json                # Project configuration (team/space)
└── context-tree/              # Your knowledge base (starts empty)
    └── .snapshot.json         # Latest context tree snapshot

• config.json: Stores your team ID, space ID, and project metadata
• context-tree/: Hierarchical structure organizing project knowledge by domains and topics (created as you curate)
• .snapshot.json: Version control snapshot tracking context tree changes over time

.brv/context-tree/
├── code_style/
│   └── error_handling/
│       └── custom_error_classes.md
├── design/
│   └── components/
│       └── button_variants.md
├── structure/
│   └── api_endpoints/
│       └── rest_api_structure.md
└── testing/
    └── integration_tests/
        └── api_testing_patterns.md