Overview

Headless mode enables ByteRover CLI to run without an interactive terminal, making it ideal for CI/CD pipelines, automation scripts, and server environments where no TTY is available.

Headless mode requires ByteRover CLI v1.6.0 or later.

Key Benefits

No TTY required: Runs in environments without interactive terminals (containers, SSH sessions, CI runners)
Structured output: Choose between human-readable text or machine-parseable JSON (NDJSON)
Graceful error handling: Fails predictably when interactive prompts would be required
Independent execution: Each command runs as an ephemeral process—no running REPL instance needed

Quick Start

Authenticate with API key

brv login --api-key $BYTEROVER_API_KEY

Initialize project in headless mode

brv init --headless --team my-team --space my-space

Run commands with structured output

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

Common Flags

All headless commands support these flags:

Flag	Description	Default
`--headless`	Enable non-interactive mode (no TTY required)	`false`
`--format <text\|json>`	Output format: `text` for human-readable, `json` for NDJSON	`text`

Supported Commands

Six commands support headless execution:

Command	Required Flags	Description
`brv init`	`--team`, `--space`	Initialize project with team and space
`brv status`	None	Show CLI and project status
`brv query`	None	Query the context tree
`brv curate`	None	Curate context to the context tree
`brv push`	`-y` (skip confirmation)	Push context tree to cloud
`brv pull`	None	Pull context tree from cloud

brv init

Initialize a project in headless mode. Requires both --team and --space flags since interactive selection is unavailable.

# Initialize with team/space names
brv init --headless --team my-team --space my-space

# Initialize with IDs (more reliable in scripts)
brv init --headless --team team-abc123 --space space-xyz789

# With JSON output
brv init --headless --team my-team --space my-space --format json

# Force re-initialization
brv init --headless --team my-team --space my-space --force

brv status

Check CLI and project status without interaction.

# Text output
brv status --headless

# JSON output for parsing
brv status --headless --format json

# Check specific directory
brv status /path/to/project --headless --format json

brv query

Query the context tree for project information.

# Query with text output
brv query "How is user authentication implemented?" --headless

# Query with JSON output for scripting
brv query "What are the API endpoints?" --headless --format json

Use specific, detailed questions for best results. Avoid vague queries like “auth” or “show me code”.

brv curate

Add context to the context tree.

# Curate context
brv curate "Auth uses JWT with 24h expiry" --headless

# Curate with file references
brv curate "Session handling logic" --headless -f src/auth/session.ts

# Multiple files with JSON output
brv curate "JWT implementation" --headless -f src/auth/jwt.ts -f src/middleware/auth.ts --format json

brv push

Push context tree changes to ByteRover cloud storage.

The -y flag is required in headless mode to skip the confirmation prompt. Without it, the command will fail.

# Push to main branch
brv push --headless -y

# Push to specific branch with JSON output
brv push --headless -y --branch feature-auth --format json

brv pull

Pull context tree from ByteRover cloud storage.

# Pull from main branch
brv pull --headless

# Pull from specific branch with JSON output
brv pull --headless --branch feature-auth --format json

JSON Output Format

When using --format json, ByteRover outputs NDJSON (Newline-Delimited JSON)—one JSON object per line. This format is ideal for streaming and parsing with tools like jq.

Message Structure

Each line follows this structure:

interface HeadlessJsonMessage {
  id: string           // Unique message ID (UUID)
  type: string         // Message type (see below)
  message: string      // Content (may be nested JSON for results)
  timestamp: string    // ISO 8601 timestamp
  actionId?: string    // Links start/stop events for the same action
}

Message Types

Type	Description	When Emitted
`action_start`	Beginning of a long-running action	Operation begins
`action_stop`	End of a long-running action	Operation completes
`log`	Informational message	During execution
`warning`	Non-fatal issue	Recoverable issue detected
`error`	Fatal error	On failure
`result`	Structured result data	On success

Example Output Stream

{"id":"abc123","type":"action_start","actionId":"op-001","message":"Querying context tree","timestamp":"2026-01-15T10:30:00.000Z"}
{"id":"abc124","type":"log","message":"Found 3 relevant documents","timestamp":"2026-01-15T10:30:01.000Z"}
{"id":"abc125","type":"action_stop","actionId":"op-001","message":"","timestamp":"2026-01-15T10:30:02.000Z"}
{"id":"abc126","type":"result","message":"{\"answer\":\"Authentication uses JWT...\"}","timestamp":"2026-01-15T10:30:02.000Z"}

Authentication for Automation

Headless mode uses API key authentication instead of browser-based OAuth.

Generate an API Key

Go to ByteRover Dashboard
Click Create API Key
Copy the key (starts with brv_)
Store securely in your CI/CD secrets

Secure Storage Best Practices

Never commit API keys to version control. Use environment variables or secret managers.

# Set as environment variable
export BYTEROVER_API_KEY=brv_your_api_key_here

# Use in commands
brv login --api-key "$BYTEROVER_API_KEY"

CI/CD Secret Storage:

GitHub Actions: Repository secrets (Settings > Secrets > Actions)
GitLab CI: CI/CD variables (Settings > CI/CD > Variables, masked)
Jenkins: Credentials plugin with secret text

Environment Auto-Detection

