mirror of
https://github.com/cline/cline.git
synced 2026-09-19 02:05:44 +08:00
da5477f891
- this will help the community to onboard to the CLI quicker and me more open to contributing to it. Co-authored-by: Max Paulus 🥪 <max@cline.bot> Co-authored-by: Tony Loehr <turingxo@gmail.com>
293 lines
15 KiB
Markdown
293 lines
15 KiB
Markdown
# 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.
|