DOCSEARCHbyAlgolia
Submit Docs

ByteRover CLI

repository·main·Indexed 26 days ago

https://github.com/campfirein/byterover-cli

ByteRover CLI (`brv`) is an interactive REPL and toolset that provides AI coding agents with persistent, structured, and hierarchical memory. It allows developers to curate project knowledge into a context tree that can be synced to the cloud and shared across teams. The CLI includes features for managing context via a version-control pattern (`brv vc`), configuring 20+ LLM providers, and a specialized curate protocol for agent orchestration.

Tokens
45K
Snippets
67
Records
448
Agent score
89%

What's inside byterover-cli

  1. Understand the scope and limitations of the curate protocol

    main

    The brv curate protocol has specific boundaries regarding what it handles:

    • No HTML generation: The calling agent's LLM is responsible for authoring HTML based on the provided prompt. ByteRover does not interact with an LLM directly in tool mode.
    • No Schema knowledge: Schema information is embedded within the prompt (via the prompt builder condensing the bv-* spec). The calling agent does not pre-load any schema.
    • Limited Retry Strategy: The protocol only manages the correct-html loop. If the calling agent's LLM produces invalid HTML for 3 consecutive rounds, the session terminates with a failed status. In this case, the calling agent should surface the failure and ask the user for clarification.

  2. Run ByteRover CLI REPL

    main

    To start the interactive REPL in a specific project, navigate to your project directory and run the brv command. The REPL will auto-configure on its first run.

    Once inside the REPL, type / to see all available commands.

    cd your/project
brv

  6. Continue a `brv curate` session

    main

    To resume an in-flight session, use the --session <sessionId> flag along with the LLM's response. The response must be a JSON envelope containing html and optional meta keys. You can deliver the response in two ways:

    1. Inline: Using the --response flag with a JSON string.
    2. File-based: Using the --response-file flag pointing to a JSON file. This is mutually exclusive with --response.

    If using a file, you can optionally use --delete-response-file to unlink the file after the daemon dispatch returns. Note that if a daemon error occurs, the file is preserved for retries. If the status is correct-html, the file is deleted after the call, so the agent must re-author a new file for the next step.

    # Inline envelope
brv curate --session <sessionId> --response '{"html":"<bv-topic>...</bv-topic>","meta":{...}}' --format json

# Envelope from a JSON file
brv curate --session <sessionId> --response-file envelope.json --format json

# Envelope from a JSON file with automatic cleanup
brv curate --session <sessionId> --response-file envelope.json --delete-response-file --format json

  7. Manage Worktrees and Knowledge Sources

    main

    ByteRover allows you to run from a linked subdirectory (worktree) without creating a nested .brv/ directory.

    • Worktree: A subdirectory pointer to a parent project. Use brv worktree add <path> from the project root to register a subdirectory or sibling. Use brv worktree remove to unregister and brv worktree list to inspect.
    • Source: A read-only reference to another project's knowledge. Use brv source add <path> to attach a source, brv source list to inspect, and brv source remove to detach.

    When running brv query or brv curate from a worktree, the tool uses worktreeRoot as the default scope to ensure stability even if your shell directory drifts.

  8. Kickoff a `brv curate` session

    main

    To start a new curation session in tool-mode, use the brv curate command with a user intent string. You must use --format json to receive the machine-readable wire envelope required for agent orchestration. Tool-mode does not require any LLM provider configuration or environment variables; the calling agent is responsible for providing completions.

    brv curate "<user intent>" --format json

  9. Overwrite existing topics in `brv curate`

    main

    By default, brv curate will refuse to overwrite an existing topic at a resolved path. If a path conflict occurs, it returns a path-exists correction step containing the existing file's content. To explicitly replace existing content, include the --overwrite flag in your continuation command. This flag must be repeated on every subsequent continuation in the session if overwriting is still required.

    brv curate --session <sessionId> --response-file envelope.json --overwrite --format json

  10. Install ByteRover CLI

    main

    You can install the ByteRover CLI (brv) using either a shell script for macOS/Linux or via npm for all platforms.

    macOS & Linux (No Node.js required)

    Use the bundled installer:

    curl -fsSL https://byterover.dev/install.sh | sh

    Supported platforms: macOS ARM64, macOS x64 (Intel), Linux x64, Linux ARM64.

    All Platforms (Requires Node.js >= 20)

    Install globally via npm:

    npm install -g byterover-cli
    curl -fsSL https://byterover.dev/install.sh | sh

  11. Configure ByteRover Settings

    main

    Settings can be inspected and modified via the brv settings command group. Note that most changes require a brv restart to take effect because the daemon reads the configuration only at startup.

    Available Keys

    KeyDefaultDescription
    agentPool.maxSize10Maximum concurrent active projects (one agent process per project).
    agentPool.maxConcurrentTasksPerProject5Parallel brv curate / brv query tasks within a single project.
    llm.iterationBudgetMs600000Wall-clock budget for the agentic loop on one task (ms).
    llm.requestTimeoutMs120000Wall-clock budget for one direct LLM HTTP request (ms).
    taskHistory.maxEntries1000Number of task records brv query-log view retains per project.

    Constraint: llm.requestTimeoutMs must be $\le$ llm.iterationBudgetMs.

    Configuration File Locations

    Settings are stored in settings.json in the global data directory:

    • Linux: $XDG_DATA_HOME/brv/settings.json (defaults to ~/.local/share/brv/settings.json)
    • macOS: ~/Library/Application Support/brv/settings.json
    • Windows: %LOCALAPPDATA%/brv/settings.json

    You can override the directory by setting the BRV_DATA_DIR environment variable.

    brv settings list               # Alias for `brv settings`
brv settings get <key>          # Show current and default for one key
brv settings set <key> <value>  # Update one key (restart required)
brv settings reset <key>        # Restore one key to its default (restart required)

  12. Use Expanded Command View keyboard shortcuts

    main

    When viewing an expanded command message in the ByteRover CLI (full-screen overlay), you can navigate the scrollable output using the following keyboard shortcuts:

    • Ctrl+O: Collapse/dismiss the expanded view.
    • Up Arrow or k: Scroll up by one line.
    • Down Arrow or j: Scroll down by one line.
    • g: Scroll to the top of the output.
    • G: Scroll to the bottom of the output.