byterover-cli 1.4.0 → 1.6.0

package/README.md

@@ -12,8 +12,11 @@ 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)
 * [Slash Commands Reference](#slash-commands-reference)
 * [Authentication](#authentication)
 * [Configuration](#configuration)
@@ -51,7 +54,7 @@ brv --version
 
 Visit [**ByteRover Docs**](https://docs.byterover.dev) for more information.
 
-Get started with ByteRover CLI in three simple steps:
+Get started with ByteRover CLI:
 
 ### 1. Start the REPL
 
@@ -91,6 +94,14 @@ ByteRover automatically configures the best connector for your installed agents:
 - **MCP tools** for most other agents (universal protocol)
 - Switch connector types anytime via `/connectors`
 
+### 5. (Optional) Connect an LLM Provider
+
+```
+/provider
+```
+
+ByteRover works out of the box with its built-in LLM provider. To use your own models, connect to [OpenRouter](https://openrouter.ai/keys) for access to 200+ models. See [LLM Providers](#llm-providers) for details.
+
 You're now ready to use ByteRover! Try `/status` to see your project's current state.
 
 ## Interactive REPL
@@ -115,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
@@ -133,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
+```
+
+**Query context in a script:**
+```bash
+brv query "What are the API endpoints?" --headless --format json
 ```
 
-Commands support tab completion for quick navigation.
+### 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?
 
@@ -203,6 +320,48 @@ ByteRover supports four connector types:
 - All others (16 agents): MCP connector
 - Rules: Available for all agents as fallback
 
+## LLM Providers (BETA)
+
+ByteRover uses LLMs internally to power `/curate` and `/query` operations. By default, the built-in ByteRover provider is used with no configuration required. You can optionally connect to OpenRouter to access 200+ models.
+
+### Available Providers
+
+| Provider | API Key Required | Models |
+|----------|-----------------|--------|
+| **ByteRover** (default) | No | Built-in internal model |
+| **OpenRouter** | Yes | 200+ models from Anthropic, OpenAI, Google, Meta, and more |
+
+### Connecting a Provider
+
+Use `/provider` (aliases: `/providers`, `/connect`) to switch providers:
+
+```
+/provider
+```
+
+This opens an interactive prompt showing all available providers with their connection status.
+
+### Selecting a Model
+
+When connected to OpenRouter, use `/model` (alias: `/models`) to browse and select models:
+
+```
+/model
+```
+
+The model browser shows:
+- **Pricing**: Input/output cost per million tokens (e.g., `$3.00/$15.00/M`)
+- **Context window**: Maximum token capacity (e.g., `200K ctx`)
+- **Free models**: Marked with `[Free]`
+- **Favorites and recents**: Starred and recently used models appear first
+
+### OpenRouter Setup
+
+1. Get an API key at [openrouter.ai/keys](https://openrouter.ai/keys)
+2. Run `/provider` and select **OpenRouter**
+3. Paste your API key when prompted (stored securely in system keychain)
+4. Run `/model` to select a model (default: `anthropic/claude-3.5-sonnet`)
+
 ## Slash Commands Reference
 
 ### Core Workflow
@@ -279,6 +438,15 @@ ByteRover supports four connector types:
 **Reset options:**
 - `-y, --yes`: Skip confirmation prompt
 
+### LLM Providers (BETA)
+
+| Command | Description |
+|---------|-------------|
+| `/provider` | Connect to and switch between LLM providers |
+| `/model` | Select a model from the active provider (OpenRouter) |
+
+**Aliases:** `/providers` and `/connect` for `/provider`; `/models` for `/model`
+
 ### Session Management
 
 | Command | Description |
@@ -288,7 +456,7 @@ ByteRover supports four connector types:
 **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
 
@@ -308,16 +476,29 @@ ByteRover supports four connector types:
 
 ## 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/cipher/process/types.d.ts

@@ -82,7 +82,7 @@ export interface ExecuteOptions {
     /**
      * Timeout in milliseconds (max: ProcessConfig.maxTimeout).
      *
-     * @default 120000 (2 minutes)
+     * @default 300000 (5 minutes)
      */
     timeout?: number;
 }

package/dist/core/domain/entities/provider-config.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Provider Configuration Entity
+ *
+ * Stores user's provider preferences and connection state.
+ * Non-sensitive data (API keys stored separately in keychain).
+ */
+/**
+ * Configuration for a single connected provider.
+ */
+export interface ConnectedProviderConfig {
+    /** Currently active model for this provider */
+    readonly activeModel?: string;
+    /** When the provider was connected */
+    readonly connectedAt: string;
+    /** User's favorite models (for quick access) */
+    readonly favoriteModels: readonly string[];
+    /** Recently used models (last 10) */
+    readonly recentModels: readonly string[];
+}
+/**
+ * Parameters for creating a ProviderConfig.
+ */
+export interface ProviderConfigParams {
+    /** Currently active provider ID */
+    readonly activeProvider: string;
+    /** Configuration for each connected provider */
+    readonly providers: Readonly<Record<string, ConnectedProviderConfig>>;
+}
+/**
+ * Default configuration when no providers are connected.
+ */
+export declare const DEFAULT_PROVIDER_CONFIG: ProviderConfigParams;
+/**
+ * Represents the provider configuration for the CLI.
+ * Tracks which providers are connected and user preferences.
+ */
+export declare class ProviderConfig {
+    readonly activeProvider: string;
+    readonly providers: Readonly<Record<string, ConnectedProviderConfig>>;
+    private constructor();
+    /**
+     * Creates a new ProviderConfig with default values.
+     */
+    static createDefault(): ProviderConfig;
+    /**
+     * Deserializes config from JSON format.
+     * Returns default config for invalid JSON structure.
+     */
+    static fromJson(json: unknown): ProviderConfig;
+    /**
+     * Get the active model for a provider.
+     */
+    getActiveModel(providerId: string): string | undefined;
+    /**
+     * Get favorite models for a provider.
+     */
+    getFavoriteModels(providerId: string): readonly string[];
+    /**
+     * Get recent models for a provider.
+     */
+    getRecentModels(providerId: string): readonly string[];
+    /**
+     * Check if a provider is connected.
+     */
+    isProviderConnected(providerId: string): boolean;
+    /**
+     * Serializes the config to JSON format.
+     */
+    toJson(): ProviderConfigParams;
+    /**
+     * Create a new config with the active model changed for a provider.
+     */
+    withActiveModel(providerId: string, modelId: string): ProviderConfig;
+    /**
+     * Create a new config with the active provider changed.
+     */
+    withActiveProvider(providerId: string): ProviderConfig;
+    /**
+     * Create a new config with a model toggled as favorite.
+     */
+    withFavoriteToggled(providerId: string, modelId: string): ProviderConfig;
+    /**
+     * Create a new config with a provider connected.
+     */
+    withProviderConnected(providerId: string, options?: {
+        activeModel?: string;
+    }): ProviderConfig;
+    /**
+     * Create a new config with a provider disconnected.
+     */
+    withProviderDisconnected(providerId: string): ProviderConfig;
+}

package/dist/core/domain/entities/provider-config.js

@@ -0,0 +1,181 @@
+/**
+ * Provider Configuration Entity
+ *
+ * Stores user's provider preferences and connection state.
+ * Non-sensitive data (API keys stored separately in keychain).
+ */
+/**
+ * Type guard for ProviderConfig JSON validation.
+ */
+const isProviderConfigJson = (json) => {
+    if (typeof json !== 'object' || json === null)
+        return false;
+    const obj = json;
+    if (typeof obj.activeProvider !== 'string')
+        return false;
+    if (typeof obj.providers !== 'object' || obj.providers === null)
+        return false;
+    return true;
+};
+/**
+ * Default configuration when no providers are connected.
+ */
+export const DEFAULT_PROVIDER_CONFIG = {
+    activeProvider: 'byterover',
+    providers: {},
+};
+/**
+ * Maximum number of recent models to track.
+ */
+const MAX_RECENT_MODELS = 10;
+/**
+ * Represents the provider configuration for the CLI.
+ * Tracks which providers are connected and user preferences.
+ */
+export class ProviderConfig {
+    activeProvider;
+    providers;
+    constructor(params) {
+        this.activeProvider = params.activeProvider;
+        this.providers = params.providers;
+    }
+    /**
+     * Creates a new ProviderConfig with default values.
+     */
+    static createDefault() {
+        return new ProviderConfig(DEFAULT_PROVIDER_CONFIG);
+    }
+    /**
+     * Deserializes config from JSON format.
+     * Returns default config for invalid JSON structure.
+     */
+    static fromJson(json) {
+        if (!isProviderConfigJson(json)) {
+            return ProviderConfig.createDefault();
+        }
+        return new ProviderConfig(json);
+    }
+    /**
+     * Get the active model for a provider.
+     */
+    getActiveModel(providerId) {
+        return this.providers[providerId]?.activeModel;
+    }
+    /**
+     * Get favorite models for a provider.
+     */
+    getFavoriteModels(providerId) {
+        return this.providers[providerId]?.favoriteModels ?? [];
+    }
+    /**
+     * Get recent models for a provider.
+     */
+    getRecentModels(providerId) {
+        return this.providers[providerId]?.recentModels ?? [];
+    }
+    /**
+     * Check if a provider is connected.
+     */
+    isProviderConnected(providerId) {
+        return providerId in this.providers;
+    }
+    /**
+     * Serializes the config to JSON format.
+     */
+    toJson() {
+        return {
+            activeProvider: this.activeProvider,
+            providers: this.providers,
+        };
+    }
+    /**
+     * Create a new config with the active model changed for a provider.
+     */
+    withActiveModel(providerId, modelId) {
+        const existingConfig = this.providers[providerId];
+        if (!existingConfig) {
+            return this;
+        }
+        // Add to recent models (at the front, deduplicated)
+        const recentModels = [
+            modelId,
+            ...existingConfig.recentModels.filter((m) => m !== modelId),
+        ].slice(0, MAX_RECENT_MODELS);
+        const newProviderConfig = {
+            ...existingConfig,
+            activeModel: modelId,
+            recentModels,
+        };
+        return new ProviderConfig({
+            ...this.toJson(),
+            providers: {
+                ...this.providers,
+                [providerId]: newProviderConfig,
+            },
+        });
+    }
+    /**
+     * Create a new config with the active provider changed.
+     */
+    withActiveProvider(providerId) {
+        return new ProviderConfig({
+            ...this.toJson(),
+            activeProvider: providerId,
+        });
+    }
+    /**
+     * Create a new config with a model toggled as favorite.
+     */
+    withFavoriteToggled(providerId, modelId) {
+        const existingConfig = this.providers[providerId];
+        if (!existingConfig) {
+            return this;
+        }
+        const isFavorite = existingConfig.favoriteModels.includes(modelId);
+        const favoriteModels = isFavorite
+            ? existingConfig.favoriteModels.filter((m) => m !== modelId)
+            : [...existingConfig.favoriteModels, modelId];
+        const newProviderConfig = {
+            ...existingConfig,
+            favoriteModels,
+        };
+        return new ProviderConfig({
+            ...this.toJson(),
+            providers: {
+                ...this.providers,
+                [providerId]: newProviderConfig,
+            },
+        });
+    }
+    /**
+     * Create a new config with a provider connected.
+     */
+    withProviderConnected(providerId, options) {
+        const existingConfig = this.providers[providerId];
+        const newProviderConfig = {
+            activeModel: options?.activeModel ?? existingConfig?.activeModel,
+            connectedAt: existingConfig?.connectedAt ?? new Date().toISOString(),
+            favoriteModels: existingConfig?.favoriteModels ?? [],
+            recentModels: existingConfig?.recentModels ?? [],
+        };
+        return new ProviderConfig({
+            ...this.toJson(),
+            providers: {
+                ...this.providers,
+                [providerId]: newProviderConfig,
+            },
+        });
+    }
+    /**
+     * Create a new config with a provider disconnected.
+     */
+    withProviderDisconnected(providerId) {
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const { [providerId]: _removed, ...remainingProviders } = this.providers;
+        const newActiveProvider = this.activeProvider === providerId ? 'byterover' : this.activeProvider;
+        return new ProviderConfig({
+            activeProvider: newActiveProvider,
+            providers: remainingProviders,
+        });
+    }
+}

package/dist/core/domain/entities/provider-registry.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Provider Registry
+ *
+ * Defines available LLM providers that can be connected to byterover-cli.
+ * Inspired by OpenCode's provider system.
+ */
+/**
+ * Definition for an LLM provider.
+ */
+export interface ProviderDefinition {
+    /** URL where users can get an API key */
+    readonly apiKeyUrl?: string;
+    /** API base URL (empty for internal providers) */
+    readonly baseUrl: string;
+    /** Category for grouping in UI */
+    readonly category: 'other' | 'popular';
+    /** Default model to use when first connected */
+    readonly defaultModel?: string;
+    /** Short description */
+    readonly description: string;
+    /** Default headers for API requests */
+    readonly headers: Readonly<Record<string, string>>;
+    /** Unique provider identifier */
+    readonly id: string;
+    /** Endpoint to fetch available models */
+    readonly modelsEndpoint: string;
+    /** Display name */
+    readonly name: string;
+    /** Priority for display order (lower = higher priority) */
+    readonly priority: number;
+}
+/**
+ * Registry of all available providers.
+ * Order by priority for consistent display.
+ */
+export declare const PROVIDER_REGISTRY: Readonly<Record<string, ProviderDefinition>>;
+/**
+ * Get all providers sorted by priority.
+ */
+export declare function getProvidersSortedByPriority(): ProviderDefinition[];
+/**
+ * Get providers grouped by category.
+ */
+export declare function getProvidersGroupedByCategory(): {
+    other: ProviderDefinition[];
+    popular: ProviderDefinition[];
+};
+/**
+ * Get a provider by ID.
+ */
+export declare function getProviderById(id: string): ProviderDefinition | undefined;
+/**
+ * Check if a provider requires an API key.
+ */
+export declare function providerRequiresApiKey(id: string): boolean;

package/dist/core/domain/entities/provider-registry.js

@@ -0,0 +1,74 @@
+/**
+ * Provider Registry
+ *
+ * Defines available LLM providers that can be connected to byterover-cli.
+ * Inspired by OpenCode's provider system.
+ */
+/**
+ * Registry of all available providers.
+ * Order by priority for consistent display.
+ */
+export const PROVIDER_REGISTRY = {
+    byterover: {
+        baseUrl: '',
+        category: 'popular',
+        description: 'Internal ByteRover LLM',
+        headers: {},
+        id: 'byterover',
+        modelsEndpoint: '',
+        name: 'ByteRover',
+        priority: 0,
+    },
+    openrouter: {
+        apiKeyUrl: 'https://openrouter.ai/keys',
+        baseUrl: 'https://openrouter.ai/api/v1',
+        category: 'popular',
+        defaultModel: 'anthropic/claude-3.5-sonnet',
+        description: 'Access 200+ models',
+        headers: {
+            'HTTP-Referer': 'https://byterover.dev',
+            'X-Title': 'byterover-cli',
+        },
+        id: 'openrouter',
+        modelsEndpoint: '/models',
+        name: 'OpenRouter',
+        priority: 1,
+    },
+    // Future providers can be added here:
+    // anthropic: { ... },
+    // openai: { ... },
+    // google: { ... },
+    // groq: { ... },
+};
+/**
+ * Get all providers sorted by priority.
+ */
+export function getProvidersSortedByPriority() {
+    return Object.values(PROVIDER_REGISTRY).sort((a, b) => a.priority - b.priority);
+}
+/**
+ * Get providers grouped by category.
+ */
+export function getProvidersGroupedByCategory() {
+    const providers = getProvidersSortedByPriority();
+    return {
+        other: providers.filter((p) => p.category === 'other'),
+        popular: providers.filter((p) => p.category === 'popular'),
+    };
+}
+/**
+ * Get a provider by ID.
+ */
+export function getProviderById(id) {
+    return PROVIDER_REGISTRY[id];
+}
+/**
+ * Check if a provider requires an API key.
+ */
+export function providerRequiresApiKey(id) {
+    const provider = getProviderById(id);
+    if (!provider)
+        return false;
+    // Internal providers (empty baseUrl) don't need API keys
+    return provider.baseUrl.length > 0;
+}