CLI reference

​

Getting Started

# First, authenticate with ByteRover
brv login

# Then, initialize your project (select team and space)
brv init

​

CLI Commands

​

Command Details

​

brv login

# Authenticate with ByteRover
brv login

# Re-authenticate after token expires
brv login

• First command you should run when setting up ByteRover
• Opens your default browser for authentication
• Tokens are stored securely in system keychain (macOS Keychain, Windows Credential Manager, Linux libsecret)
• If authentication expires, simply run brv login again

​

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

• CLI version
• Authentication status (logged in user or “Not logged in”)
• Current directory
• Project initialization status (team and space info if initialized)
• Playbook contents (sections and bullets) or empty state

​

brv init

# Initialize project (interactive team/space selection)
brv init

# Complete first-time setup
brv login
brv init

• Requires brv login first
• Interactive prompts guide you through team and space selection
• Creates .brv/ directory with configuration and playbook structure
• Automatically runs brv gen-rules after initialization
• If project is already initialized, displays current configuration and exits

​

brv space list

# List first 50 spaces (default)
brv space list

# List all spaces
brv space list --all

# Manual pagination: get 10 spaces at a time
brv space list --limit 10
brv space list --limit 10 --offset 10

# Output as JSON
brv space list --json

• Requires brv init first (reads team ID from config)
• Default limit is 50 spaces
• Use --all to fetch all spaces (internally paginates at 100 items per page)
• Use --limit and --offset for manual pagination control

​

brv space switch

# Switch team or space (interactive)
brv space switch

• Requires brv init first (project must be initialized)
• Displays current team and space configuration
• Interactive prompts guide you through new team and space selection
• Updates configuration but does NOT initialize playbook

​

brv retrieve

# Retrieve memories about authentication
brv retrieve --query "authentication best practices"

# Short form
brv retrieve -q "error handling patterns"

# Filter by specific files
brv retrieve -q "database connection" -n "src/db/connection.ts,src/db/pool.ts"

# Compact JSON output (single line)
brv retrieve -q "API endpoints" --compact

• Requires brv login and brv init first
• Returns JSON with memories (primary results with scores) and relatedMemories (additional context)
• Each memory includes: content, section, tags, metadata type, timestamp, related files
• Use --node-keys to scope search to specific files in your codebase

​

brv push

# Push to default branch (with confirmation)
brv push

# Push to a specific branch
brv push --branch develop
brv push -b feature-auth

# Skip confirmation prompt
brv push --yes
brv push -y

• Requires brv login and brv init first
• Playbook must exist with content to push
• Branch concept is ByteRover-internal, NOT related to Git branches
• Shows confirmation dialog unless --yes flag is used
• After successful push, automatically cleans up:
  • Playbook content (resets to empty)
  • Bullet files (.brv/ace/bullets/)
  • Executor outputs (.brv/ace/executor-outputs/)
  • Reflections (.brv/ace/reflections/)
  • Deltas (.brv/ace/deltas/)

​

brv add

# Interactive mode (recommended)
brv add --interactive
brv add -i

# Add new bullet directly
brv add --section "Common Errors" --content "Auth fails when token expires"

# Update existing bullet
brv add --section "Common Errors" --bullet-id "common-00001" --content "Updated: Auth fails when token expires"

# Short form
brv add -s "Best Practices" -c "Always validate user input before processing"

• Playbook must exist (run brv init first)
• Interactive mode: prompts for section (with search), content, and confirmation
• Non-interactive mode: requires both --section and --content flags
• Suggested sections: Common Errors, Best Practices, Strategies, Lessons Learned, Architecture, Testing
• If --bullet-id is not provided, creates a new bullet with auto-generated ID

​

brv clear

# Clear playbook (with confirmation)
brv clear

# Clear without confirmation
brv clear --yes
brv clear -y

# Clear playbook in specific directory
brv clear /path/to/project

• Playbook must exist
• Shows confirmation prompt unless --yes flag is used
• This action cannot be undone
• Resets playbook to empty structure with no bullets
• Does not affect .brv/config.json or project initialization

​

brv complete

# Complete workflow after implementing OAuth
brv complete "user-auth" "Implemented OAuth2 flow with PKCE" "Authentication works correctly" \
  --tool-usage "Read:src/auth.ts,Edit:src/auth.ts,Bash:npm test" \
  --feedback "All tests passed"

# Complete with referenced bullets
brv complete "validation-fix" "Analyzed validator and fixed edge case" "Bug fixed" \
  --tool-usage "Grep:pattern:\"validate\",Read:src/validator.ts,Edit:src/validator.ts" \
  --bullet-ids "bullet-123,bullet-456" \
  --feedback "Tests passed, no regressions"

# Update existing bullet
brv complete "auth-update" "Improved error handling in auth flow" "Better error messages" \
  --tool-usage "Edit:src/auth.ts,Bash:npm test" \
  --feedback "Tests passed" \
  --update-bullet "bullet-5"

# Short form flags
brv complete "fix" "Fixed bug" "Works now" -t "Edit:file.ts" -f "Tests pass"

• ToolName:argument - e.g., Read:src/file.ts
• ToolName:pattern:"search" - e.g., Grep:pattern:"validate"
• Multiple tools: Read:file1.ts,Edit:file1.ts,Bash:npm test

1. Phase 1: Saves executor output to .brv/ace/executor-outputs/
2. Phase 2: Generates reflection with tags and saves to .brv/ace/reflections/
3. Phase 3: Generates delta and applies to playbook

• Playbook must exist (run brv init first)
• This is the primary command for coding agents to complete the ACE workflow
• Combines three separate operations (executor output, reflection, delta) into one
• If --update-bullet is not provided, adds new bullet to playbook
• Use --bullet-ids to reference bullets that informed your approach

​

brv gen-rules

# Generate rules (interactive agent selection)
brv gen-rules

• Interactive search prompt for agent selection
• Prompts for overwrite confirmation if rule file already exists
• Automatically called by brv init command
• Generated rules help coding agents understand ByteRover workflow
• Rules include commands, workflows, and best practices for the selected agent

​

Global Options

​

File Structure

.brv/
├── config.json              # Project configuration (team/space)
└── ace/
    ├── playbook.json        # Living knowledge base
    ├── bullets/             # Individual bullet content
    ├── executor-outputs/    # Task execution records
    ├── reflections/         # Task reflections
    └── deltas/              # Playbook update operations

• config.json: Stores your team ID, space ID, and project metadata
• playbook.json: Your living knowledge base containing accumulated learnings organized by sections
• bullets/: Individual bullet content referenced by the playbook
• executor-outputs/: Records of task executions (created by brv complete)
• reflections/: Generated reflections on completed tasks
• deltas/: Operations that modify the playbook structure