byterover-cli 1.5.0 → 1.6.0

package/README.md

@@ -12,6 +12,8 @@ Command-line interface for ByteRover, featuring an interactive REPL with a moder
 * [Quick Start](#quick-start)
 * [Interactive REPL](#interactive-repl)
 * [Keyboard Shortcuts](#keyboard-shortcuts)
+* [CLI Commands](#cli-commands)
+* [Headless Mode](#headless-mode)
 * [What is Context Tree?](#what-is-context-tree)
 * [Supported AI Agents](#supported-ai-agents)
 * [LLM Providers](#llm-providers) (BETA)
@@ -124,7 +126,7 @@ The terminal UI includes:
 - **Streaming Output**: Live responses with markdown rendering (headings, lists, blockquotes, code blocks)
 - **Reasoning Display**: View agent thinking process with streamed reasoning blocks
 - **File References**: Type `@` in curate mode to browse and attach files
-- **PDF Support**: Reference and extract text from PDF files using `@` (up to 100 pages)
+- **PDF Support**: Reference and extract text from PDF files using `@` (100 pages default, 200 max)
 - **Dynamic Domains**: Automatically creates new knowledge domains as your context tree grows
 - **Session Persistence**: Sessions auto-resume after restart
 - **Expandable Views**: Press `Ctrl+O` to expand messages or logs to full-screen with vim-style navigation
@@ -142,17 +144,123 @@ The terminal UI includes:
 | `/` | Show command suggestions |
 | `@` | Browse files (in curate mode) |
 
-### Using Commands
+## CLI Commands
 
-In the REPL, use slash commands (commands prefixed with `/`) to interact with ByteRover:
+In addition to the interactive REPL, ByteRover CLI provides direct command-line commands for automation and scripting.
 
+### Authentication
+
+| Command | Description |
+|---------|-------------|
+| `brv login -k <key>` | Authenticate with an API key |
+
+**Example:**
+```bash
+brv login --api-key your-api-key
 ```
-/status              # Check your project status
-/curate              # Add context interactively
-/push                # Push changes to cloud
+
+Get your API key at [app.byterover.dev/settings/keys](https://app.byterover.dev/settings/keys).
+
+### Project Commands
+
+| Command | Description |
+|---------|-------------|
+| `brv init` | Initialize a project with ByteRover |
+| `brv status [dir]` | Show CLI status and project information |
+
+**Init flags:**
+- `-f, --force`: Force re-initialization without confirmation
+- `--headless`: Run in headless mode (requires `--team` and `--space`)
+- `--team <id|name>`: Team ID or name
+- `--space <id|name>`: Space ID or name
+- `--format <text|json>`: Output format (default: text)
+
+**Status flags:**
+- `-f, --format <text|json>`: Output format (default: text)
+- `--headless`: Run in headless mode
+
+### Context Operations
+
+| Command | Description |
+|---------|-------------|
+| `brv query <question>` | Query the context tree |
+| `brv curate [context]` | Curate context to the context tree |
+
+**Note:** `query` and `curate` require a running `brv` instance in another terminal.
+
+**Query flags:**
+- `--headless`: Run in headless mode
+- `--format <text|json>`: Output format (default: text)
+
+**Curate flags:**
+- `-f, --files <path>`: Include specific files (max 5, can be repeated)
+- `--headless`: Run in headless mode
+- `--format <text|json>`: Output format (default: text)
+
+### Cloud Sync
+
+| Command | Description |
+|---------|-------------|
+| `brv push` | Push context tree to ByteRover cloud |
+| `brv pull` | Pull context tree from ByteRover cloud |
+
+**Push flags:**
+- `-b, --branch <name>`: ByteRover branch name (default: main, not Git branch)
+- `-y, --yes`: Skip confirmation prompt
+- `--headless`: Run in headless mode (auto-skips confirmation)
+- `--format <text|json>`: Output format (default: text)
+
+**Pull flags:**
+- `-b, --branch <name>`: ByteRover branch name (default: main, not Git branch)
+- `--headless`: Run in headless mode
+- `--format <text|json>`: Output format (default: text)
+
+## Headless Mode
+
+ByteRover CLI supports headless mode for automation, CI/CD pipelines, and scripting. Headless mode disables interactive prompts and supports machine-readable JSON output.
+
+### Supported Commands
+
+The following commands support `--headless` mode:
+- `brv init` (requires `--team` and `--space`)
+- `brv status`
+- `brv query`
+- `brv curate`
+- `brv push` (auto-skips confirmation)
+- `brv pull`
+
+### Output Formats
+
+Use `--format` to control output:
+- `text` (default): Human-readable text output
+- `json`: NDJSON (newline-delimited JSON) for machine parsing
+
+### CI/CD Examples
+
+**Initialize a project in CI:**
+```bash
+brv login --api-key $BRV_API_KEY
+brv init --headless --team "my-team" --space "my-space" --format json
+```
+
+**Push context tree after tests pass:**
+```bash
+brv push --headless --format json -y
 ```
 
-Commands support tab completion for quick navigation.
+**Query context in a script:**
+```bash
+brv query "What are the API endpoints?" --headless --format json
+```
+
+### JSON Output Structure
+
+JSON output uses NDJSON format with message types:
+- `log`: Progress messages
+- `output`: Main output content
+- `error`: Error messages
+- `warning`: Warning messages
+- `result`: Final operation result
 
 ## What is Context Tree?
 
@@ -348,7 +456,7 @@ The model browser shows:
 **Options:**
 - `-y, --yes`: Skip confirmation prompt
 
-**Note:** Sessions are stateful and auto-resume after restart. Use `/new` to start fresh—this clears conversation history but does NOT affect the context tree.
+**Note:** Sessions are stateful and auto-resume after restart (retained for 30 days). Use `/new` to start fresh—this clears conversation history but does NOT affect the context tree.
 
 ### Project Setup
 
@@ -368,16 +476,29 @@ The model browser shows:
 
 ## Authentication
 
-ByteRover CLI uses **OAuth 2.0 with PKCE** (Proof Key for Code Exchange) for secure authentication.
+ByteRover CLI supports two authentication methods to suit different workflows.
+
+### Authentication Methods
+
+**1. OAuth 2.0 (Interactive)**
+- Use `/login` in the REPL
+- Opens browser for secure OAuth flow with PKCE
+- Best for: Local development, interactive use
+
+**2. API Key (Non-interactive)**
+- Use `brv login --api-key <key>`
+- No browser required
+- Best for: CI/CD, automation, headless environments
+- Get your key at [app.byterover.dev/settings/keys](https://app.byterover.dev/settings/keys)
 
-### How it works
+### How OAuth Works
 
 1. Run `/login` in the REPL to start authentication
 2. Your browser opens to the ByteRover authorization page
 3. After successful login, tokens are securely stored in your system keychain
 4. All subsequent commands automatically use your stored credentials
 
-### Security features
+### Security Features
 
 - **PKCE flow**: Prevents authorization code interception attacks
 - **System keychain**: Tokens stored in macOS Keychain, Windows Credential Manager, or Linux Secret Service

package/dist/core/domain/errors/headless-prompt-error.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Error thrown when headless mode encounters a prompt that cannot be handled.
+ * Provides detailed information about what prompt was required and available choices.
+ */
+export declare class HeadlessPromptError extends Error {
+    readonly availableChoices?: string[];
+    readonly code = "HEADLESS_PROMPT_REQUIRED";
+    readonly promptMessage: string;
+    readonly promptType: string;
+    constructor(promptType: string, promptMessage: string, availableChoices?: string[]);
+}

package/dist/core/domain/errors/headless-prompt-error.js

@@ -0,0 +1,18 @@
+/**
+ * Error thrown when headless mode encounters a prompt that cannot be handled.
+ * Provides detailed information about what prompt was required and available choices.
+ */
+export class HeadlessPromptError extends Error {
+    availableChoices;
+    code = 'HEADLESS_PROMPT_REQUIRED';
+    promptMessage;
+    promptType;
+    constructor(promptType, promptMessage, availableChoices) {
+        const choicesInfo = availableChoices?.length ? ` Available choices: ${availableChoices.join(', ')}` : '';
+        super(`Headless mode cannot handle ${promptType} prompt: "${promptMessage}".${choicesInfo}`);
+        this.name = 'HeadlessPromptError';
+        this.promptType = promptType;
+        this.promptMessage = promptMessage;
+        this.availableChoices = availableChoices;
+    }
+}

package/dist/core/interfaces/i-cogit-pull-service.d.ts

@@ -3,7 +3,6 @@ import type { CogitSnapshot } from '../domain/entities/cogit-snapshot.js';
  * Parameters for pulling a snapshot from CoGit.
  */
 export type PullParams = {
-    accessToken: string;
     branch: string;
     sessionKey: string;
     spaceId: string;

package/dist/core/interfaces/i-memory-retrieval-service.d.ts

@@ -1,6 +1,5 @@
 import type { RetrieveResult } from '../domain/entities/retrieve-result.js';
 export type RetrieveParams = {
-    accessToken: string;
     nodeKeys?: string[];
     query: string;
     sessionKey: string;

package/dist/core/interfaces/i-memory-storage-service.d.ts

@@ -3,7 +3,6 @@ import type { PresignedUrlsResponse } from '../domain/entities/presigned-urls-re
  * Parameters for requesting presigned URLs.
  */
 export type GetPresignedUrlsParams = {
-    accessToken: string;
     branch: string;
     fileNames: string[];
     sessionKey: string;
@@ -14,7 +13,6 @@ export type GetPresignedUrlsParams = {
  * Parameters for confirming upload completion.
  */
 export type ConfirmUploadParams = {
-    accessToken: string;
     requestId: string;
     sessionKey: string;
     spaceId: string;

package/dist/core/interfaces/i-space-service.d.ts

@@ -6,7 +6,6 @@ import type { Space } from '../domain/entities/space.js';
 export interface ISpaceService {
     /**
      * Fetches spaces accessible to the authenticated user within a specific team.
-     * @param accessToken The OAuth access token for authentication
      * @param sessionKey The session key for tracking the user session
      * @param teamId The team ID to filter spaces by
      * @param option Optional pagination options
@@ -17,7 +16,7 @@ export interface ISpaceService {
      *  - spaces: Array of Space entities
      *  - total: Total number of spaces available (across all pages)
      */
-    getSpaces: (accessToken: string, sessionKey: string, teamId: string, option?: {
+    getSpaces: (sessionKey: string, teamId: string, option?: {
         fetchAll?: boolean;
         limit?: number;
         offset?: number;

package/dist/core/interfaces/i-team-service.d.ts

@@ -6,7 +6,6 @@ import type { Team } from '../domain/entities/team.js';
 export interface ITeamService {
     /**
      * Fetches teams where the authenticated user is a member.
-     * @param accessToken The OAuth access token for authentication
      * @param sessionKey The session key for tracking the user session
      * @param option Optional filtering and pagination options
      * @param option.limit Maximum number of teams to fetch in a single request
@@ -17,7 +16,7 @@ export interface ITeamService {
      *  - teams: Array of Team entities
      *  - total: Total number of teams available (across all pages)
      */
-    getTeams: (accessToken: string, sessionKey: string, option?: {
+    getTeams: (sessionKey: string, option?: {
         fetchAll?: boolean;
         isActive?: boolean;
         limit?: number;

package/dist/core/interfaces/i-user-service.d.ts

@@ -6,9 +6,8 @@ import type { User } from '../domain/entities/user.js';
 export interface IUserService {
     /**
      * Fetches the current authenticated user's information.
-     * @param accessToken The OAuth access token for authentication
      * @param sessionKey The session key for tracking the user session
      * @returns A promise that resolves to the User entity
      */
-    getCurrentUser: (accessToken: string, sessionKey: string) => Promise<User>;
+    getCurrentUser: (sessionKey: string) => Promise<User>;
 }

package/dist/core/interfaces/usecase/i-curate-use-case.d.ts

@@ -2,6 +2,8 @@ export interface CurateUseCaseRunOptions {
     apiKey?: string;
     context?: string;
     files?: string[];
+    format?: 'json' | 'text';
+    headless?: boolean;
     model?: string;
     verbose?: boolean;
 }

package/dist/core/interfaces/usecase/i-init-use-case.d.ts

@@ -1,5 +1,11 @@
+export interface InitUseCaseRunOptions {
+    force: boolean;
+    format?: 'json' | 'text';
+    /** Space ID for headless mode (skips interactive selection) */
+    spaceId?: string;
+    /** Team ID for headless mode (skips interactive selection) */
+    teamId?: string;
+}
 export interface IInitUseCase {
-    run(options: {
-        force: boolean;
-    }): Promise<void>;
+    run(options: InitUseCaseRunOptions): Promise<void>;
 }

package/dist/core/interfaces/usecase/i-login-use-case.d.ts

@@ -1,3 +1,6 @@
+export interface LoginUseCaseRunOptions {
+    apiKey?: string;
+}
 export interface ILoginUseCase {
-    run(): Promise<void>;
+    run(options: LoginUseCaseRunOptions): Promise<void>;
 }

package/dist/core/interfaces/usecase/i-pull-use-case.d.ts

@@ -1,5 +1,7 @@
+export interface PullUseCaseRunOptions {
+    branch: string;
+    format?: 'json' | 'text';
+}
 export interface IPullUseCase {
-    run: (options: {
-        branch: string;
-    }) => Promise<void>;
+    run: (options: PullUseCaseRunOptions) => Promise<void>;
 }

package/dist/core/interfaces/usecase/i-push-use-case.d.ts

@@ -1,6 +1,8 @@
+export interface PushUseCaseRunOptions {
+    branch: string;
+    format?: 'json' | 'text';
+    skipConfirmation: boolean;
+}
 export interface IPushUseCase {
-    run(options: {
-        branch: string;
-        skipConfirmation: boolean;
-    }): Promise<void>;
+    run(options: PushUseCaseRunOptions): Promise<void>;
 }

package/dist/core/interfaces/usecase/i-query-use-case.d.ts

@@ -1,5 +1,7 @@
 export interface QueryUseCaseRunOptions {
     apiKey?: string;
+    format?: 'json' | 'text';
+    headless?: boolean;
     model?: string;
     query: string;
     verbose?: boolean;

package/dist/core/interfaces/usecase/i-status-use-case.d.ts

@@ -1,5 +1,6 @@
 export interface IStatusUseCase {
     run(options: {
         cliVersion: string;
+        format?: 'json' | 'text';
     }): Promise<void>;
 }

package/dist/infra/cipher/agent/service-initializer.d.ts

@@ -39,7 +39,7 @@ export interface SessionLLMConfig {
     temperature?: number;
     verbose?: boolean;
 }
-export type { CipherAgentServices, SessionManagerConfig, SessionServices } from '../../../core/interfaces/cipher/cipher-services.js';
+export type { CipherAgentServices, SessionManagerConfig, SessionServices, } from '../../../core/interfaces/cipher/cipher-services.js';
 /**
  * Creates shared services for CipherAgent.
  * These services are singletons shared across all sessions.

package/dist/infra/cipher/agent/service-initializer.js

@@ -232,7 +232,6 @@ export function createSessionServices(sessionId, sharedServices, httpConfig, llm
         // Use HTTP backend service (default) with generator pattern
         // Step 1: Create HTTP service
         const httpService = new ByteRoverLlmHttpService({
-            accessToken: httpConfig.accessToken,
             apiBaseUrl: httpConfig.apiBaseUrl,
             projectId: httpConfig.projectId,
             region: httpConfig.region,

package/dist/infra/cipher/http/internal-llm-http-service.d.ts

@@ -6,7 +6,6 @@ import type { GenerateContentChunk } from '../../../core/interfaces/cipher/i-con
  * ByteRover HTTP LLM provider configuration.
  */
 export interface ByteRoverHttpConfig {
-    accessToken: string;
     apiBaseUrl: string;
     projectId?: string;
     region?: string;

package/dist/infra/cipher/http/internal-llm-http-service.js

@@ -31,7 +31,6 @@ export class ByteRoverLlmHttpService {
      */
     constructor(config) {
         this.config = {
-            accessToken: config.accessToken,
             apiBaseUrl: config.apiBaseUrl,
             projectId: config.projectId ?? 'byterover',
             region: config.region ?? 'us-east1',
@@ -109,7 +108,7 @@ export class ByteRoverLlmHttpService {
      */
     async callHttpGenerate(request) {
         const url = `${this.config.apiBaseUrl}/api/llm/generate`;
-        const httpClient = new AuthenticatedHttpClient(this.config.accessToken, this.config.sessionKey);
+        const httpClient = new AuthenticatedHttpClient(this.config.sessionKey);
         const httpResponse = await httpClient.post(url, request, {
             timeout: this.config.timeout,
         });

package/dist/infra/cogit/http-cogit-pull-service.js

@@ -15,7 +15,7 @@ export class HttpCogitPullService {
     async pull(params) {
         const baseUrl = `${this.config.apiBaseUrl}/organizations/${params.teamId}/projects/${params.spaceId}/git/snapshot`;
         const url = `${baseUrl}?branch=${encodeURIComponent(params.branch)}`;
-        const httpClient = new AuthenticatedHttpClient(params.accessToken, params.sessionKey);
+        const httpClient = new AuthenticatedHttpClient(params.sessionKey);
         try {
             const response = await httpClient.get(url, {
                 timeout: this.config.timeout,

package/dist/infra/cogit/http-cogit-push-service.js

@@ -94,7 +94,6 @@ export class HttpCogitPushService {
         // Directly use axios here because of the work around to get current SHA from CoGit's error response
         const response = await axios.post(params.url, requestBody, {
             headers: {
-                Authorization: `Bearer ${params.accessToken}`,
                 'x-byterover-session-id': params.sessionKey,
             },
             timeout: this.config.timeout,

package/dist/infra/http/authenticated-http-client.d.ts

@@ -3,7 +3,6 @@ import type { HttpRequestConfig, IHttpClient } from '../../core/interfaces/i-htt
  * HTTP client implementation that automatically adds authentication headers to all requests.
  *
  * This client wraps axios and automatically includes:
- * - Authorization: Bearer {accessToken}
  * - x-byterover-session-id: {sessionKey}
  *
  * Usage:
@@ -13,9 +12,8 @@ import type { HttpRequestConfig, IHttpClient } from '../../core/interfaces/i-htt
  * ```
  */
 export declare class AuthenticatedHttpClient implements IHttpClient {
-    private readonly accessToken;
     private readonly sessionKey;
-    constructor(accessToken: string, sessionKey: string);
+    constructor(sessionKey: string);
     /**
      * Performs an HTTP GET request with authentication headers.
      * @param url The URL to request

package/dist/infra/http/authenticated-http-client.js

@@ -3,7 +3,6 @@ import axios, { isAxiosError } from 'axios';
  * HTTP client implementation that automatically adds authentication headers to all requests.
  *
  * This client wraps axios and automatically includes:
- * - Authorization: Bearer {accessToken}
  * - x-byterover-session-id: {sessionKey}
  *
  * Usage:
@@ -13,10 +12,8 @@ import axios, { isAxiosError } from 'axios';
  * ```
  */
 export class AuthenticatedHttpClient {
-    accessToken;
     sessionKey;
-    constructor(accessToken, sessionKey) {
-        this.accessToken = accessToken;
+    constructor(sessionKey) {
         this.sessionKey = sessionKey;
     }
     /**
@@ -66,7 +63,6 @@ export class AuthenticatedHttpClient {
      */
     buildHeaders(customHeaders) {
         return {
-            Authorization: `Bearer ${this.accessToken}`,
             'x-byterover-session-id': this.sessionKey,
             ...customHeaders,
         };

package/dist/infra/memory/http-memory-retrieval-service.js

@@ -16,7 +16,7 @@ export class HttpMemoryRetrievalService {
     }
     async retrieve(params) {
         try {
-            const httpClient = new AuthenticatedHttpClient(params.accessToken, params.sessionKey);
+            const httpClient = new AuthenticatedHttpClient(params.sessionKey);
             // Build query parameters
             const queryParams = this.buildQueryParams(params);
             const response = await httpClient.get(`${this.config.apiBaseUrl}/retrieve?${queryParams}`, {

package/dist/infra/memory/http-memory-storage-service.js

@@ -18,7 +18,7 @@ export class HttpMemoryStorageService {
     }
     async confirmUpload(params) {
         try {
-            const httpClient = new AuthenticatedHttpClient(params.accessToken, params.sessionKey);
+            const httpClient = new AuthenticatedHttpClient(params.sessionKey);
             const url = `${this.config.apiBaseUrl}/organizations/${params.teamId}/projects/${params.spaceId}/memory-processing/confirm-upload`;
             const requestBody = {
                 request_id: params.requestId,
@@ -33,7 +33,7 @@ export class HttpMemoryStorageService {
     }
     async getPresignedUrls(params) {
         try {
-            const httpClient = new AuthenticatedHttpClient(params.accessToken, params.sessionKey);
+            const httpClient = new AuthenticatedHttpClient(params.sessionKey);
             const url = `${this.config.apiBaseUrl}/organizations/${params.teamId}/projects/${params.spaceId}/memory-processing/presigned-urls`;
             const requestBody = {
                 branch: params.branch,

package/dist/infra/process/inline-agent-executor.d.ts

@@ -0,0 +1,32 @@
+/**
+ * InlineAgent - Ephemeral in-process CipherAgent for headless commands.
+ *
+ * Used by `brv curate --headless` and `brv query --headless` to execute tasks
+ * without requiring a running REPL instance or Transport/Socket.IO infrastructure.
+ *
+ * Exposes a `transportClient` property (ITransportClient) so use cases can use it
+ * as a drop-in replacement for SocketIOTransportClient.
+ *
+ * Lifecycle:
+ * 1. InlineAgent.create() — loads auth, config, starts CipherAgent
+ * 2. Use case gets inlineAgent.transportClient and calls on()/request() as normal
+ * 3. transportClient.disconnect() — stops CipherAgent and cleans up
+ */
+import type { ITransportClient } from '../../core/interfaces/transport/i-transport-client.js';
+/**
+ * Ephemeral in-process CipherAgent for headless CLI commands.
+ *
+ * Creates and owns a CipherAgent, and exposes an ITransportClient that
+ * use cases interact with exactly like a SocketIOTransportClient.
+ */
+export declare class InlineAgent {
+    readonly transportClient: ITransportClient;
+    private constructor();
+    /**
+     * Async factory — loads auth/config, creates and starts CipherAgent.
+     *
+     * @throws NotAuthenticatedError if no auth token or token is expired
+     * @throws Error if no project config (.brv/config.json) exists
+     */
+    static create(): Promise<InlineAgent>;
+}