byterover-cli 0.3.5 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # ByteRover CLI
 
-Command-line interface for ByteRover, enabling seamless team/space management, authentication, and space's memory operations directly from your terminal.
+Command-line interface for ByteRover, featuring an interactive REPL with a modern terminal UI for managing your project's context tree and memory storage.
 
 [![Version](https://img.shields.io/npm/v/byterover-cli.svg)](https://npmjs.org/package/byterover-cli)
 [![Downloads/week](https://img.shields.io/npm/dw/byterover-cli.svg)](https://npmjs.org/package/byterover-cli)
@@ -18,8 +18,9 @@ Please check the migration guide [here](https://docs.byterover.dev/beta/migratio
 
 * [Installation](#installation)
 * [Quick Start](#quick-start)
+* [Interactive REPL](#interactive-repl)
 * [What is Context Tree?](#what-is-context-tree)
-* [Essential Commands](#essential-commands)
+* [Slash Commands Reference](#slash-commands-reference)
 * [Authentication](#authentication)
 * [Configuration](#configuration)
 * [Getting Help](#getting-help)
@@ -56,26 +57,58 @@ Visit [**ByteRover's Beta Docs**](https://docs.byterover.dev/beta) for more info
 
 Get started with ByteRover CLI in three simple steps:
 
-### 1. Authenticate
+### 1. Start the REPL
 
 ```bash
-brv login
+cd to/your/project
+brv
+```
+
+This launches the interactive REPL with a modern terminal UI.
+
+### 2. Authenticate
+
+In the REPL, type:
+
+```
+/login
 ```
 
 This opens your browser to complete OAuth authentication. Your credentials are securely stored in the system keychain.
 
-### 2. Initialize a project
+### 3. Initialize your project
+
+```
+/init
+```
+
+Select a team and space from your available options, and ByteRover will set up your project's context tree.
+
+You're now ready to use ByteRover! Try `/status` to see your project's current state.
+
+## Interactive REPL
+
+ByteRover CLI features an interactive REPL (Read-Eval-Print Loop) with a React/Ink-based terminal UI.
+
+### Starting the REPL
 
 ```bash
-cd to/your/project
-brv init
+brv
 ```
 
-Select a space from your available spaces and configure your project.
+Running `brv` without arguments starts the interactive REPL. The REPL requires an interactive terminal (TTY).
+
+### Using Commands
+
+In the REPL, use slash commands (commands prefixed with `/`) to interact with ByteRover:
 
-### 3. Start using ByteRover
+```
+/status              # Check your project status
+/curate              # Add context interactively
+/push                # Push changes to cloud
+```
 
-You're ready to use ByteRover commands in your project!
+Commands support tab completion for quick navigation.
 
 ## What is Context Tree?
 
@@ -96,62 +129,88 @@ The context tree organizes knowledge into:
 - **Topics**: Specific subjects within domains (e.g., Authentication, Components)
 - **Context Files**: Markdown files containing your actual knowledge
 
-For comprehensive instructions for coding agents, check the generated rule files after running `brv gen-rules`.
+For comprehensive instructions for coding agents, use `/gen-rules` to generate rule files.
 
-## Essential Commands
+## Slash Commands Reference
 
-### Authentication
+### Core Workflow
 
-```bash
-# Log in to ByteRover
-brv login
+| Command | Description |
+|---------|-------------|
+| `/status` | Show CLI status and project information |
+| `/curate [context] @files` | Curate context to the context tree |
+| `/query <question>` | Query and retrieve information from the context tree |
 
-# Log out and clear credentials
-brv logout
+**Curate examples:**
+```
+/curate                                    # Interactive mode
+/curate "Auth uses JWT tokens"             # Autonomous mode with text
+/curate "API docs" @src/api.ts @README.md  # With file references (max 5)
+```
 
-# Check your authentication and project status
-brv status
+**Query example:**
+```
+/query How is authentication implemented?
+/q What endpoints exist?                   # /q is an alias for /query
 ```
 
-### Project Setup
+### Sync Operations
 
-```bash
-# Initialize project with ByteRover
-brv init
+| Command | Description |
+|---------|-------------|
+| `/push [-b branch] [-y]` | Push context tree to ByteRover memory storage |
+| `/pull [-b branch]` | Pull context tree from ByteRover memory storage |
 
-# List available spaces
-brv space list
+**Options:**
+- `-b, --branch <name>`: ByteRover branch name (default: `main`)
+- `-y, --yes`: Skip confirmation prompt
 
-# Switch to a different space or team
-brv space switch
+**Examples:**
+```
+/push                    # Push to main branch
+/push -b feature-auth    # Push to a specific branch
+/push -y                 # Push without confirmation
+/pull -b feature-auth    # Pull from a specific branch
 ```
 
-### Memory Operations
+### Space Management
 
-```bash
-# Add content to context tree (interactive or autonomous)
-brv curate
-brv curate "User authentication uses JWT tokens"
+| Command | Description |
+|---------|-------------|
+| `/space list` | List all spaces for the current team |
+| `/space switch` | Switch to a different space |
 
-# Push your context tree to ByteRover's memory storage
-brv push
+**Space list options:**
+- `-a, --all`: Fetch all spaces
+- `-j, --json`: Output in JSON format
+- `-l, --limit <n>`: Maximum spaces to fetch (default: 50)
+- `-o, --offset <n>`: Number of spaces to skip
 
-# Pull context tree from ByteRover cloud
-brv pull
+### Context Tree Management
 
-# Query the context tree
-brv query "How is authentication implemented?"
+| Command | Description |
+|---------|-------------|
+| `/gen-rules` | Generate rule instructions for coding agents |
+| `/clear [-y] [directory]` | Reset context tree to default domains |
 
-# Reset context tree to default state
-brv clear
-```
+**Clear options:**
+- `-y, --yes`: Skip confirmation prompt
 
-### For Coding Agents
+### Project Setup
 
-```bash
-# Generate agent rules (sets up context tree workflow for your coding agent)
-brv gen-rules
-```
+| Command | Description |
+|---------|-------------|
+| `/init [-f]` | Initialize a project with ByteRover |
+
+**Options:**
+- `-f, --force`: Force re-initialization without confirmation
+
+### Authentication
+
+| Command | Description |
+|---------|-------------|
+| `/login` | Authenticate with ByteRover using OAuth 2.0 + PKCE |
+| `/logout [-y]` | Log out and clear authentication |
 
 ## Authentication
 
@@ -159,7 +218,7 @@ ByteRover CLI uses **OAuth 2.0 with PKCE** (Proof Key for Code Exchange) for sec
 
 ### How it works
 
-1. Run `brv login` to start authentication
+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
@@ -167,7 +226,7 @@ ByteRover CLI uses **OAuth 2.0 with PKCE** (Proof Key for Code Exchange) for sec
 ### Security features
 
 - **PKCE flow**: Prevents authorization code interception attacks
-- **System keychain**: Tokens stored in macOS Keychain
+- **System keychain**: Tokens stored in macOS Keychain, Windows Credential Manager, or Linux Secret Service
 - **Session tracking**: Each session includes a session key for request tracking
 - **Auto-refresh**: Refresh tokens enable seamless credential renewal
 
@@ -175,7 +234,7 @@ ByteRover CLI uses **OAuth 2.0 with PKCE** (Proof Key for Code Exchange) for sec
 
 ### Project Configuration
 
-When you run `brv init`, a configuration file is created at `.brv/config.json` in your project directory containing:
+When you run `/init`, a configuration file is created at `.brv/config.json` in your project directory containing:
 
 - **Space ID**: The ByteRover workspace/space associated with this project
 - **User information**: Your user ID and email
@@ -204,33 +263,30 @@ The context tree is stored in `.brv/context-tree/`:
         └── context.md
 ```
 
-**Note**: When you run `brv push`, your context tree is uploaded to ByteRover's memory storage for version control and team collaboration.
+**Note**: When you run `/push`, your context tree is uploaded to ByteRover's memory storage for version control and team collaboration.
 
 ## Getting Help
 
+### In-REPL Help
+
+Start typing `/` in the REPL to see available commands with tab completion.
+
 ### Command Help
 
 ```bash
 # Get general help
 brv --help
-
-# Get help for a specific command
-brv login --help
-brv init --help
-brv push --help
-brv pull --help
-brv query --help
-brv clear --help
 ```
 
 ### Support
 
 If you encounter issues or have questions:
 
-1. Check the command help: `brv [command] --help`
-2. Review your status: `brv status`
-3. Contact ByteRover support
+1. Check the command help in the REPL
+2. Run `/status` to review your project state
+3. Visit [ByteRover Docs](https://docs.byterover.dev/beta)
+4. Contact ByteRover support
 
 ---
 
-**Copyright (c) ByteRover**
+**Copyright (c) ByteRover**

package/bin/dev.js

@@ -1,7 +1,14 @@
-#!/usr/bin/env -S node --loader ts-node/esm --no-warnings=ExperimentalWarning
+#!/usr/bin/env -S node --import tsx --no-warnings
 
 process.env.BRV_ENV = 'development'
 
 import {execute} from '@oclif/core'
 
+// Inject default command 'main' (represents logic of a single 'brv' run) when no args provided
+// process.argv = ['node', 'bin/dev.js', ...userArgs]
+const userArgs = process.argv.slice(2)
+if (userArgs.length === 0) {
+  process.argv.push('main')
+}
+
 await execute({development: true, dir: import.meta.url})

package/bin/run.js

@@ -4,4 +4,11 @@ process.env.BRV_ENV = 'production'
 
 import {execute} from '@oclif/core'
 
+// Inject default command 'main' (represents logic of a single 'brv' run) when no args provided
+// process.argv = ['node', 'brv', ...userArgs]
+const userArgs = process.argv.slice(2)
+if (userArgs.length === 0) {
+  process.argv.push('main')
+}
+
 await execute({dir: import.meta.url})

package/dist/commands/cipher-agent/run.d.ts

@@ -1,5 +1,6 @@
 import { Command } from '@oclif/core';
 import type { IProjectConfigStore } from '../../core/interfaces/i-project-config-store.js';
+import type { ITerminal } from '../../core/interfaces/i-terminal.js';
 import { CipherAgent } from '../../infra/cipher/cipher-agent.js';
 export default class CipherAgentRun extends Command {
     static args: {
@@ -19,6 +20,7 @@ export default class CipherAgentRun extends Command {
         verbose?: import("@oclif/core/interfaces").BooleanFlag<boolean> | undefined;
     };
     static hidden: boolean;
+    protected terminal: ITerminal;
     catch(error: Error & {
         oclif?: {
             exit: number;
@@ -70,6 +72,34 @@ export default class CipherAgentRun extends Command {
      * @returns LLM configuration object
      */
     private createLLMConfig;
+    /**
+     * Format curate tool result summary
+     *
+     * @param result - Tool result data
+     * @returns Formatted summary string or empty
+     */
+    private formatCurateResult;
+    /**
+     * Format find_knowledge_topics tool result summary
+     *
+     * @param result - Tool result data
+     * @returns Formatted summary string or empty
+     */
+    private formatFindKnowledgeTopicsResult;
+    /**
+     * Format grep_content tool result summary
+     *
+     * @param result - Tool result data
+     * @returns Formatted summary string or empty
+     */
+    private formatGrepContentResult;
+    /**
+     * Format list_directory tool result summary
+     *
+     * @param result - Tool result data
+     * @returns Formatted summary string or empty
+     */
+    private formatListDirectoryResult;
     /**
      * Format tool call for concise display in interactive mode
      *

package/dist/commands/cipher-agent/run.js

@@ -7,6 +7,7 @@ import { displayInfo, startInteractiveLoop } from '../../infra/cipher/interactiv
 import { WorkspaceNotInitializedError } from '../../infra/cipher/validation/workspace-validator.js';
 import { ProjectConfigStore } from '../../infra/config/file-config-store.js';
 import { KeychainTokenStore } from '../../infra/storage/keychain-token-store.js';
+import { OclifTerminal } from '../../infra/terminal/oclif-terminal.js';
 import { formatToolCall, formatToolResult } from '../../utils/tool-display-formatter.js';
 export default class CipherAgentRun extends Command {
     static args = {
@@ -90,6 +91,7 @@ export default class CipherAgentRun extends Command {
         }),
     };
     static hidden = !isDevelopment();
+    terminal = {};
     // Override catch to prevent oclif from logging errors that were already displayed
     async catch(error) {
         // Check if error is ExitError (message already displayed by exitWithCode)
@@ -105,6 +107,7 @@ export default class CipherAgentRun extends Command {
         throw error;
     }
     createServices() {
+        this.terminal = new OclifTerminal(this);
         return {
             projectConfigStore: new ProjectConfigStore(),
         };
@@ -149,8 +152,11 @@ export default class CipherAgentRun extends Command {
     }
     // eslint-disable-next-line complexity
     async run() {
+        // Load services first to initialize terminal
+        const { projectConfigStore } = this.createServices();
         if (!isDevelopment()) {
-            this.error('This command is only available in development environment');
+            this.terminal.error('This command is only available in development environment');
+            return;
         }
         const { args, flags } = await this.parse(CipherAgentRun);
         try {
@@ -169,14 +175,13 @@ export default class CipherAgentRun extends Command {
                 : flags.interactive; // User explicitly set --interactive or --no-interactive
             // Validate prompt requirement for non-interactive mode
             if (!isInteractive && !currentPrompt) {
-                this.error('Prompt is required in non-interactive mode. Use --interactive flag for interactive mode.');
+                this.terminal.error('Prompt is required in non-interactive mode. Use --interactive flag for interactive mode.');
             }
             // Validate flags: In headless mode, prompt is required for session continuation
             if ((flags.continue || flags.resume) && !isInteractive && !args.prompt) {
-                this.error('Session continuation flags (-c/--continue or -r/--resume) require a prompt in headless mode.');
+                this.terminal.error('Session continuation flags (-c/--continue or -r/--resume) require a prompt in headless mode.');
             }
             // Load ByteRover config to get custom system prompt (if configured)
-            const { projectConfigStore } = this.createServices();
             const brvConfig = await projectConfigStore.read();
             // Validate workspace is initialized
             if (!brvConfig) {
@@ -186,7 +191,7 @@ export default class CipherAgentRun extends Command {
             const llmConfig = this.createLLMConfig({ ...token, spaceId: brvConfig?.spaceId ?? '', teamId: brvConfig?.teamId ?? '' }, flags);
             // Create CipherAgent with service factory pattern
             const agent = new CipherAgent(llmConfig, brvConfig);
-            this.log('Starting CipherAgent...');
+            this.terminal.log('Starting CipherAgent...');
             await agent.start();
             try {
                 // Resolve session ID based on flags
@@ -204,15 +209,15 @@ export default class CipherAgentRun extends Command {
                 else {
                     // Non-interactive mode: single execution
                     if (!currentPrompt) {
-                        this.error('Prompt is required in non-interactive mode.');
+                        this.terminal.error('Prompt is required in non-interactive mode.');
                     }
-                    this.log('Executing prompt...');
+                    this.terminal.log('Executing prompt...');
                     const response = await agent.execute(currentPrompt, resolvedSessionId);
-                    this.log('\nCipherAgent Response:');
-                    this.log(response);
+                    this.terminal.log('\nCipherAgent Response:');
+                    this.terminal.log(response);
                     // Show agent state
                     const state = agent.getState();
-                    this.log(`\n[Agent State: ${state.currentIteration} iterations]`);
+                    this.terminal.log(`\n[Agent State: ${state.currentIteration} iterations]`);
                 }
             }
             finally {
@@ -264,13 +269,13 @@ export default class CipherAgentRun extends Command {
      * @returns LLM configuration object
      */
     createLLMConfig(token, flags) {
-        // Default model: google/gemini-2.5-pro for OpenRouter, gemini-2.5-pro for gRPC
+        // Default model: google/gemini-2.5-pro for OpenRouter, gemini-2.5-pro for HTTP
         const model = flags.model ?? (flags.apiKey ? 'google/gemini-2.5-pro' : 'gemini-2.5-pro');
         const envConfig = getCurrentConfig();
         return {
             accessToken: token.accessToken,
+            apiBaseUrl: envConfig.llmApiBaseUrl,
             fileSystemConfig: flags.workingDirectory ? { workingDirectory: flags.workingDirectory } : undefined,
-            grpcEndpoint: envConfig.llmGrpcEndpoint,
             maxIterations: 10, // Hardcoded default
             maxTokens: flags.maxTokens ?? 8192, // Default: 8192
             model,
@@ -283,6 +288,84 @@ export default class CipherAgentRun extends Command {
             verbose: flags.verbose ?? false,
         };
     }
+    /**
+     * Format curate tool result summary
+     *
+     * @param result - Tool result data
+     * @returns Formatted summary string or empty
+     */
+    formatCurateResult(result) {
+        if (typeof result !== 'string') {
+            return '';
+        }
+        try {
+            const parsed = JSON.parse(result);
+            if (!parsed.summary) {
+                return '';
+            }
+            const { added = 0, deleted = 0, failed = 0, merged = 0, updated = 0 } = parsed.summary;
+            const parts = [];
+            if (added > 0)
+                parts.push(`${added} added`);
+            if (updated > 0)
+                parts.push(`${updated} updated`);
+            if (merged > 0)
+                parts.push(`${merged} merged`);
+            if (deleted > 0)
+                parts.push(`${deleted} deleted`);
+            if (failed > 0)
+                parts.push(`${failed} failed`);
+            return parts.length > 0 ? parts.join(', ') : 'No operations';
+        }
+        catch {
+            return '';
+        }
+    }
+    /**
+     * Format find_knowledge_topics tool result summary
+     *
+     * @param result - Tool result data
+     * @returns Formatted summary string or empty
+     */
+    formatFindKnowledgeTopicsResult(result) {
+        if (typeof result !== 'string') {
+            return '';
+        }
+        try {
+            const parsed = JSON.parse(result);
+            const count = Array.isArray(parsed) ? parsed.length : Object.keys(parsed).length;
+            return `${count} topics retrieved`;
+        }
+        catch {
+            return '';
+        }
+    }
+    /**
+     * Format grep_content tool result summary
+     *
+     * @param result - Tool result data
+     * @returns Formatted summary string or empty
+     */
+    formatGrepContentResult(result) {
+        if (typeof result !== 'string') {
+            return '';
+        }
+        const lines = result.split('\n').filter((line) => line.trim());
+        return `${lines.length} matches found`;
+    }
+    /**
+     * Format list_directory tool result summary
+     *
+     * @param result - Tool result data
+     * @returns Formatted summary string or empty
+     */
+    formatListDirectoryResult(result) {
+        if (typeof result !== 'string') {
+            return '';
+        }
+        const lines = result.split('\n').filter((line) => line.trim());
+        return `${lines.length} items`;
+    }
     /**
      * Format tool call for concise display in interactive mode
      *
@@ -301,6 +384,9 @@ export default class CipherAgentRun extends Command {
             case 'create_knowledge_topic': {
                 return 'Creating knowledge topic...';
             }
+            case 'curate': {
+                return 'Curating knowledge topics...';
+            }
             case 'find_knowledge_topics': {
                 return 'Querying knowledge base...';
             }
@@ -333,46 +419,22 @@ export default class CipherAgentRun extends Command {
      * @returns Formatted summary string or empty if no summary needed
      */
     formatToolResultSummary(toolName, result) {
-        try {
-            switch (toolName) {
-                case 'find_knowledge_topics': {
-                    // Parse result to count topics
-                    if (typeof result === 'string') {
-                        try {
-                            const parsed = JSON.parse(result);
-                            const count = Array.isArray(parsed) ? parsed.length : Object.keys(parsed).length;
-                            return `${count} topics retrieved`;
-                        }
-                        catch {
-                            return '';
-                        }
-                    }
-                    return '';
-                }
-                case 'grep_content': {
-                    // Parse result to count matches
-                    if (typeof result === 'string') {
-                        const lines = result.split('\n').filter((line) => line.trim());
-                        return `${lines.length} matches found`;
-                    }
-                    return '';
-                }
-                case 'list_directory': {
-                    // Parse result to count items
-                    if (typeof result === 'string') {
-                        const lines = result.split('\n').filter((line) => line.trim());
-                        return `${lines.length} items`;
-                    }
-                    return '';
-                }
-                default: {
-                    return '';
-                }
+        switch (toolName) {
+            case 'curate': {
+                return this.formatCurateResult(result);
+            }
+            case 'find_knowledge_topics': {
+                return this.formatFindKnowledgeTopicsResult(result);
+            }
+            case 'grep_content': {
+                return this.formatGrepContentResult(result);
+            }
+            case 'list_directory': {
+                return this.formatListDirectoryResult(result);
+            }
+            default: {
+                return '';
             }
-        }
-        catch {
-            // If parsing fails, just return empty
-            return '';
         }
     }
     /**
@@ -405,7 +467,7 @@ export default class CipherAgentRun extends Command {
                 exitWithCode(ExitCode.VALIDATION_ERROR, `Session '${flags.resume}' not found. Use 'brv cipher-agent sessions' to see available sessions.`);
             }
             const metadata = await agent.getSessionMetadata(flags.resume);
-            this.log(`📌 Resuming session: ${flags.resume} (${metadata?.messageCount ?? 0} messages)\n`);
+            this.terminal.log(`📌 Resuming session: ${flags.resume} (${metadata?.messageCount ?? 0} messages)\n`);
             return flags.resume;
         }
         if (flags.continue) {
@@ -415,12 +477,12 @@ export default class CipherAgentRun extends Command {
                 exitWithCode(ExitCode.VALIDATION_ERROR, 'No previous sessions found. Start a new conversation without -c flag.');
             }
             const metadata = await agent.getSessionMetadata(mostRecentSessionId);
-            this.log(`📌 Continuing most recent session: ${mostRecentSessionId} (${metadata?.messageCount ?? 0} messages)\n`);
+            this.terminal.log(`📌 Continuing most recent session: ${mostRecentSessionId} (${metadata?.messageCount ?? 0} messages)\n`);
             return mostRecentSessionId;
         }
         // No continuation flags: generate new unique session ID
         const newSessionId = this.generateSessionId();
-        this.log(`🚀 Starting new session: ${newSessionId}\n`);
+        this.terminal.log(`🚀 Starting new session: ${newSessionId}\n`);
         return newSessionId;
     }
     /**
@@ -464,30 +526,30 @@ export default class CipherAgentRun extends Command {
         }
         // In non-interactive mode, show verbose event logs for debugging
         eventBus.on('llmservice:thinking', () => {
-            this.log('🤔 [Event] LLM is thinking...');
+            this.terminal.log('🤔 [Event] LLM is thinking...');
         });
         eventBus.on('llmservice:response', (payload) => {
-            this.log(`✅ [Event] LLM Response (${payload.provider}/${payload.model})`);
+            this.terminal.log(`✅ [Event] LLM Response (${payload.provider}/${payload.model})`);
         });
         eventBus.on('llmservice:toolCall', (payload) => {
             const formattedCall = formatToolCall(payload.toolName, payload.args);
-            this.log(`🔧 [Event] Tool Call: ${formattedCall}`);
+            this.terminal.log(`🔧 [Event] Tool Call: ${formattedCall}`);
         });
         eventBus.on('llmservice:toolResult', (payload) => {
             const resultSummary = formatToolResult(payload.toolName, payload.success, payload.result, payload.error);
             if (payload.success) {
-                this.log(`✓ [Event] Tool Success: ${payload.toolName} → ${resultSummary}`);
+                this.terminal.log(`✓ [Event] Tool Success: ${payload.toolName} → ${resultSummary}`);
             }
             else {
-                this.log(`✗ [Event] Tool Error: ${payload.toolName} → ${resultSummary}`);
+                this.terminal.log(`✗ [Event] Tool Error: ${payload.toolName} → ${resultSummary}`);
             }
         });
         eventBus.on('llmservice:error', (payload) => {
             const errorMessage = payload.error || 'Unknown error occurred';
-            this.log(`❌ [Event] LLM Error: ${errorMessage}`);
+            this.terminal.log(`❌ [Event] LLM Error: ${errorMessage}`);
         });
         eventBus.on('cipher:conversationReset', () => {
-            this.log('🔄 [Event] Conversation Reset');
+            this.terminal.log('🔄 [Event] Conversation Reset');
         });
     }
 }