ByteRover CLI automatically detects headless Linux environments and adjusts behavior accordingly.

Detected Environments

The CLI recognizes these as headless environments:

Environment	Detection Method
SSH sessions	`SSH_TTY` or `SSH_CONNECTION` environment variables
Docker containers	`/.dockerenv` file exists
WSL (Windows Subsystem for Linux)	`WSL_DISTRO_NAME`, `WSLENV`, or `/proc/version` contains “microsoft”
No display server	`DISPLAY` and `WAYLAND_DISPLAY` unset
No D-Bus session	`DBUS_SESSION_BUS_ADDRESS` unset

Token Storage Fallback

When the system keychain is unavailable (common in headless environments), ByteRover automatically uses file-based token storage:

# Linux/WSL file-based storage location
~/.local/share/brv/

# macOS (when keychain available)
Stored in system keychain under "ByteRover CLI"

Error Handling

HeadlessPromptError

When a command requires interactive input that cannot be provided in headless mode, ByteRover throws a HeadlessPromptError:

{
  "id": "err-001",
  "type": "error",
  "message": "{\"code\":\"HEADLESS_PROMPT_REQUIRED\",\"promptType\":\"select\",\"promptMessage\":\"Select a team\",\"availableChoices\":[\"team-1\",\"team-2\",\"team-3\"]}",
  "timestamp": "2026-01-15T10:30:00.000Z"
}

Error Properties:

Property	Description
`code`	Always `HEADLESS_PROMPT_REQUIRED`
`promptType`	Type of prompt: `confirm`, `select`, `input`, `search`, `file_selector`
`promptMessage`	The prompt that could not be answered
`availableChoices`	For select prompts, the available options

Common Error Scenarios

Error	Cause	Solution
Missing `--team` or `--space`	`brv init --headless` without required flags	Provide both `--team` and `--space`
Confirmation required	`brv push --headless` without `-y`	Add `-y` flag to skip confirmation
Not authenticated	No valid API key or token	Run `brv login --api-key` first
Project not initialized	No `.brv/` directory	Run `brv init --headless` first

Troubleshooting

Headless mode requires both --team and --space flags

Cause: Running brv init --headless without specifying team and space.Solution: Provide both flags:

brv init --headless --team my-team --space my-space

You can use either names or IDs. IDs are more reliable in scripts as names may change.

Command requires a running brv instance

Cause: Running brv query or brv curate without --headless flag when no REPL is running.Solution: Add the --headless flag to run independently:

brv query "question" --headless
brv curate "context" --headless

JSON output not appearing

Cause: Errors are written to stderr, not stdout.Solution: Redirect both streams when capturing output:

brv status --headless --format json 2>&1

Authentication fails in CI/CD

Cause: Keychain unavailable, token expired, or incorrect API key.Solution:

Verify the API key is correct and not expired
Ensure the BYTEROVER_API_KEY secret is properly configured
Re-run brv login --api-key $BYTEROVER_API_KEY
Check that the secret is not masked in a way that corrupts special characters

Permission denied for token storage

Cause: Cannot write to ~/.local/share/brv/ directory.Solution: Ensure the directory exists and is writable:

mkdir -p ~/.local/share/brv
chmod 700 ~/.local/share/brv

Next Steps

CLI Reference

Complete command reference for all ByteRover CLI commands

Team Context Sync

Learn collaborative workflows for sharing context across teams

Security

Security practices and data protection information

Troubleshooting

Common issues and solutions for ByteRover CLI

Getting Started

Context Tree

Agent Connectors

External LLM Providers (BETA)

Headless Mode

Reference

FAQs

Security

Key Benefits

Quick Start

Common Flags

Supported Commands

brv init

brv status

brv query

brv curate

brv push

brv pull

JSON Output Format

Message Structure

Message Types

Example Output Stream

Authentication for Automation

Generate an API Key

Secure Storage Best Practices

Environment Auto-Detection

Detected Environments

Token Storage Fallback

Error Handling

HeadlessPromptError

Common Error Scenarios

Troubleshooting

Next Steps

CLI Reference

Team Context Sync

Security

Troubleshooting

Getting Started

Context Tree

Agent Connectors

External LLM Providers (BETA)

Headless Mode

Reference

FAQs

Security

​Key Benefits

​Quick Start

​Common Flags

​Supported Commands

​brv init

​brv status

​brv query

​brv curate

​brv push

​brv pull

​JSON Output Format

​Message Structure

​Message Types

​Example Output Stream

​Authentication for Automation

​Generate an API Key

​Secure Storage Best Practices

​Environment Auto-Detection

​Detected Environments

​Token Storage Fallback

​Error Handling

​HeadlessPromptError

​Common Error Scenarios

​Troubleshooting

​Next Steps

CLI Reference

Team Context Sync

Security

Troubleshooting

Key Benefits

Quick Start

Common Flags

Supported Commands

brv init

brv status

brv query

brv curate

brv push

brv pull

JSON Output Format

Message Structure

Message Types

Example Output Stream

Authentication for Automation

Generate an API Key

Secure Storage Best Practices

Environment Auto-Detection

Detected Environments

Token Storage Fallback

Error Handling

HeadlessPromptError

Common Error Scenarios

Troubleshooting

Next Steps