cline/cli/architecture.md

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.