|
|
@@ -0,0 +1,292 @@
|
|
|
+# Cline CLI Architecture
|
|
|
+
|
|
|
+The CLI is a **standalone terminal interface** for the Cline AI coding assistant, written in Go. It provides the same autonomous coding capabilities as the VS Code extension but runs entirely in the terminal.
|
|
|
+
|
|
|
+## High-Level Architecture
|
|
|
+
|
|
|
+```
|
|
|
+┌─────────────────────────────────────────────────────────────────────────┐
|
|
|
+│ User Terminal │
|
|
|
+└─────────────────────────────────────────────────────────────────────────┘
|
|
|
+ │
|
|
|
+ ▼
|
|
|
+┌─────────────────────────────────────────────────────────────────────────┐
|
|
|
+│ cline (Go binary) │
|
|
|
+│ cmd/cline/main.go │
|
|
|
+│ • Cobra CLI commands (task, auth, config, instance, etc.) │
|
|
|
+│ • Interactive input via Bubble Tea │
|
|
|
+│ • Streaming output with markdown rendering │
|
|
|
+└─────────────────────────────────────────────────────────────────────────┘
|
|
|
+ │ gRPC (50052) │ starts subprocess
|
|
|
+ ▼ ▼
|
|
|
+┌─────────────────────────┐ ┌─────────────────────────┐
|
|
|
+│ cline-core │◄────────────────►│ cline-host │
|
|
|
+│ (Node.js) │ gRPC (51052) │ (Go binary) │
|
|
|
+│ │ │ cmd/cline-host/main.go│
|
|
|
+│ • AI/LLM orchestration │ │ │
|
|
|
+│ • Tool execution │ │ • Workspace paths │
|
|
|
+│ • Task state mgmt │ │ • File diff editing │
|
|
|
+│ • Message handling │ │ • Clipboard access │
|
|
|
+└─────────────────────────┘ │ • Environment info │
|
|
|
+ │ └─────────────────────────┘
|
|
|
+ │ SQLite (self-registration)
|
|
|
+ ▼
|
|
|
+┌─────────────────────────────────────────────────────────────────────────┐
|
|
|
+│ ~/.cline/data/locks/locks.db │
|
|
|
+│ (Instance registry - core self-registers on startup) │
|
|
|
+└─────────────────────────────────────────────────────────────────────────┘
|
|
|
+```
|
|
|
+
|
|
|
+## Entry Points (`cmd/`)
|
|
|
+
|
|
|
+### `cmd/cline/main.go` - Main CLI
|
|
|
+
|
|
|
+Cobra-based CLI with commands:
|
|
|
+
|
|
|
+- **Root**: `cline [prompt]` - Start a task directly
|
|
|
+- **task**: Create, send, view, list, pause, restore tasks
|
|
|
+- **auth**: Authentication setup and provider configuration
|
|
|
+- **config**: Read/write settings
|
|
|
+- **instance**: Manage running Cline instances
|
|
|
+- **logs**: View and clean log files
|
|
|
+- **doctor**: System health check
|
|
|
+
|
|
|
+### `cmd/cline-host/main.go` - Host Bridge Service
|
|
|
+
|
|
|
+Separate gRPC server providing host environment operations to cline-core:
|
|
|
+
|
|
|
+- Workspace paths
|
|
|
+- File diff editing
|
|
|
+- Clipboard access
|
|
|
+- Shutdown coordination
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## `pkg/cli/` Subsystems
|
|
|
+
|
|
|
+### 1. `auth/` - Authentication System
|
|
|
+
|
|
|
+Handles authentication with Cline service and BYO (Bring Your Own) API providers.
|
|
|
+
|
|
|
+| File | Purpose |
|
|
|
+| ------------------------- | ------------------------------------------------------------------------ |
|
|
|
+| `auth_cline_provider.go` | OAuth login flow - opens browser, subscribes to auth callback stream |
|
|
|
+| `auth_menu.go` | Interactive menu showing auth options based on current state |
|
|
|
+| `auth_subscription.go` | gRPC stream subscription for auth status updates |
|
|
|
+| `wizard_byo.go` | Interactive wizard for configuring BYO providers |
|
|
|
+| `wizard_byo_bedrock.go` | AWS Bedrock-specific credential setup |
|
|
|
+| `wizard_byo_oca.go` | Oracle Code Assist setup |
|
|
|
+| `providers_list.go` | Retrieves configured providers from core state |
|
|
|
+| `providers_byo.go` | Provider selection UI and field configuration |
|
|
|
+| `models_*.go` | Model listing (static lists + dynamic fetch from OpenRouter/OpenAI/Ollama) |
|
|
|
+
|
|
|
+**Flow**: User runs `cline auth` → Menu shows options → For BYO: wizard guides through provider/key/model selection → Config saved via gRPC to core.
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### 2. `clerror/` - Error Handling
|
|
|
+
|
|
|
+Parses and classifies API errors from the Cline service.
|
|
|
+
|
|
|
+**Error Types:**
|
|
|
+
|
|
|
+- `ErrorTypeAuth` - 401, bad API key
|
|
|
+- `ErrorTypeBalance` - Insufficient credits
|
|
|
+- `ErrorTypeRateLimit` - 429, quota exceeded
|
|
|
+- `ErrorTypeNetwork` - Connection issues
|
|
|
+- `ErrorTypeUnknown` - Catch-all
|
|
|
+
|
|
|
+Extracts billing details (balance, spent, buy credits URL) from error responses.
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### 3. `config/` - Configuration Management
|
|
|
+
|
|
|
+| File | Purpose |
|
|
|
+| --------------------- | -------------------------------------------------------------------------- |
|
|
|
+| `manager.go` | gRPC interface for reading/writing settings via `UpdateSettingsCli` RPC |
|
|
|
+| `settings_renderer.go`| Pretty-prints config values, censors sensitive fields (keys, secrets) |
|
|
|
+
|
|
|
+Supports dot-notation paths: `cline config get auto-approval-settings.actions.read-files`
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### 4. `display/` - Terminal Display System
|
|
|
+
|
|
|
+The most complex subsystem - handles all visual output.
|
|
|
+
|
|
|
+| File | Purpose |
|
|
|
+| ----------------------- | -------------------------------------------------------------------- |
|
|
|
+| `renderer.go` | Central coordinator with lipgloss styles, color methods, markdown delegation |
|
|
|
+| `streaming.go` | Real-time streaming display with deduplication |
|
|
|
+| `segment_streamer.go` | Streaming segments (header + body) with context-aware headers |
|
|
|
+| `typewriter.go` | Character-by-character animation with variable delays |
|
|
|
+| `markdown_renderer.go` | Glamour wrapper for terminal markdown rendering |
|
|
|
+| `tool_renderer.go` | Tool operation formatting ("Cline is editing `file.ts`") |
|
|
|
+| `tool_result_parser.go` | Parses structured tool results (file lists, search results) |
|
|
|
+| `banner.go` | Session startup banner with version/model/workspace |
|
|
|
+| `deduplicator.go` | MD5-based deduplication with 2-second window |
|
|
|
+| `system_renderer.go` | Rich error/warning boxes for balance errors, auth failures |
|
|
|
+| `ansi.go` | TTY detection, line clearing with escape codes |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### 5. `global/` - Global State Management
|
|
|
+
|
|
|
+| File | Purpose |
|
|
|
+| ------------------ | -------------------------------------------------------------------------- |
|
|
|
+| `global.go` | Global config (paths, verbosity, output format), initialization |
|
|
|
+| `registry.go` | Instance discovery via SQLite, health checking, default instance management|
|
|
|
+| `cline-clients.go` | Starts cline-core + cline-host processes, port allocation, cleanup |
|
|
|
+
|
|
|
+**Instance lifecycle:**
|
|
|
+
|
|
|
+1. Find available port pair
|
|
|
+2. Start `cline-host` on port+1000
|
|
|
+3. Start `cline-core` on port
|
|
|
+4. Wait for core to self-register in SQLite
|
|
|
+5. Set as default if first instance
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### 6. `handlers/` - Message Handlers
|
|
|
+
|
|
|
+Routes incoming messages from cline-core to appropriate renderers.
|
|
|
+
|
|
|
+| File | Purpose |
|
|
|
+| ------------------ | --------------------------------------------------------------------- |
|
|
|
+| `handler.go` | Handler registry with priority-based routing |
|
|
|
+| `ask_handlers.go` | Approval requests: tool, command, followup, api_req_failed, etc. |
|
|
|
+| `say_handlers.go` | Status messages: text, reasoning, command_output, tool, checkpoint, etc. |
|
|
|
+
|
|
|
+Uses `DisplayContext` providing renderer access, state, and context flags (isLast, isPartial, isStreamingMode).
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### 7. `output/` - Output Coordination
|
|
|
+
|
|
|
+| File | Purpose |
|
|
|
+| --------------------- | ----------------------------------------------------------------------- |
|
|
|
+| `coordinator.go` | Coordinates streaming output with interactive input (saves/restores input state) |
|
|
|
+| `input_model.go` | Bubble Tea model for rich input (message, approval, feedback types) |
|
|
|
+| `slash_completion.go` | Autocomplete dropdown for slash commands |
|
|
|
+
|
|
|
+**Key pattern:** When output needs to print while input is visible, the coordinator saves input state, clears the form, prints, then restores input.
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### 8. `slash/` - Slash Command Registry
|
|
|
+
|
|
|
+Central registry for commands like `/plan`, `/act`, `/cancel`:
|
|
|
+
|
|
|
+- **CLI-local commands**: Handled directly by CLI
|
|
|
+- **Backend commands**: Fetched from core via gRPC, filtered by `CliCompatible` flag
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### 9. `sqlite/` - Instance Locking
|
|
|
+
|
|
|
+Manages the distributed locking system:
|
|
|
+
|
|
|
+- **Instance locks**: Track running Cline instances by address
|
|
|
+- **File locks**: Coordinate file access across instances
|
|
|
+- SQLite database created by cline-core, CLI reads/writes for discovery
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### 10. `task/` - Task Management
|
|
|
+
|
|
|
+| File | Purpose |
|
|
|
+| ----------------------- | -------------------------------------------------------------------- |
|
|
|
+| `manager.go` | Core orchestrator: create, cancel, resume, restore tasks; stream handling |
|
|
|
+| `stream_coordinator.go` | Deduplication and turn management for dual streams |
|
|
|
+| `input_handler.go` | Interactive input during follow mode (polling, approval detection) |
|
|
|
+| `history_handler.go` | Direct disk access to `taskHistory.json` |
|
|
|
+| `settings_parser.go` | Parse settings from CLI flags |
|
|
|
+| `follow_options.go` | Configuration for follow behavior |
|
|
|
+
|
|
|
+**Streaming:** Task manager subscribes to two gRPC streams:
|
|
|
+
|
|
|
+1. `SubscribeToState` - Full state updates
|
|
|
+2. `SubscribeToPartialMessage` - Streaming AI responses
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### 11. `terminal/` - Terminal Handling
|
|
|
+
|
|
|
+Enhanced keyboard protocol support and terminal configuration:
|
|
|
+
|
|
|
+- Enables modifyOtherKeys and Kitty keyboard protocol
|
|
|
+- Detects terminal type (VS Code, iTerm, Ghostty, Kitty, etc.)
|
|
|
+- Auto-configures shift+enter keybindings for various terminals
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### 12. `types/` - Type Definitions
|
|
|
+
|
|
|
+| File | Purpose |
|
|
|
+| -------------- | ----------------------------------------------------------------- |
|
|
|
+| `messages.go` | `ClineMessage`, `AskType`, `SayType`, `ToolType` enums, proto conversion |
|
|
|
+| `state.go` | `ConversationState` with thread-safe message access |
|
|
|
+| `history.go` | `HistoryItem` matching taskHistory.json format |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### 13. `updater/` - Auto-Update
|
|
|
+
|
|
|
+Background auto-update checking:
|
|
|
+
|
|
|
+- 24-hour check interval (cached)
|
|
|
+- Queries npm registry for newer versions
|
|
|
+- Supports `latest` and `nightly` channels
|
|
|
+- Runs `npm install -g cline` to update
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## `pkg/common/` - Shared Types
|
|
|
+
|
|
|
+| File | Purpose |
|
|
|
+| --------------- | ------------------------------------------------------------ |
|
|
|
+| `constants.go` | `SETTINGS_SUBFOLDER`, `DEFAULT_CLINE_CORE_PORT` |
|
|
|
+| `schema.go` | SQL queries for instance/file locks |
|
|
|
+| `types.go` | `CoreInstanceInfo`, `LockRow`, `DefaultCoreInstance` |
|
|
|
+| `utils.go` | Port checking, health checks, address normalization, retry logic |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## `pkg/generated/` - Auto-Generated
|
|
|
+
|
|
|
+| File | Purpose |
|
|
|
+| --------------------- | -------------------------------------------------------------------------------------------------------------------- |
|
|
|
+| `providers.go` | Provider definitions (Anthropic, OpenAI, Bedrock, etc.) with field metadata and model specs - generated from TypeScript sources |
|
|
|
+| `field_overrides.go` | Manual overrides for field filtering |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## `pkg/hostbridge/` - CLI-to-Core Bridge
|
|
|
+
|
|
|
+This is the **reverse bridge** allowing cline-core to request host environment operations:
|
|
|
+
|
|
|
+| File | Purpose |
|
|
|
+| ----------------------- | ---------------------------------------------------- |
|
|
|
+| `grpc_server.go` | Main server registering all services |
|
|
|
+| `simple_workspace.go` | Workspace service: returns CWD as workspace path |
|
|
|
+| `diff.go` | In-memory file diff editing with line-based operations |
|
|
|
+| `env.go` | Clipboard access, version info, shutdown coordination |
|
|
|
+| `window.go` | UI stubs (no-ops or console output) |
|
|
|
+
|
|
|
+**Why this exists:** The same cline-core logic runs in VS Code and CLI. In VS Code, the "host" is the extension with editor APIs. In CLI, hostbridge emulates these capabilities with terminal-appropriate implementations.
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## Key Design Decisions
|
|
|
+
|
|
|
+1. **Two-process model:** `cline` CLI manages instances; `cline-core` is the actual AI engine (Node.js). This allows reusing the same core as the VS Code extension.
|
|
|
+
|
|
|
+2. **Self-registration via SQLite:** `cline-core` registers itself in a SQLite database on startup. The CLI discovers instances by reading this database, enabling multi-instance support.
|
|
|
+
|
|
|
+3. **Host bridge abstraction:** The `cline-host` process provides platform-specific operations (clipboard, workspace paths) via gRPC, allowing `cline-core` to remain host-agnostic.
|
|
|
+
|
|
|
+4. **Streaming-first UI:** The CLI uses gRPC streaming to display AI responses in real-time with typewriter-style rendering.
|
|
|
+
|
|
|
+5. **Dual stream handling:** Task manager subscribes to both state updates and partial messages, using deduplication to prevent duplicate rendering.
|
Max