byterover-headless

# ByteRover Knowledge Management Use the `brv` CLI to manage your own knowledgebase. ByteRover maintains a context tree that stores patterns, decisions, and implementation details about a project. **IMPORTANT**: For headless/automated use, always add `--headless --format json` flags to get machine-parseable JSON output. ## Setup (Headless) - ByteRover can be fully set up in headless mode. If user has not logged in or initialized `.brv/` in the current working directory (check via `projectInitialized` and and `authStatus` in `brv status --headless --format json ` response), ask them to provide: 1. **API key** - for authentication (obtain from https://app.byterover.dev/settings/keys) 2. **Team and space** - names or IDs for project initialization ### Login with API Key Authenticate using an API key: ```bash brv login --api-key <key> ``` Outputs text: `Logged in as <email>` on success. ### Initialize Project Initialize ByteRover for a project (requires team and space for headless mode - can use either ID or name): ```bash # Using names brv init --headless --team my-team --space my-space --format json # Using IDs brv init --headless --team team-abc123 --space space-xyz789 --format json ``` Force re-initialization: ```bash brv init --headless --team my-team --space my-space --force --format json ``` Example response: ```json { "success": true, "command": "init", "data": { "status": "success", "teamName": "MyTeam", "spaceName": "MySpace", "configPath": "/path/to/project/.brv/config.json" } } ``` **Note**: You can use either team/space names or IDs. Names are matched case-insensitively. ### Check Status Check the current status of ByteRover and the project: ```bash brv status --headless --format json ``` Example response: ```json { "success": true, "command": "status", "data": { "cliVersion": "1.0.0", "authStatus": "logged_in", "userEmail": "user@example.com", "projectInitialized": true, "teamName": "MyTeam", "spaceName": "MySpace", "mcpStatus": "connected", "contextTreeStatus": "has_changes" } } ``` ## Query Knowledge Ask questions to retrieve relevant knowledge: ```bash brv query "How is authentication implemented?" --headless --format json ``` Example response: ```json { "success": true, "command": "query", "data": { "status": "completed", "result": "Authentication uses JWT tokens...", "toolCalls": [{"tool": "search_knowledge", "status": "success", "summary": "5 matches"}] } } ``` ## Curate Context Add new knowledge or context to the project's context tree: ```bash brv curate "Auth uses JWT with 24h expiry. Tokens stored in httpOnly cookies via authMiddleware.ts" --headless --format json ``` Include specific files for comprehensive context (max 5 files): ```bash brv curate "Authentication middleware validates JWT tokens" --files src/middleware/auth.ts --headless --format json ``` Example response: ```json { "success": true, "command": "curate", "data": { "status": "queued", "taskId": "abc123", "message": "Context queued for processing" } } ``` ## Push Context Tree Push local context tree changes to ByteRover cloud storage: ```bash brv push --headless --format json -y ``` The `-y` flag skips confirmation prompt (required for headless mode). Push to a specific branch: ```bash brv push --branch feature-branch --headless --format json -y ``` Example response: ```json { "success": true, "command": "push", "data": { "status": "success", "added": 3, "edited": 1, "deleted": 0, "branch": "main", "url": "https://app.byterover.com/team/space" } } ``` Possible statuses: - `success` - Push completed - `no_changes` - No context changes to push - `cancelled` - Push was cancelled - `error` - Push failed ## Pull Context Tree Pull context tree from ByteRover cloud storage: ```bash brv pull --headless --format json ``` Pull from a specific branch: ```bash brv pull --branch feature-branch --headless --format json ``` Example response: ```json { "success": true, "command": "pull", "data": { "status": "success", "added": 5, "edited": 2, "deleted": 1, "branch": "main", "commitSha": "abc123def" } } ``` Possible statuses: - `success` - Pull completed - `local_changes` - Local changes exist, push first - `error` - Pull failed ## Error Handling Always check the `success` field in JSON responses: - `success: true` - Operation completed successfully - `success: false` - Operation failed, check `data.error` or `data.message` for details Common error scenarios: - **Not authenticated**: Run `brv login --api-key <key>` - **Project not initialized**: Run `brv init --headless --team <team> --space <space> --format json` - **Local changes exist**: Push local changes before pulling ## Tips 1. For pull and push operations, you should ask for user permission first. 2. Always use `--headless --format json` for automation (except `brv login` which outputs text). 3. Check `brv status --headless --format json` first to verify auth and project state. 4. For curate operations, include relevant files with `--files` for better context. 5. Query responses may include tool call details showing what knowledge was searched. 6. For push operations, always use `-y` to skip confirmation in headless mode. For re-initialization, use `-f` to force re-initialization. 7. Pull will fail if there are unpushed local changes - push first.