ByteRover - Headless

Query and curate knowledge-base using ByteRover CLI. Use `brv query` for knowledge retrieval, `brv curate` for adding context, and `brv push/pull` for syncing.

Security Scan

The skill is a thin wrapper for the official ByteRover CLI (npm @byterover/cli); its requirements, install method, and runtime instructions are consistent with its stated purpose.

Purpose & Capability

Name/description match the actual requirements and behavior: the skill requires the 'brv' binary and the install spec installs the @byterover/cli package which provides that binary. Nothing requested by the skill (no unrelated binaries, env vars, or config paths) is out of scope for a CLI integration.

Instruction Scope

SKILL.md stays within ByteRover CLI operations (login, init, status, query, curate, push, pull). It asks the user to supply an API key at runtime (via brv login) and to include up to 5 files for curate; it does not instruct the agent to read arbitrary system files or unrelated credentials. Note: brv login outputs text (not JSON), and credentials/config are stored under the project's .brv directory according to examples — automation should handle that and avoid exposing secrets.

Install Mechanism

Install uses npm to add @byterover/cli and create the 'brv' binary. npm is an expected mechanism for a Node-based CLI. This will write files/binaries to the environment (node_modules/.bin or global install depending on setup), so users should verify the package's provenance before installing.

Credentials

The skill declares no required environment variables, which is consistent. Runtime usage requires an API key for login (entered interactively or supplied to brv); this is appropriate for a remote service. Be aware the CLI likely writes auth tokens/config to .brv in the project directory (example shown), so secrets may be persisted on disk — use a least-privileged API key and/or a dedicated account.

Persistence & Privilege

always:false and no requests to modify other skills or system-wide agent settings. The skill does not ask for permanent platform privileges. The ability to run commands autonomously is the platform default but is not combined with other concerning privileges here.

Assessment

This skill is a straightforward adapter for the ByteRover CLI, but before installing: 1) verify the npm package (@byterover/cli) and its publisher (check the npm registry and package source) to ensure it's the official ByteRover client; 2) when using it, supply a dedicated, least-privileged API key rather than broad or production credentials; 3) be aware the CLI stores auth/config under .brv in your project — inspect that file if you are concerned about persisted tokens and protect its directory; 4) automation will use flags like --headless --format json and brv push -y (which skips confirmations) — avoid -y unless you want to allow destructive/remote changes without manual confirmation; 5) if you need stronger assurance, review the installed package contents (node_modules or the published tarball) before running it.

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:

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

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

brv init --headless --team my-team --space my-space --force --format json

Example response:

{
  "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:

brv status --headless --format json

Example response:

{
  "success": true,
  "command": "status",
  "data": {
    "cliVersion": "1.0.0",
    "authStatus": "logged_in",
    "userEmail": "[e-mail]",
    "projectInitialized": true,
    "teamName": "MyTeam",
    "spaceName": "MySpace",
    "mcpStatus": "connected",
    "contextTreeStatus": "has_changes"
  }
}

Query Knowledge

Ask questions to retrieve relevant knowledge:

brv query "How is authentication implemented?" --headless --format json

Example response:

{
  "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:

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

brv curate "Authentication middleware validates JWT tokens" --files src/middleware/auth.ts --headless --format json

Example response:

{
  "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:

brv push --headless --format json -y

The -y flag skips confirmation prompt (required for headless mode).

Push to a specific branch:

brv push --branch feature-branch --headless --format json -y

Example response:

{
  "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:

brv pull --headless --format json

Pull from a specific branch:

brv pull --branch feature-branch --headless --format json

Example response:

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