Cli 2.0 docs (#9060)

* docs: restructure CLI reference to web-friendly format

Replace embedded man page format with structured markdown sections
for better readability. Simplify description, reorganize commands and
options into clear categories, and update Next Steps navigation cards.

* Add ACP editor integrations documentation (#9036)

* Add ACP editor integrations documentation with JetBrains and Neovim video demos

* Add Model Orchestration documentation with --config and --thinking flags

- Document --config and --thinking flags in CLI reference
- Create new model-orchestration.mdx sample page
- Add patterns for CI/CD review, task phase optimization, and multi-model consensus
- Link to production GitHub Actions workflow
- Update samples overview with new card
- Update docs navigation

* Add Worktree Workflows documentation with --cwd flag

- Document --cwd flag in CLI reference
- Create comprehensive worktree-workflows.mdx sample page
- Add patterns for parallel execution and cross-worktree piping
- Include real-world examples and best practices
- Add CLI section to features/worktrees.mdx for discoverability
- Update samples overview and navigation
- Cross-link between CLI and VS Code worktree docs

* Remove broken image references from worktrees documentation

- Remove worktrees-overview.png Frame (image not available)
- Remove worktrees-merge.png Frame (image not available)
- Documentation remains fully functional with comprehensive text explanations

* Remove accidentally committed local test file

- Delete src/test/verify-platformio-mcp.ts which was causing CI failures
- File contained TypeScript errors and hardcoded local paths
- Was meant for local testing only, should not have been committed

* Add native JetBrains plugin recommendation to ACP docs

- Add prominent Note recommending native JetBrains plugin
- Link directly to JetBrains installation section
- Position ACP setup as an alternative approach
- Keep all existing ACP content and video

* docs: refine CLI reference formatting and ACP title

Improve CLI reference readability with clearer headings and descriptions, and clarify the ACP editor integration page title for better discovery.docs: refine CLI reference formatting and ACP title

Improve CLI reference readability with clearer headings and descriptions, and clarify the ACP editor integration page title for better discovery.

* Fix CLI 2.0 syntax in model-orchestration.mdx

- Updated issue analysis pipeline to use shell variables for passing context
- Added explanatory note about why direct piping doesn't work
- Corrected example to complete each phase before starting the next
- All examples now use proper CLI 2.0 syntax

* Completely rewrite cli-reference.mdx with accurate CLI 2.0 information

- Removed all outdated CLI 1.0 content (instance management, Cline Core architecture, gRPC references)
- Added accurate CLI 2.0 commands: task, history, config, auth, update, version, dev
- Corrected all command flags and options based on actual man page
- Added proper examples for all commands
- Included environment variables documentation (CLINE_DIR, CLINE_COMMAND_PERMISSIONS)
- Added shell completion instructions
- Removed incorrect three-layer architecture description
- All content now matches cli/man/cline.1.md source of truth

Fixes outdated documentation issue mentioned in PR#9036

* Fix MDX syntax error in cli-reference.mdx

- Replace angle bracket URLs with proper markdown links
- MDX parser was interpreting <https://...> as invalid HTML tags
- Now uses [url](url) format which is proper MDX syntax

Fixes deployment validation error

---------

Co-authored-by: Renee Huang <[email protected]>

* docs: enhance interactive mode documentation with structured settings overview

* docs: restructure and improve CLI reference documentation

- Reorganize command structure with clearer global options section
- Add mode behavior table explaining interactive vs plain text modes
- Improve option descriptions with consistent formatting
- Add horizontal rules between sections for better readability
- Document timeout option and environment variables more clearly
- Add Tips & Tricks section for common usage patterns
- Update frontmatter description to reflect content changes

* docs: improve ACP editor integrations page with editor descriptions

- Update page title to be more concise ("ACP: Editor Integrations")
- Remove redundant H1 header that duplicated the title
- Add introductory descriptions for JetBrains, Neovim, and Zed sections
- Rename "Zed Editor" section to just "Zed" for consistency

* docs: expand CLI reference with modes of operation and agent behavior

* Update docs/cline-cli/cli-reference-deprecated.mdx

Co-authored-by: Copilot <[email protected]>

---------

Co-authored-by: Tony Loehr <[email protected]>
Co-authored-by: Renee Huang <[email protected]>
Co-authored-by: Copilot <[email protected]>

docs/cline-cli/acp-editor-integrations.mdx

@@ -0,0 +1,216 @@
+---
+title: "ACP: Editor Integrations"
+description: "Use Cline in JetBrains, Neovim, Zed, and other editors via the Agent Client Protocol"
+---
+
+
+Cline CLI supports the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/), an open standard that enables AI coding agents to work across different editors and IDEs. This means you can use the full Cline agent—with all its capabilities including Skills, Hooks, and MCP integrations—in your preferred development environment.
+
+## Why ACP?
+
+- **Editor flexibility**: Use Cline in JetBrains, Neovim, Zed, or any ACP-compatible editor
+- **No feature compromises**: Full access to Cline's capabilities regardless of editor
+- **Team consistency**: Same AI assistant across different developer workflows
+- **Open standard**: Built on Zed's open Agent Client Protocol specification
+
+## JetBrains IDEs
+
+[JetBrains](https://www.jetbrains.com) IDEs include IntelliJ IDEA, PyCharm, WebStorm, and more. They offer built-in AI Assistant with ACP support.
+
+<Note>
+**Recommended: Native JetBrains Plugin**
+
+For the best JetBrains experience, install the [native Cline plugin](/getting-started/installing-cline#jetbrains-ides) from the JetBrains Marketplace. It provides full IDE integration and the complete Cline experience.
+
+The ACP setup below is an alternative way to use Cline CLI features in JetBrains IDEs.
+</Note>
+
+Alternatively, you can run Cline CLI in IntelliJ IDEA, PyCharm, WebStorm, and all other JetBrains IDEs through their built-in AI Assistant with ACP support.
+
+<video
+  src="https://storage.googleapis.com/cline_public_images/cline-acp-jetbrains.mp4"
+  autoPlay
+  loop
+  muted
+  playsInline
+  style={{ width: "100%", borderRadius: "8px", marginTop: "16px", marginBottom: "16px" }}
+/>
+
+### Setup
+
+1. **Install Cline CLI** (if not already installed):
+   ```bash
+   npm i -g cline
+   ```
+
+2. **Authenticate with Cline**:
+   ```bash
+   cline auth
+   ```
+
+3. **Configure JetBrains AI Assistant**:
+   - Open your JetBrains IDE
+   - Navigate to `Settings | Tools | AI Assistant | Agents`
+   - Click "Add Custom Agent"
+   - This opens/creates `~/.jetbrains/acp.json`
+
+4. **Add Cline to `acp.json`**:
+   ```json
+   {
+     "agent_servers": {
+       "Cline": {
+         "command": "cline",
+         "args": ["--acp"],
+         "env": {}
+       }
+     }
+   }
+   ```
+
+5. **Use Cline**:
+   - Open the AI Chat tool window
+   - Select "Cline" from the agent dropdown
+   - Start coding with Cline in your JetBrains IDE!
+
+<Tip>
+JetBrains AI Assistant can expose its built-in MCP server to Cline, giving Cline access to IDE-specific tools and context.
+</Tip>
+
+## Neovim
+
+[Neovim](https://neovim.io) is a hyperextensible Vim-based text editor loved by developers for its speed and flexibility. Use Cline in Neovim through the [agentic.nvim](https://github.com/carlos-algms/agentic.nvim) or [avante.nvim](https://github.com/yetone/avante.nvim) plugins, which provide ACP integration.
+
+<video
+  src="https://storage.googleapis.com/cline_public_images/cline-acp-neovim-avante.mp4"
+  autoPlay
+  loop
+  muted
+  playsInline
+  style={{ width: "100%", borderRadius: "8px", marginTop: "16px", marginBottom: "16px" }}
+/>
+
+### Setup with agentic.nvim
+
+1. **Install Cline CLI** (if not already installed):
+   ```bash
+   npm i -g cline
+   ```
+
+2. **Authenticate with Cline**:
+   ```bash
+   cline auth
+   ```
+
+3. **Install agentic.nvim** using lazy.nvim:
+   ```lua
+   {
+     "carlos-algms/agentic.nvim",
+     opts = {
+       provider = "cline-acp",
+       acp_providers = {
+         ["cline-acp"] = {
+           command = "cline",
+           args = {"--acp"},
+         },
+       },
+     },
+     keys = {
+       {"<C-\\>", function() require("agentic").toggle() end, mode={"n","v","i"}, desc="Toggle Cline Chat"},
+     },
+   }
+   ```
+
+4. **Use Cline**:
+   - Press `<C-\>` to toggle Cline chat
+   - Start coding with Cline in Neovim!
+
+### Setup with avante.nvim
+
+Follow the [avante.nvim documentation](https://github.com/yetone/avante.nvim) for configuring external ACP agents and point it to `cline --acp`.
+
+## Zed
+
+[Zed](https://zed.dev) is a high-performance, multiplayer code editor built from the ground up for speed and collaboration. Zed's team created the Agent Client Protocol, making Cline a natural fit for this editor.
+
+### Setup
+
+1. **Install Cline CLI** (if not already installed):
+   ```bash
+   npm i -g cline
+   ```
+
+2. **Authenticate with Cline**:
+   ```bash
+   cline auth
+   ```
+
+3. **Configure Zed**:
+   - Open Zed settings (`Cmd/Ctrl + ,`)
+   - Add Cline to your `settings.json`:
+   ```json
+   {
+     "agent_servers": {
+       "Cline": {
+         "type": "custom",
+         "command": "cline",
+         "args": ["--acp"],
+         "env": {}
+       }
+     }
+   }
+   ```
+
+4. **Use Cline**:
+   - Open the AI assistant panel
+   - Select "Cline" from the agent dropdown
+   - Start coding with Cline in Zed!
+
+## Other Editors
+
+Any editor that supports the Agent Client Protocol can run Cline. Check your editor's documentation for ACP configuration instructions, then point it to:
+
+```bash
+cline --acp
+```
+
+## Troubleshooting
+
+### Agent not appearing
+
+- Ensure Cline CLI is installed globally: `npm i -g cline`
+- Verify authentication: `cline auth`
+- Check that `cline --acp` runs without errors
+- Restart your editor after configuration changes
+
+### Permission errors
+
+If Cline can't access files or run commands:
+- Check that your editor's ACP integration passes the correct working directory
+- Verify file permissions in your project
+- Ensure Cline has approval settings configured correctly
+
+### Connection issues
+
+- Make sure no other Cline instance is using the same configuration directory
+- Check editor logs for ACP-related errors
+- Try running `cline --acp` manually to test the connection
+
+## Learn More
+
+<Columns cols={2}>
+  <Card title="CLI Overview" icon="terminal" href="/cline-cli/overview">
+    Learn about Cline CLI's core capabilities and use cases.
+  </Card>
+  
+  <Card title="Three Core Flows" icon="route" href="/cline-cli/three-core-flows">
+    Master interactive mode, headless automation, and multi-instance workflows.
+  </Card>
+  
+  <Card title="Skills" icon="graduation-cap" href="/features/skills">
+    Understand how Cline's Skills work across all editors via ACP.
+  </Card>
+  
+  <Card title="Hooks" icon="link" href="/features/hooks/index">
+    Learn how to enforce policies with Hooks in any editor.
+  </Card>
+</Columns>

docs/cline-cli/cli-reference-deprecated.mdx

@@ -0,0 +1,482 @@
+---
+title: "CLI Reference (Deprecated)"
+description: "Command reference for Cline CLI versions earlier than 2.0.0 (deprecated). For the latest commands and options, see the current Cline CLI reference."
+---
+
+Complete command reference for Cline CLI. Use this for detailed documentation on all commands, options, and configuration.
+
+For quick help in your terminal:
+
+```bash
+cline --help          # Show all commands
+cline task --help     # Show task-specific commands
+man cline            # View the full manual page
+```
+
+## Manual Page
+
+The complete manual page for the Cline CLI:
+
+```
+CLINE(1)                         User Commands                        CLINE(1)
+
+NAME
+       cline - orchestrate and interact with Cline AI coding agents
+
+SYNOPSIS
+       cline [prompt] [options]
+
+       cline command [subcommand] [options] [arguments]
+
+DESCRIPTION
+       Try: cat README.md | cline "Summarize this for me:"
+
+       cline is a command-line interface for orchestrating multiple Cline AI
+       coding agents.  Cline is an autonomous AI agent who can read, write,
+       and execute code across your projects.  He operates through a
+       client-server architecture where Cline Core runs as a standalone
+       service, and the CLI acts as a scriptable interface for managing tasks,
+       instances, and agent interactions.
+
+       The CLI is designed for both interactive use and automation, making it
+       ideal for CI/CD pipelines, parallel task execution, and terminal-based
+       workflows.  Multiple frontends (CLI, VSCode, JetBrains) can attach to
+       the same Cline Core instance, enabling seamless task handoff between
+       environments.
+
+MODES OF OPERATION
+       Instant Task Mode
+              The simplest invocation: cline "prompt here" immediately spawns
+              an instance, creates a task, and enters chat mode.  This is
+              equivalent to running cline instance new && cline task new &&
+              cline task chat in sequence.
+
+       Subcommand Mode
+              Advanced usage with explicit control: cline <command>
+              [subcommand] [options] provides fine-grained control over
+              instances, tasks, authentication, and configuration.
+
+AGENT BEHAVIOR
+       Cline operates in two primary modes:
+
+       ACT MODE
+              Cline actively uses tools to accomplish tasks.  He can read
+              files, write code, execute commands, use a headless browser, and
+              more.  This is the default mode for task execution.
+
+       PLAN MODE
+              Cline gathers information and creates a detailed plan before
+              implementation.  He explores the codebase, asks clarifying
+              questions, and presents a strategy for user approval before
+              switching to ACT MODE.
+
+INSTANT TASK OPTIONS
+       When using the instant task syntax cline "prompt" the following options
+       are available:
+
+       -o, --oneshot
+              Full autonomous mode.  Cline completes the task and stops
+              following after completion.  Example: cline -o "what's 6 + 8?"
+
+       -s, --setting setting value
+              Override a setting for this task
+
+       -y, --no-interactive, --yolo
+              Enable fully autonomous mode.  Disables all interactivity:
+
+              • ask_followup_question tool is disabled
+
+              • attempt_completion happens automatically
+
+              • execute_command runs in non-blocking mode with timeout
+
+              • PLAN MODE automatically switches to ACT MODE
+
+       -m, --mode mode
+              Starting mode.  Options: act (default), plan
+
+       -w, --workspace path
+              Additional workspace paths.  Can be specified multiple times to
+              include multiple directories.  The current working directory is
+              always included as the first workspace.  Example: cline -w
+              /path/to/other/project "refactor shared code"
+
+GLOBAL OPTIONS
+       These options apply to all subcommands:
+
+       -F, --output-format format
+              Output format.  Options: rich (default), json, plain
+
+       -h, --help
+              Display help information for the command.
+
+       -v, --verbose
+              Enable verbose output for debugging.
+
+COMMANDS
+   Authentication
+       cline auth [provider] [key]
+
+       cline a [provider] [key]
+              Configure authentication for AI model providers.  Launches an
+              interactive wizard if no arguments provided.  If provider is
+              specified without a key, prompts for the key or launches the
+              appropriate OAuth flow.
+
+   Instance Management
+       Cline Core instances are independent agent processes that can run in
+       the background.  Multiple instances can run simultaneously, enabling
+       parallel task execution.
+
+       cline instance
+
+       cline i
+              Display instance management help.
+
+       cline instance new [-d|--default]
+
+       cline i n [-d|--default]
+              Spawn a new Cline Core instance.  Use --default to set it as
+              the default instance for subsequent commands.
+
+       cline instance list
+
+       cline i l
+              List all running Cline Core instances with their addresses and
+              status.
+
+       cline instance default address
+
+       cline i d address
+              Set the default instance to avoid specifying --address in task
+              commands.
+
+       cline instance kill address [-a|--all]
+
+       cline i k address [-a|--all]
+              Terminate a Cline Core instance.  Use --all to kill all running
+              instances.
+
+   Task Management
+       Tasks represent individual work items that Cline executes.  Tasks
+       maintain conversation history, checkpoints, and settings.
+
+       cline task [-a|--address ADDR]
+
+       cline t [-a|--address ADDR]
+              Display task management help.  The --address flag specifies
+              which Cline Core instance to use (e.g., localhost:50052).
+
+       cline task new prompt [options]
+
+       cline t n prompt [options]
+              Create a new task in the default or specified instance.
+              Options:
+
+              -s, --setting setting value
+                     Set task-specific settings
+
+              -y, --no-interactive, --yolo
+                     Enable autonomous mode
+
+              -m, --mode mode
+                     Starting mode (act or plan)
+
+       cline task open task-id [options]
+
+       cline t o task-id [options]
+              Resume a previous task from history.  Accepts the same options
+              as task new.
+
+       cline task list
+
+       cline t l
+              List all tasks in history with their id and snippet
+
+       cline task chat
+
+       cline t c
+              Enter interactive chat mode for the current task.  Allows
+              back-and-forth conversation with Cline.
+
+       cline task send [message] [options]
+
+       cline t s [message] [options]
+              Send a message to Cline.  If no message is provided, reads from
+              stdin.  Options:
+
+              -a, --approve
+                     Approve Cline's proposed action
+
+              -d, --deny
+                     Deny Cline's proposed action
+
+              -f, --file FILE
+                     Attach a file to the message
+
+              -y, --no-interactive, --yolo
+                     Enable autonomous mode
+
+              -m, --mode mode
+                     Switch mode (act or plan)
+
+       cline task view [-f|--follow] [-c|--follow-complete]
+
+       cline t v [-f|--follow] [-c|--follow-complete]
+              Display the current conversation.  Use --follow to stream
+              updates in real-time, or --follow-complete to follow until task
+              completion.
+
+       cline task restore checkpoint
+
+       cline t r checkpoint
+              Restore the task to a previous checkpoint state.
+
+       cline task pause
+
+       cline t p
+              Pause task execution.
+
+   Configuration
+       Configuration can be set globally.  Override these global settings for
+       a task using the --setting flag
+
+       cline config
+
+       cline c
+
+       cline config set key value
+
+       cline c s key value
+              Set a configuration variable.
+
+       cline config get key
+
+       cline c g key
+              Read a configuration variable.
+
+       cline config list
+
+       cline c l
+              List all configuration variables and their values.
+
+   Context Window Configuration
+       For local model providers, you can configure the context window size:
+
+       Ollama
+              cline config s ollama-api-options-ctx-num=32768
+
+       LM Studio
+              cline config s lm-studio-max-tokens=32768
+
+       For other providers (Anthropic, OpenRouter, etc.), the context window
+       is defined per model in the model metadata and is not user-settable.
+       Cline uses each model's built-in context limits automatically.
+
+TASK SETTINGS
+       Task settings are persisted in the ~/.cline/x/tasks directory.  When
+       resuming a task with cline task open, task settings are automatically
+       restored.
+
+       Common settings include:
+
+       yolo   Enable autonomous mode (true/false)
+
+       mode   Starting mode (act/plan)
+
+       hooks_enabled
+              Enable or disable hooks for the task (true/false)
+
+HOOKS INTEGRATION
+       Hooks let you inject custom logic into Cline's workflow at key moments.
+       They can validate operations before they execute, monitor tool usage,
+       and shape AI decisions. This allows you to integrate hooks into
+       automated workflows, CI/CD pipelines, and headless task execution.
+
+       Enable hooks for a task:
+
+              cline "prompt" -s hooks_enabled=true
+
+       Configure hooks globally:
+
+              cline config set hooks-enabled=true
+              cline config get hooks-enabled
+
+       Note: Hooks in the CLI are only supported on macOS and Linux.
+
+       For complete hooks documentation, see:
+       <https://docs.cline.bot/features/hooks/index>
+
+NOTES & EXAMPLES
+       The cline task send and cline task new commands support reading from
+       stdin, enabling powerful pipeline compositions:
+
+              cat requirements.txt | cline task send
+              echo "Refactor this code" | cline -y
+
+   Instance Management
+       Manage multiple Cline instances:
+
+              # Start a new instance and make it default
+              cline instance new --default
+
+              # List all running instances
+              cline instance list
+
+              # Kill a specific instance
+              cline instance kill localhost:50052
+
+              # Kill all CLI instances
+              cline instance kill --all-cli
+
+   Task History
+       Work with task history:
+
+              # List previous tasks
+              cline task list
+
+              # Resume a previous task
+              cline task open 1760501486669
+
+              # View conversation history
+              cline task view
+
+              # Start interactive chat with this task
+              cline task chat
+
+ARCHITECTURE
+       Cline operates on a three-layer architecture:
+
+       Presentation Layer
+              User interfaces (CLI, VSCode, JetBrains) that connect to Cline
+              Core via gRPC
+
+       Cline Core
+              The autonomous agent service handling task management, AI model
+              integration, state management, tool orchestration, and real-time
+              streaming updates
+
+       Host Provider Layer
+              Environment-specific integrations (VSCode APIs, JetBrains APIs,
+              shell APIs) that Cline Core uses to interact with the host
+              system
+
+BUGS
+       Report bugs at: <https://github.com/cline/cline/issues>
+
+       For real-time help, join the Discord community at:
+       <https://discord.gg/cline>
+
+SEE ALSO
+       Full documentation: <https://docs.cline.bot>
+
+AUTHORS
+       Cline is developed by the Cline Bot Inc. and the open source community.
+
+COPYRIGHT
+       Copyright © 2025 Cline Bot Inc. Licensed under the Apache License 2.0.
+```
+
+## JSON output (-F json)
+
+When you run a command with `-F json` (or `--output-format json`), Cline prints each client message as JSON.
+
+### ClineMessage schema
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `type` | `"ask" or "say"` | Yes | Top-level message category. |
+| `text` | `string` | Yes | Human-readable message content. |
+| `ts` | `number` | Yes | Unix epoch timestamp in milliseconds. |
+| `reasoning` | `string` | No | Omitted when empty. |
+| `say` | `string` | No | Omitted when empty. Present when `type` is `"say"`. |
+| `ask` | `string` | No | Omitted when empty. Present when `type` is `"ask"`. |
+| `partial` | `boolean` | No | Omitted when false. `true` for streaming updates. |
+| `images` | `string[]` | No | Omitted when empty. Image URIs when included with a message. |
+| `files` | `string[]` | No | Omitted when empty. File paths when attached to a message. |
+| `lastCheckpointHash` | `string` | No | Omitted when empty. Git checkpoint hash when available. |
+| `isCheckpointCheckedOut` | `boolean` | No | Omitted when false. `true` if Cline checked out a checkpoint. |
+| `isOperationOutsideWorkspace` | `boolean` | No | Omitted when false. `true` if an operation happened outside the workspace. |
+
+<Note>
+Most fields are optional and omitted when empty. If you parse this output, treat missing fields as “not present”, not as empty strings.
+</Note>
+
+### Example
+
+```json
+{
+  "type": "say",
+  "text": "Cline is about to run a command.",
+  "ts": 1760501486669,
+  "say": "command",
+  "partial": false
+}
+```
+
+### Shell Completion
+
+Generate autocompletion scripts for various shells:
+
+#### Bash
+
+```bash
+# Generate bash completion
+cline completion bash > /etc/bash_completion.d/cline
+
+# Or for user-level installation
+cline completion bash > ~/.local/share/bash-completion/completions/cline
+```
+
+#### Zsh
+
+```bash
+# Generate zsh completion
+cline completion zsh > "${fpath[1]}/_cline"
+
+# Or add to your .zshrc
+echo 'source <(cline completion zsh)' >> ~/.zshrc
+```
+
+#### Fish
+
+```bash
+# Generate fish completion
+cline completion fish > ~/.config/fish/completions/cline.fish
+```
+
+#### PowerShell
+
+```powershell
+# Generate PowerShell completion
+cline completion powershell > cline.ps1
+
+# Add to your PowerShell profile
+Add-Content $PROFILE "cline completion powershell | Out-String | Invoke-Expression"
+```
+
+### Version Command
+
+```bash
+# Show version information
+cline version
+```
+
+### Environment Variables
+
+#### CLINE_DIR
+
+Override the default Cline directory location:
+
+```bash
+# Override default Cline directory
+export CLINE_DIR=/custom/path
+
+# Default: ~/.cline
+```
+
+This directory is used for:
+- Instance registry database
+- Configuration files
+- Task history
+- Checkpoints

docs/cline-cli/cli-reference.mdx

@@ -1,482 +1,426 @@
 ---
 title: "CLI Reference"
-description: "Complete command reference for Cline CLI including configuration, instance management, and task commands"
+description: "Complete command reference for Cline CLI including all commands, flags, and configuration options"
 ---
 
-Complete command reference for Cline CLI. Use this for detailed documentation on all commands, options, and configuration.
+# CLI Reference
 
-For quick help in your terminal:
+This page documents all available commands, flags, and configuration options for Cline CLI. For quick help in your terminal, use:
 
 ```bash
 cline --help          # Show all commands
-cline task --help     # Show task-specific commands
-man cline            # View the full manual page
+cline task --help     # Show task command options
+cline auth --help     # Show auth command options
+man cline             # View the full manual page (if installed)
 ```
 
-## Manual Page
-
-The complete manual page for the Cline CLI:
+## Synopsis
 
+```bash
+cline [prompt] [options]
+cline <command> [options] [arguments]
 ```
-CLINE(1)                         User Commands                        CLINE(1)
-
-NAME
-       cline - orchestrate and interact with Cline AI coding agents
-
-SYNOPSIS
-       cline [prompt] [options]
-
-       cline command [subcommand] [options] [arguments]
-
-DESCRIPTION
-       Try: cat README.md | cline "Summarize this for me:"
-
-       cline is a command-line interface for orchestrating multiple Cline AI
-       coding agents.  Cline is an autonomous AI agent who can read, write,
-       and execute code across your projects.  He operates through a
-       client-server architecture where Cline Core runs as a standalone
-       service, and the CLI acts as a scriptable interface for managing tasks,
-       instances, and agent interactions.
-
-       The CLI is designed for both interactive use and automation, making it
-       ideal for CI/CD pipelines, parallel task execution, and terminal-based
-       workflows.  Multiple frontends (CLI, VSCode, JetBrains) can attach to
-       the same Cline Core instance, enabling seamless task handoff between
-       environments.
-
-MODES OF OPERATION
-       Instant Task Mode
-              The simplest invocation: cline "prompt here" immediately spawns
-              an instance, creates a task, and enters chat mode.  This is
-              equivalent to running cline instance new && cline task new &&
-              cline task chat in sequence.
-
-       Subcommand Mode
-              Advanced usage with explicit control: cline <command>
-              [subcommand] [options] provides fine-grained control over
-              instances, tasks, authentication, and configuration.
-
-AGENT BEHAVIOR
-       Cline operates in two primary modes:
-
-       ACT MODE
-              Cline actively uses tools to accomplish tasks.  He can read
-              files, write code, execute commands, use a headless browser, and
-              more.  This is the default mode for task execution.
-
-       PLAN MODE
-              Cline gathers information and creates a detailed plan before
-              implementation.  He explores the codebase, asks clarifying
-              questions, and presents a strategy for user approval before
-              switching to ACT MODE.
-
-INSTANT TASK OPTIONS
-       When using the instant task syntax cline "prompt" the following options
-       are available:
-
-       -o, --oneshot
-              Full autonomous mode.  Cline completes the task and stops
-              following after completion.  Example: cline -o "what's 6 + 8?"
-
-       -s, --setting setting value
-              Override a setting for this task
-
-       -y, --no-interactive, --yolo
-              Enable fully autonomous mode.  Disables all interactivity:
-
-              • ask_followup_question tool is disabled
-
-              • attempt_completion happens automatically
-
-              • execute_command runs in non-blocking mode with timeout
-
-              • PLAN MODE automatically switches to ACT MODE
-
-       -m, --mode mode
-              Starting mode.  Options: act (default), plan
-
-       -w, --workspace path
-              Additional workspace paths.  Can be specified multiple times to
-              include multiple directories.  The current working directory is
-              always included as the first workspace.  Example: cline -w
-              /path/to/other/project "refactor shared code"
 
-GLOBAL OPTIONS
-       These options apply to all subcommands:
+## Global Options
 
-       -F, --output-format format
-              Output format.  Options: rich (default), json, plain
+These options work with any command:
 
-       -h, --help
-              Display help information for the command.
+| Option | Description |
+|--------|-------------|
+| `--config <path>` | Use a custom configuration directory instead of `~/.cline/data/` |
+| `-c, --cwd <path>` | Set the working directory for the task |
+| `-v, --verbose` | Show detailed output including model reasoning |
+| `--help` | Show help for the command |
 
-       -v, --verbose
-              Enable verbose output for debugging.
+## Modes of Operation
 
-COMMANDS
-   Authentication
-       cline auth [provider] [key]
+Cline CLI automatically detects the best output mode based on how you invoke it:
 
-       cline a [provider] [key]
-              Configure authentication for AI model providers.  Launches an
-              interactive wizard if no arguments provided.  If provider is
-              specified without a key, prompts for the key or launches the
-              appropriate OAuth flow.
+| Mode | When Activated | Description |
+|------|----------------|-------------|
+| **Interactive** | `cline` with no args, TTY connected | Rich terminal UI with real-time streaming, keyboard shortcuts, and visual feedback. |
+| **Task** | `cline "prompt"` with TTY connected | Interactive UI starts immediately with your task. |
+| **Plain Text** | stdin piped, stdout redirected, or `--yolo`/`--json` flags | Clean text output without UI, suitable for scripting and CI/CD. |
 
-   Instance Management
-       Cline Core instances are independent agent processes that can run in
-       the background.  Multiple instances can run simultaneously, enabling
-       parallel task execution.
+## Agent Behavior
 
-       cline instance
+Cline operates in two primary modes that control how it approaches tasks:
 
-       cline i
-              Display instance management help.
+| Mode | Description |
+|------|-------------|
+| **Act Mode** (default) | Cline actively uses tools to accomplish tasks. It can read files, write code, execute commands, use a headless browser, and more. |
+| **Plan Mode** | Cline gathers information and creates a detailed plan before implementation. It explores the codebase, asks clarifying questions, and presents a strategy for your approval before switching to Act Mode. |
 
-       cline instance new [-d|--default]
+Use `-a, --act` or `-p, --plan` flags to explicitly set the mode.
 
-       cline i n [-d|--default]
-              Spawn a new Cline Core instance.  Use --default to set it as
-              the default instance for subsequent commands.
+## Commands
 
-       cline instance list
+### cline (default)
 
-       cline i l
-              List all running Cline Core instances with their addresses and
-              status.
+Run Cline without a subcommand to start a task or enter interactive mode.
 
-       cline instance default address
-
-       cline i d address
-              Set the default instance to avoid specifying --address in task
-              commands.
-
-       cline instance kill address [-a|--all]
-
-       cline i k address [-a|--all]
-              Terminate a Cline Core instance.  Use --all to kill all running
-              instances.
-
-   Task Management
-       Tasks represent individual work items that Cline executes.  Tasks
-       maintain conversation history, checkpoints, and settings.
-
-       cline task [-a|--address ADDR]
-
-       cline t [-a|--address ADDR]
-              Display task management help.  The --address flag specifies
-              which Cline Core instance to use (e.g., localhost:50052).
-
-       cline task new prompt [options]
-
-       cline t n prompt [options]
-              Create a new task in the default or specified instance.
-              Options:
-
-              -s, --setting setting value
-                     Set task-specific settings
-
-              -y, --no-interactive, --yolo
-                     Enable autonomous mode
+```bash
+# Interactive mode (no arguments)
+cline
 
-              -m, --mode mode
-                     Starting mode (act or plan)
+# Start a task directly
+cline "your prompt here"
+```
 
-       cline task open task-id [options]
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `-a, --act` | Start in Act mode (default). Cline executes actions directly. |
+| `-p, --plan` | Start in Plan mode. Cline analyzes and creates a strategy before acting. |
+| `-y, --yolo` | YOLO mode: auto-approve all actions, use plain text output, exit when complete. Ideal for CI/CD. |
+| `-m, --model <id>` | Use a specific model (e.g., `claude-sonnet-4-5-20250929`, `gpt-4o`). |
+| `-i, --images <paths...>` | Include image files with the prompt. |
+| `--thinking` | Enable extended thinking with a 1024 token budget. |
+| `--json` | Output messages as JSON (one object per line). Forces plain text mode. |
+| `--timeout <seconds>` | Maximum execution time before the task is stopped. |
+
+**Mode Behavior:**
+
+| Invocation | Output Mode | Why |
+|------------|-------------|-----|
+| `cline` | Interactive UI | No arguments, TTY connected |
+| `cline "prompt"` | Interactive UI | TTY connected |
+| `cline -y "prompt"` | Plain text | YOLO flag forces plain text |
+| `cline --json "prompt"` | JSON | JSON flag forces plain text |
+| `cat file \| cline "prompt"` | Plain text | stdin is piped |
+| `cline "prompt" > out.txt` | Plain text | stdout is redirected |
 
-       cline t o task-id [options]
-              Resume a previous task from history.  Accepts the same options
-              as task new.
+---
 
-       cline task list
+### cline task (alias: t)
 
-       cline t l
-              List all tasks in history with their id and snippet
+Run a task with a prompt. This is equivalent to `cline "prompt"`.
 
-       cline task chat
+```bash
+cline task "Create a REST API endpoint"
+cline t "Fix the bug in utils.js"
+```
 
-       cline t c
-              Enter interactive chat mode for the current task.  Allows
-              back-and-forth conversation with Cline.
+**Options:** Same as the default command above.
 
-       cline task send [message] [options]
+---
 
-       cline t s [message] [options]
-              Send a message to Cline.  If no message is provided, reads from
-              stdin.  Options:
+### cline auth
 
-              -a, --approve
-                     Approve Cline's proposed action
+Configure authentication with an AI provider.
 
-              -d, --deny
-                     Deny Cline's proposed action
+```bash
+# Interactive wizard
+cline auth
 
-              -f, --file FILE
-                     Attach a file to the message
+# Quick setup with flags
+cline auth -p anthropic -k sk-ant-api-xxxxx -m claude-sonnet-4-5-20250929
+```
 
-              -y, --no-interactive, --yolo
-                     Enable autonomous mode
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `-p, --provider <id>` | Provider ID. See [Supported Providers](#supported-providers) below. |
+| `-k, --apikey <key>` | API key for the provider. |
+| `-m, --modelid <id>` | Model ID to use (e.g., `claude-sonnet-4-5-20250929`, `gpt-4o`). |
+| `-b, --baseurl <url>` | Base URL for OpenAI-compatible providers. |
+
+**Supported Providers:**
+
+| Provider ID | Description |
+|-------------|-------------|
+| `anthropic` | Anthropic Claude (direct API) |
+| `openai-native` | OpenAI GPT models |
+| `openai-codex` | ChatGPT subscription via OAuth |
+| `openrouter` | OpenRouter (access multiple providers) |
+| `bedrock` | AWS Bedrock |
+| `gemini` | Google Gemini |
+| `xai` | X AI (Grok) |
+| `cerebras` | Cerebras (fast inference) |
+| `deepseek` | DeepSeek |
+| `ollama` | Ollama (local models) |
+| `lmstudio` | LM Studio (local models) |
+| `openai` | OpenAI-compatible API (custom base URL) |
 
-              -m, --mode mode
-                     Switch mode (act or plan)
+---
 
-       cline task view [-f|--follow] [-c|--follow-complete]
+### cline history (alias: h)
 
-       cline t v [-f|--follow] [-c|--follow-complete]
-              Display the current conversation.  Use --follow to stream
-              updates in real-time, or --follow-complete to follow until task
-              completion.
+Browse task history with pagination.
 
-       cline task restore checkpoint
+```bash
+# Show recent tasks (default: 10)
+cline history
 
-       cline t r checkpoint
-              Restore the task to a previous checkpoint state.
+# Show more tasks
+cline history -n 20
 
-       cline task pause
+# Paginate through history
+cline history -n 10 -p 2
+```
 
-       cline t p
-              Pause task execution.
+**Options:**
 
-   Configuration
-       Configuration can be set globally.  Override these global settings for
-       a task using the --setting flag
+| Option | Description |
+|--------|-------------|
+| `-n, --limit <number>` | Number of tasks to show (default: 10) |
+| `-p, --page <number>` | Page number, 1-based (default: 1) |
 
-       cline config
+---
 
-       cline c
+### cline config
 
-       cline config set key value
+View and manage configuration settings.
 
-       cline c s key value
-              Set a configuration variable.
+```bash
+cline config
+```
 
-       cline config get key
+Opens an interactive configuration view with tabs for:
+- **Settings** - Global and workspace-specific settings
+- **Rules** - `.clinerules` files and imported rules
+- **Workflows** - Available workflows (appear as slash commands)
+- **Hooks** - Configured hook scripts
+- **Skills** - Enabled skills
 
-       cline c g key
-              Read a configuration variable.
+---
 
-       cline config list
+### cline update
 
-       cline c l
-              List all configuration variables and their values.
+Check for updates and install the latest version.
 
-   Context Window Configuration
-       For local model providers, you can configure the context window size:
+```bash
+cline update
+```
 
-       Ollama
-              cline config s ollama-api-options-ctx-num=32768
+---
 
-       LM Studio
-              cline config s lm-studio-max-tokens=32768
+### cline version
 
-       For other providers (Anthropic, OpenRouter, etc.), the context window
-       is defined per model in the model metadata and is not user-settable.
-       Cline uses each model's built-in context limits automatically.
+Show the installed CLI version.
 
-TASK SETTINGS
-       Task settings are persisted in the ~/.cline/x/tasks directory.  When
-       resuming a task with cline task open, task settings are automatically
-       restored.
+```bash
+cline version
+```
 
-       Common settings include:
+---
 
-       yolo   Enable autonomous mode (true/false)
+### cline dev
 
-       mode   Starting mode (act/plan)
+Developer tools for debugging.
 
-       hooks_enabled
-              Enable or disable hooks for the task (true/false)
+```bash
+# Open the log file
+cline dev log
+```
 
-HOOKS INTEGRATION
-       Hooks let you inject custom logic into Cline's workflow at key moments.
-       They can validate operations before they execute, monitor tool usage,
-       and shape AI decisions. This allows you to integrate hooks into
-       automated workflows, CI/CD pipelines, and headless task execution.
+## Environment Variables
 
-       Enable hooks for a task:
+### CLINE_DIR
 
-              cline "prompt" -s hooks_enabled=true
+Override the default configuration directory:
 
-       Configure hooks globally:
+```bash
+export CLINE_DIR=/path/to/custom/config
+cline "your task"
+```
 
-              cline config set hooks-enabled=true
-              cline config get hooks-enabled
+When set, all Cline data (settings, secrets, task history) is stored in this directory instead of `~/.cline/data/`.
 
-       Note: Hooks in the CLI are only supported on macOS and Linux.
+**Use cases:**
+- Running isolated Cline instances with different settings
+- CI/CD environments with custom state directories
+- Testing configuration changes without affecting your main setup
 
-       For complete hooks documentation, see:
-       <https://docs.cline.bot/features/hooks/index>
+### CLINE_COMMAND_PERMISSIONS
 
-NOTES & EXAMPLES
-       The cline task send and cline task new commands support reading from
-       stdin, enabling powerful pipeline compositions:
+Restrict which shell commands Cline can execute:
 
-              cat requirements.txt | cline task send
-              echo "Refactor this code" | cline -y
+```bash
+export CLINE_COMMAND_PERMISSIONS='{"allow": ["npm *", "git *"], "deny": ["rm -rf *"]}'
+```
 
-   Instance Management
-       Manage multiple Cline instances:
+**Format:**
 
-              # Start a new instance and make it default
-              cline instance new --default
+```json
+{
+  "allow": ["pattern1", "pattern2"],
+  "deny": ["pattern3"],
+  "allowRedirects": true
+}
+```
 
-              # List all running instances
-              cline instance list
+| Field | Type | Description |
+|-------|------|-------------|
+| `allow` | `string[]` | Glob patterns for allowed commands. If set, **only** matching commands are permitted. |
+| `deny` | `string[]` | Glob patterns for denied commands. Deny rules **always take precedence** over allow rules. |
+| `allowRedirects` | `boolean` | Whether to allow shell redirects (`>`, `>>`, `<`). Default: `false`. |
 
-              # Kill a specific instance
-              cline instance kill localhost:50052
+**Examples:**
 
-              # Kill all CLI instances
-              cline instance kill --all-cli
+```bash
+# Allow only npm and git commands (deny everything else)
+export CLINE_COMMAND_PERMISSIONS='{"allow": ["npm *", "git *"]}'
 
-   Task History
-       Work with task history:
+# Allow dev commands but explicitly deny dangerous ones
+export CLINE_COMMAND_PERMISSIONS='{"allow": ["npm *", "git *", "node *"], "deny": ["rm -rf *", "sudo *"]}'
 
-              # List previous tasks
-              cline task list
+# Allow file reading with redirects
+export CLINE_COMMAND_PERMISSIONS='{"allow": ["cat *", "echo *"], "allowRedirects": true}'
+```
 
-              # Resume a previous task
-              cline task open 1760501486669
+**How commands are evaluated:**
 
-              # View conversation history
-              cline task view
+1. Check for dangerous characters (backticks outside single quotes, unquoted newlines)
+2. Parse command into segments split by operators (`&&`, `||`, `|`, `;`)
+3. If redirects are detected and `allowRedirects` is not true, command is denied
+4. Each segment is validated against deny rules first, then allow rules
+5. Subshell contents (`$(...)` and `(...)`) are recursively validated
+6. All segments must pass for the command to be allowed
 
-              # Start interactive chat with this task
-              cline task chat
+## JSON Output Format
 
-ARCHITECTURE
-       Cline operates on a three-layer architecture:
+When using `--json`, each message is output as a JSON object (one per line):
 
-       Presentation Layer
-              User interfaces (CLI, VSCode, JetBrains) that connect to Cline
-              Core via gRPC
+```json
+{
+  "type": "say",
+  "text": "I'll create the file now.",
+  "ts": 1760501486669,
+  "say": "text"
+}
+```
 
-       Cline Core
-              The autonomous agent service handling task management, AI model
-              integration, state management, tool orchestration, and real-time
-              streaming updates
+**Required fields:**
 
-       Host Provider Layer
-              Environment-specific integrations (VSCode APIs, JetBrains APIs,
-              shell APIs) that Cline Core uses to interact with the host
-              system
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `"ask"` \| `"say"` | Message category |
+| `text` | `string` | Human-readable message content |
+| `ts` | `number` | Unix timestamp in milliseconds |
 
-BUGS
-       Report bugs at: <https://github.com/cline/cline/issues>
+**Optional fields:**
 
-       For real-time help, join the Discord community at:
-       <https://discord.gg/cline>
+| Field | Type | Description |
+|-------|------|-------------|
+| `say` | `string` | Subtype when `type` is `"say"` (e.g., `"text"`, `"tool"`) |
+| `ask` | `string` | Subtype when `type` is `"ask"` (e.g., `"tool"`, `"followup"`) |
+| `reasoning` | `string` | Model reasoning (omitted when empty) |
+| `partial` | `boolean` | `true` while streaming (omitted when complete) |
+| `images` | `string[]` | Image URIs (omitted when empty) |
+| `files` | `string[]` | File paths (omitted when empty) |
 
-SEE ALSO
-       Full documentation: <https://docs.cline.bot>
+## Configuration Files
 
-AUTHORS
-       Cline is developed by the Cline Bot Inc. and the open source community.
+Cline stores all data in `~/.cline/` by default:
 
-COPYRIGHT
-       Copyright © 2025 Cline Bot Inc. Licensed under the Apache License 2.0.
+```
+~/.cline/
+├── data/                    # Configuration directory
+│   ├── globalState.json     # Global settings
+│   ├── secrets.json         # API keys (stored securely)
+│   ├── workspace/           # Workspace-specific state
+│   └── tasks/               # Task history and conversations
+└── log/                     # Debug logs (view with cline dev log)
 ```
 
-## JSON output (-F json)
-
-When you run a command with `-F json` (or `--output-format json`), Cline prints each client message as JSON.
-
-### ClineMessage schema
-
-| Field | Type | Required | Notes |
-|-------|------|----------|-------|
-| `type` | `"ask" or "say"` | Yes | Top-level message category. |
-| `text` | `string` | Yes | Human-readable message content. |
-| `ts` | `number` | Yes | Unix epoch timestamp in milliseconds. |
-| `reasoning` | `string` | No | Omitted when empty. |
-| `say` | `string` | No | Omitted when empty. Present when `type` is `"say"`. |
-| `ask` | `string` | No | Omitted when empty. Present when `type` is `"ask"`. |
-| `partial` | `boolean` | No | Omitted when false. `true` for streaming updates. |
-| `images` | `string[]` | No | Omitted when empty. Image URIs when included with a message. |
-| `files` | `string[]` | No | Omitted when empty. File paths when attached to a message. |
-| `lastCheckpointHash` | `string` | No | Omitted when empty. Git checkpoint hash when available. |
-| `isCheckpointCheckedOut` | `boolean` | No | Omitted when false. `true` if Cline checked out a checkpoint. |
-| `isOperationOutsideWorkspace` | `boolean` | No | Omitted when false. `true` if an operation happened outside the workspace. |
+## Examples
 
-<Note>
-Most fields are optional and omitted when empty. If you parse this output, treat missing fields as “not present”, not as empty strings.
-</Note>
+### Interactive Development
 
-### Example
+```bash
+# Start interactive mode
+cline
 
-```json
-{
-  "type": "say",
-  "text": "Cline is about to run a command.",
-  "ts": 1760501486669,
-  "say": "command",
-  "partial": false
-}
+# Start with a task and use interactive UI
+cline "Help me refactor this codebase"
 ```
 
-### Shell Completion
-
-Generate autocompletion scripts for various shells:
-
-#### Bash
+### Direct Task Execution
 
 ```bash
-# Generate bash completion
-cline completion bash > /etc/bash_completion.d/cline
+# Run a task directly
+cline "Add error handling to utils.js"
+
+# Start in Plan mode to review strategy first
+cline -p "Design a caching layer for the API"
 
-# Or for user-level installation
-cline completion bash > ~/.local/share/bash-completion/completions/cline
+# Use a specific model
+cline -m gpt-4o "Explain this code"
 ```
 
-#### Zsh
+### Piped Input
 
 ```bash
-# Generate zsh completion
-cline completion zsh > "${fpath[1]}/_cline"
+# Pipe file contents
+cat README.md | cline "Summarize this document"
+
+# Review git changes
+git diff | cline "Review these changes"
 
-# Or add to your .zshrc
-echo 'source <(cline completion zsh)' >> ~/.zshrc
+# Analyze test output
+npm test 2>&1 | cline "Fix any failing tests"
 ```
 
-#### Fish
+### Automation and CI/CD
 
 ```bash
-# Generate fish completion
-cline completion fish > ~/.config/fish/completions/cline.fish
-```
+# YOLO mode for automated workflows
+cline -y "Run tests and fix failures"
 
-#### PowerShell
+# JSON output for scripting
+cline --json "List all TODO comments" | jq '.text'
 
-```powershell
-# Generate PowerShell completion
-cline completion powershell > cline.ps1
+# With timeout
+cline -y --timeout 600 "Run the full test suite"
 
-# Add to your PowerShell profile
-Add-Content $PROFILE "cline completion powershell | Out-String | Invoke-Expression"
+# Chain commands
+git diff | cline -y "explain" | cline -y "write a commit message"
 ```
 
-### Version Command
+### Authentication
 
 ```bash
-# Show version information
-cline version
-```
+# Interactive wizard
+cline auth
 
-### Environment Variables
+# Quick setup: Anthropic
+cline auth -p anthropic -k sk-ant-api-xxxxx -m claude-sonnet-4-5-20250929
 
-#### CLINE_DIR
+# Quick setup: OpenAI
+cline auth -p openai-native -k sk-xxxxx -m gpt-4o
 
-Override the default Cline directory location:
-
-```bash
-# Override default Cline directory
-export CLINE_DIR=/custom/path
+# Quick setup: OpenRouter
+cline auth -p openrouter -k sk-or-xxxxx
 
-# Default: ~/.cline
+# OpenAI-compatible with custom URL
+cline auth -p openai -k your-key -b https://api.example.com/v1
 ```
 
-This directory is used for:
-- Instance registry database
-- Configuration files
-- Task history
-- Checkpoints
+## Support
+
+- **Report bugs:** https://github.com/cline/cline/issues
+- **Discord community:** https://discord.gg/cline
+- **Documentation:** https://docs.cline.bot
+
+## See Also
+
+<Columns cols={2}>
+  <Card title="Installation & Setup" icon="download" href="/cline-cli/installation">
+    Install Cline CLI and configure authentication.
+  </Card>
+  
+  <Card title="Interactive Mode" icon="terminal" href="/cline-cli/interactive-mode">
+    Keyboard shortcuts, slash commands, and file mentions.
+  </Card>
+  
+  <Card title="CLI Workflows" icon="route" href="/cline-cli/three-core-flows">
+    Interactive mode, direct execution, and automation patterns.
+  </Card>
+  
+  <Card title="Configuration" icon="gear" href="/cline-cli/configuration">
+    Environment variables and advanced settings.
+  </Card>
+</Columns>

docs/cline-cli/configuration.mdx

@@ -0,0 +1,278 @@
+---
+title: "Configuration"
+description: "Manage Cline CLI settings with cline config, environment variables, and configuration files"
+---
+
+Cline CLI provides multiple ways to configure settings, from the interactive `cline config` command to environment variables for automation.
+
+## The Config Command
+
+Launch the configuration interface:
+
+```bash
+cline config
+```
+
+This opens an interactive view with tabs for different configuration categories.
+
+## Configuration Tabs
+
+Navigate between tabs using arrow keys.
+
+### Settings Tab
+
+View and edit global and workspace-specific settings:
+
+- **Global State**: Settings that apply across all workspaces
+- **Workspace State**: Settings specific to the current directory
+
+### Rules Tab
+
+Manage Cline rules that guide AI behavior:
+
+- **`.clinerules` files**: Project-specific rules in your workspace
+- **Cursor rules**: Import rules from Cursor editor format
+- **Windsurf rules**: Import rules from Windsurf editor format
+
+Rules help Cline understand your project's conventions, coding standards, and preferences.
+
+### Workflows Tab
+
+View and manage [workflows](/features/slash-commands/workflows/index):
+
+- List available workflows
+- View workflow definitions
+- Workflows appear as slash commands in interactive mode
+
+### Hooks Tab
+
+Configure [hooks](/features/hooks/index) for custom logic integration:
+
+- Enable/disable hooks globally
+- View configured hook scripts
+- Hooks run at key points in Cline's workflow
+
+<Note>
+Hooks must be enabled via settings. Use `cline config` to toggle `hooks-enabled`.
+</Note>
+
+### Skills Tab
+
+Manage [skills](/features/skills) that extend Cline's capabilities:
+
+- View available skills
+- Enable/disable specific skills
+- Skills provide specialized instructions for specific tasks
+
+## Configuration Directory
+
+Cline stores configuration in `~/.cline/data/`:
+
+```
+~/.cline/
+├── data/                    # Configuration directory
+│   ├── globalState.json     # Global settings
+│   ├── secrets.json         # API keys (encrypted)
+│   ├── workspace/           # Workspace-specific state
+│   └── tasks/               # Task history and data
+└── log/                     # Log files
+```
+
+### Viewing Logs
+
+For debugging, view the log file:
+
+```bash
+cline dev log
+```
+
+This opens the log file in your default editor.
+
+## Environment Variables
+
+### CLINE_DIR
+
+Override the default configuration directory:
+
+```bash
+export CLINE_DIR=/custom/path/to/cline
+cline "your task"
+```
+
+When set, all Cline data is stored in this directory instead of `~/.cline/data/`.
+
+**Use cases:**
+- Running multiple isolated Cline configurations
+- Team-shared configurations
+- CI/CD with custom state directories
+
+### CLINE_COMMAND_PERMISSIONS
+
+Restrict which shell commands Cline can execute:
+
+```bash
+export CLINE_COMMAND_PERMISSIONS='{"allow": ["npm *", "git *"], "deny": ["rm -rf *"]}'
+```
+
+**Format:**
+
+```json
+{
+  "allow": ["pattern1", "pattern2"],
+  "deny": ["pattern3"],
+  "allowRedirects": true
+}
+```
+
+**Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `allow` | `string[]` | Glob patterns for allowed commands. If set, only matching commands are permitted. |
+| `deny` | `string[]` | Glob patterns for denied commands. Deny rules take precedence over allow. |
+| `allowRedirects` | `boolean` | Whether to allow shell redirects (`>`, `>>`, `<`). Default: `false` |
+
+**Examples:**
+
+```bash
+# Allow only npm and git commands
+export CLINE_COMMAND_PERMISSIONS='{"allow": ["npm *", "git *"]}'
+
+# Allow dev commands but deny dangerous ones
+export CLINE_COMMAND_PERMISSIONS='{"allow": ["npm *", "git *", "node *"], "deny": ["rm -rf *", "sudo *"]}'
+
+# Allow file operations with redirects
+export CLINE_COMMAND_PERMISSIONS='{"allow": ["cat *", "echo *"], "allowRedirects": true}'
+```
+
+<Warning>
+When `allow` is set, all commands not matching the allow patterns are denied. Use this for security-sensitive environments.
+</Warning>
+
+## Using --config Flag
+
+Run Cline with a custom configuration directory:
+
+```bash
+cline --config /path/to/custom/config "your task"
+```
+
+This is useful for:
+- Running isolated Cline instances
+- Testing different configurations
+- Separating work and personal setups
+
+**Example: Multiple configurations**
+
+```bash
+# Work configuration
+cline --config ~/.cline-work "review this PR"
+
+# Personal projects
+cline --config ~/.cline-personal "help me with this side project"
+```
+
+## Configuration for Local Providers
+
+### Ollama
+
+Configure context window size for Ollama:
+
+```bash
+# In settings or via config
+cline config
+# Navigate to Settings tab, find ollama-api-options-ctx-num
+```
+
+Or set via environment:
+
+```bash
+# Set context window to 32K tokens
+cline -m ollama/llama3 "your task"
+```
+
+### LM Studio
+
+Configure max tokens for LM Studio:
+
+```bash
+cline config
+# Navigate to Settings tab, find lm-studio-max-tokens
+```
+
+## Importing Configuration
+
+### From VS Code Extension
+
+If you use the Cline VS Code extension, the CLI automatically detects and can share some settings. However, the CLI maintains its own configuration for terminal-specific features.
+
+### From Other CLI Tools
+
+See [Installation & Setup](/cline-cli/installation#option-3-import-from-existing-tools) for importing configurations from:
+- Codex CLI
+- OpenCode
+
+## Configuration Best Practices
+
+### For Development
+
+Use the default configuration with workspace-specific rules:
+
+```bash
+# Add project-specific rules
+echo "Use TypeScript strict mode" > .clinerules/typescript.md
+```
+
+### For CI/CD
+
+Use environment variables and `--yolo` mode:
+
+```bash
+export CLINE_COMMAND_PERMISSIONS='{"allow": ["npm test", "npm run build"]}'
+cline -y "run tests and fix any failures"
+```
+
+### For Teams
+
+Share configuration via version control:
+
+```bash
+# Commit .clinerules/ to your repo
+git add .clinerules/
+git commit -m "Add Cline rules for team"
+```
+
+## Troubleshooting
+
+### Configuration Not Persisting
+
+1. Check write permissions on `~/.cline/data/`
+2. Ensure `CLINE_DIR` isn't set to a read-only location
+3. Verify the config directory exists
+
+### Environment Variables Not Working
+
+1. Ensure variables are exported: `export CLINE_DIR=/path`
+2. Check for typos in variable names
+3. Verify JSON syntax for `CLINE_COMMAND_PERMISSIONS`
+
+### Reset Configuration
+
+To start fresh, remove the configuration directory:
+
+```bash
+rm -rf ~/.cline/data/
+cline auth  # Re-authenticate
+```
+
+## Next Steps
+
+<Columns cols={2}>
+  <Card title="CLI Workflows" icon="route" href="/cline-cli/three-core-flows">
+    Learn about interactive mode, direct execution, and automation patterns.
+  </Card>
+  
+  <Card title="CLI Reference" icon="terminal" href="/cline-cli/cli-reference">
+    Complete command documentation with all flags and options.
+  </Card>
+</Columns>

docs/cline-cli/installation.mdx

@@ -1,50 +1,274 @@
 ---
-title: "Installation"
-description: "Install Cline CLI and authenticate with your account"
+title: "Installation & Setup"
+description: "Install Cline CLI on macOS, Linux, or Windows and configure your AI provider"
 ---
 
+Cline CLI brings the full power of Cline to your terminal. In just a few minutes, you can install the CLI, authenticate with your preferred AI provider, and start running tasks from any directory on your machine.
+
 ## Prerequisites
 
-Cline CLI requires Node.js version 20 or higher. We recommend using Node.js 22 for the best experience.
+Cline CLI requires **Node.js version 20 or higher**. We recommend Node.js 22 for the best experience.
 
-To check your Node.js version:
+Check your Node.js version:
 
 ```bash
 node --version
 ```
 
-## Installation
+If you need to install or update Node.js, visit [nodejs.org](https://nodejs.org) or use a version manager like [nvm](https://github.com/nvm-sh/nvm).
+
+## Install Cline CLI
+
+Install globally via npm:
 
 ```bash
 npm install -g cline
 ```
 
-After installation, authenticate with your Cline account:
+Verify the installation:
+
+```bash
+cline version
+```
+
+<Tip>
+To install a specific version, use `npm install -g [email protected]`. Check [npm](https://www.npmjs.com/package/cline) for available versions.
+</Tip>
+
+## Authenticate
+
+After installation, run the authentication wizard:
 
 ```bash
 cline auth
 ```
 
-This starts an authentication wizard to sign you in and configure your preferred AI model provider.
+This launches an interactive wizard with multiple options. Choose the method that works best for your workflow.
+
+### Option 1: Sign in with Cline (Recommended)
+
+Select **"Sign in with Cline"** to authenticate with your Cline account via OAuth. Your browser opens automatically to complete sign-in.
+
+### Option 2: Sign in with ChatGPT Subscription
+
+If you have a ChatGPT Plus or Pro subscription, select **"Sign in with ChatGPT Subscription"**. This uses OpenAI's Codex OAuth to authenticate with your existing subscription.
+
+### Option 3: Import from Existing Tools
+
+Already using another AI coding CLI? Cline can import your existing configuration:
+
+- **Import from Codex CLI** - Imports credentials from `~/.codex/auth.json`
+- **Import from OpenCode** - Imports configuration from `~/.local/share/opencode/auth.json`
+
+### Option 4: Bring Your Own API Key
+
+Select **"Bring your own API key"** to manually configure any supported provider. Or skip the wizard entirely with flags:
+
+```bash
+# Anthropic (Claude)
+cline auth -p anthropic -k sk-ant-api-xxxxx -m claude-sonnet-4-5-20250929
+
+# OpenAI
+cline auth -p openai-native -k sk-xxxxx -m gpt-4o
+
+# OpenRouter
+cline auth -p openrouter -k sk-or-xxxxx -m anthropic/claude-sonnet-4-5-20250929
+
+# OpenAI-compatible provider with custom base URL
+cline auth -p openai -k your-api-key -b https://api.example.com/v1
+```
+
+**Quick Setup Flags:**
+
+| Flag | Description |
+|------|-------------|
+| `-p, --provider <id>` | Provider ID (e.g., `anthropic`, `openai-native`, `openrouter`) |
+| `-k, --apikey <key>` | Your API key |
+| `-m, --modelid <id>` | Model ID (e.g., `claude-sonnet-4-5-20250929`, `gpt-4o`) |
+| `-b, --baseurl <url>` | Base URL for OpenAI-compatible providers |
+
+<Tip>
+Flags are especially useful for scripting, CI/CD environments, or setting up multiple machines.
+</Tip>
+
+### Supported Providers
+
+| Provider | Provider ID | Notes |
+|----------|-------------|-------|
+| Anthropic | `anthropic` | Direct Claude API access |
+| OpenAI | `openai-native` | GPT-4o, GPT-4, etc. |
+| OpenAI Codex | `openai-codex` | ChatGPT subscription OAuth |
+| OpenRouter | `openrouter` | Access multiple providers |
+| AWS Bedrock | `bedrock` | Claude via AWS |
+| Google Gemini | `gemini` | Gemini Pro, etc. |
+| X AI (Grok) | `xai` | Grok models |
+| Cerebras | `cerebras` | Fast inference |
+| DeepSeek | `deepseek` | DeepSeek models |
+| Ollama | `ollama` | Local models |
+| LM Studio | `lmstudio` | Local models |
+| OpenAI Compatible | `openai` | Any OpenAI-compatible API |
+
+## Verify Your Setup
+
+Confirm everything is working with a simple test:
+
+```bash
+cline "What is 2 + 2?"
+```
+
+If Cline responds with an answer, your installation and authentication are complete.
+
+Check your current configuration:
+
+```bash
+cline config
+```
 
 ## Quick Start
 
-Get started with Cline in seconds:
+Now you're ready to use Cline. Choose how you want to work:
+
+### Interactive Mode
+
+Launch the interactive CLI for development:
 
 ```bash
 cline
 ```
 
-That's it! Running `cline` in any directory starts an interactive session where you can chat with the AI agent. Type your task, review the plan, and type `/act` when ready to execute.
+You'll see the Cline welcome screen. Type your task and press Enter. Use:
+- `Tab` to toggle between Plan and Act modes
+- `Shift+Tab` to enable auto-approve
+- `/help` for available commands
+
+[Learn more about interactive mode →](/cline-cli/interactive-mode)
+
+### Direct Task Execution
 
-For even faster execution without interaction:
+Run a task directly from your shell:
 
 ```bash
-cline "Add unit tests to utils.js"
+cline "Add error handling to utils.js"
 ```
 
-This runs Cline with a single command, perfect for quick tasks or automation.
+For non-interactive execution (perfect for scripts and CI/CD):
 
-<Tip>
-New to Cline CLI? Start with interactive mode (`cline`) to see how it works. Once comfortable, explore [the three core flows](/cline-cli/three-core-flows) for advanced usage patterns.
-</Tip>
+```bash
+cline -y "Run tests and fix any failures"
+```
+
+[Learn more about CLI workflows →](/cline-cli/three-core-flows)
+
+## Switching Providers
+
+To change your configured provider at any time:
+
+```bash
+cline auth
+```
+
+You can also use the settings panel in interactive mode:
+
+```bash
+cline
+# Then type: /settings
+# Navigate to the API tab
+```
+
+## Updating
+
+Check for updates and install the latest version:
+
+```bash
+cline update
+```
+
+Or update manually via npm:
+
+```bash
+npm update -g cline
+```
+
+## Troubleshooting
+
+### Command Not Found
+
+If `cline` is not found after installation:
+
+1. Ensure npm global bin is in your PATH:
+   ```bash
+   npm bin -g
+   ```
+
+2. Add the path to your shell configuration (`.bashrc`, `.zshrc`, etc.):
+   ```bash
+   export PATH="$PATH:$(npm bin -g)"
+   ```
+
+3. Restart your terminal or source your shell config.
+
+### Permission Errors
+
+If you get permission errors during installation:
+
+```bash
+# Option 1: Use a Node version manager (recommended)
+# nvm, fnm, or volta handle permissions automatically
+
+# Option 2: Fix npm permissions
+# See: https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally
+```
+
+### OAuth Flow Issues
+
+If the browser doesn't open automatically during OAuth:
+1. Copy the URL from the terminal
+2. Paste it in your browser manually
+3. Complete the sign-in flow
+4. Return to the terminal
+
+### API Key Validation
+
+If your API key is rejected:
+1. Verify the key is correct and hasn't expired
+2. Check that you've selected the correct provider
+3. Ensure your API account has the necessary permissions
+
+**Provider-specific tips:**
+- **Anthropic**: Keys start with `sk-ant-`
+- **OpenAI**: Keys start with `sk-`
+- **AWS Bedrock**: Requires AWS credentials configured separately. See [AWS Bedrock documentation](/provider-config/aws-bedrock/api-key).
+
+## Uninstallation
+
+To remove Cline CLI:
+
+```bash
+npm uninstall -g cline
+```
+
+To also remove configuration data:
+
+```bash
+rm -rf ~/.cline
+```
+
+## Next Steps
+
+<Columns cols={2}>
+  <Card title="Interactive Mode" icon="terminal" href="/cline-cli/interactive-mode">
+    Master the interactive CLI with shortcuts and slash commands.
+  </Card>
+  
+  <Card title="CLI Workflows" icon="route" href="/cline-cli/three-core-flows">
+    Learn interactive mode, direct execution, and automation patterns.
+  </Card>
+  
+  <Card title="Configuration" icon="gear" href="/cline-cli/configuration">
+    Configure settings, rules, workflows, and environment variables.
+  </Card>
+  
+  <Card title="CLI Reference" icon="book" href="/cline-cli/cli-reference">
+    Complete command documentation with all flags and options.
+  </Card>
+</Columns>

docs/cline-cli/interactive-mode.mdx

@@ -0,0 +1,252 @@
+---
+title: "Interactive Mode"
+description: "Master the interactive CLI with keyboard shortcuts, slash commands, and file mentions"
+---
+
+Interactive mode is the primary way to work with Cline CLI when you want a collaborative, conversational experience. Unlike headless mode (which runs a single task and exits), interactive mode keeps a session open where you can have back-and-forth conversations with Cline, refine your requests, and guide the AI as it works.
+
+## Why Use Interactive Mode?
+
+Interactive mode is ideal when you:
+
+- **Don't know exactly what you need yet** - Explore a codebase, ask questions, and let Cline help you understand the architecture before making changes
+- **Want to review before acting** - Toggle Plan mode to see Cline's strategy, then switch to Act mode when you're ready
+- **Need iterative refinement** - Build on previous responses, ask follow-up questions, and guide Cline to the right solution
+- **Prefer human oversight** - Review each action, approve file changes, and maintain control over what Cline does
+- **Working on complex tasks** - Multi-step refactoring, debugging sessions, or feature development that requires judgment calls
+
+For automated workflows, scripts, or CI/CD pipelines, see [headless mode](/cline-cli/overview#headless-mode-non-interactive) instead.
+
+## Prerequisites
+
+Before using interactive mode, you need to have Cline CLI installed and authenticated. If you haven't done this yet, follow the [Installation & Setup guide](/cline-cli/installation) first.
+
+## Launching Interactive Mode
+
+Start interactive mode by running `cline` without any arguments:
+
+```bash
+cline
+```
+
+You'll see an animated welcome screen with the Cline robot. Start typing your task in the input field at the bottom of the screen.
+
+## Keyboard Shortcuts
+
+Keyboard shortcuts are the primary way to navigate and control the interactive CLI. Since there's no mouse interaction in the terminal, learning these shortcuts will help you work efficiently and switch between modes, manage input, and control your session without breaking your flow.
+
+### Mode Controls
+
+| Shortcut | Action |
+|----------|--------|
+| `Tab` | Toggle between Plan and Act mode |
+| `Shift+Tab` | Toggle auto-approve all actions |
+| `Esc` | Exit or cancel current operation |
+
+### Input Controls
+
+| Shortcut | Action |
+|----------|--------|
+| `Enter` | Submit your message |
+| `↑` / `↓` | Navigate message history |
+| `Home` / `End` | Move cursor to start/end of line |
+| `Ctrl+A` | Move cursor to beginning |
+| `Ctrl+E` | Move cursor to end |
+| `Ctrl+W` | Delete word before cursor |
+| `Ctrl+U` | Delete entire line |
+
+### Session Controls
+
+| Shortcut | Action |
+|----------|--------|
+| `Ctrl+C` | Exit with session summary |
+
+## File Mentions with @
+
+Reference files from your workspace by typing `@` followed by the filename:
+
+```
+@src/utils.ts can you add error handling to this file?
+```
+
+As you type after `@`, Cline shows a fuzzy search dropdown of matching files. Use arrow keys to navigate and `Enter` to select.
+
+<Tip>
+File search uses ripgrep for fast, fuzzy matching. You can type partial paths like `@utils` to find `src/utils/helpers.ts`.
+</Tip>
+
+### Multiple File Mentions
+
+Include multiple files in a single message:
+
+```
+Compare @src/old-api.ts with @src/new-api.ts and list the breaking changes
+```
+
+## Slash Commands
+
+Type `/` to see available commands. Slash commands provide quick access to settings, history, and workflows.
+
+### Built-in Commands
+
+| Command | Description |
+|---------|-------------|
+| `/settings` | Open the settings panel |
+| `/models` | Quick model switching |
+| `/history` | Browse and resume previous tasks |
+| `/clear` | Start a fresh task (clears current conversation) |
+| `/help` | Show help and available commands |
+| `/exit` | Exit the CLI |
+
+### Workflow Commands
+
+If you have [workflows](/features/slash-commands/workflows/index) configured, they appear as additional slash commands. For example, if you have a workflow named `code-review`, you can invoke it with:
+
+```
+/code-review
+```
+
+## Settings Panel
+
+Access the settings panel with `/settings`. Navigate between tabs using arrow keys.
+
+| Tab | Description | Settings |
+|-----|-------------|----------|
+| **API** | Configure your AI provider and model | Provider selection, model choice, extended thinking toggle, thinking budget |
+| **Auto-approve** | Control which actions Cline can perform without prompting | Read files, write files, execute commands, browser actions, MCP tools |
+| **Features** | Toggle Cline capabilities | Hooks, skills, auto-compact, sound notifications |
+| **Account** | Manage your Cline account | View account status, sign in/out, manage subscription |
+| **Other** | Additional preferences | Theme preferences, debug options |
+
+## Plan and Act Modes
+
+Cline operates in two modes, toggled with `Tab`. These modes work the same way in the CLI as they do in the VS Code extension. For a deeper explanation of how Plan and Act modes work, see the [Plan and Act documentation](/features/plan-and-act).
+
+### Plan Mode
+
+In Plan mode, Cline analyzes your request and creates a strategy before making changes. Use this when:
+- Exploring a new codebase
+- Working on complex refactoring
+- You want to review the approach first
+
+### Act Mode
+
+In Act mode, Cline executes tasks directly. Use this when:
+- You're confident in the task
+- Making straightforward changes
+- Running quick operations
+
+<Tip>
+Press `Tab` anytime to switch modes. Starting in Plan mode and switching to Act after reviewing is a common workflow.
+</Tip>
+
+## Auto-approve Toggle
+
+Press `Shift+Tab` to toggle auto-approve for all actions. This removes the approval prompts that appear before each action, letting Cline work continuously without interruption.
+
+### When to Enable Auto-approve
+
+Auto-approve is useful when:
+- **You trust the task** - Well-defined tasks where you're confident in the outcome
+- **Speed matters** - Long-running tasks where constant approvals slow you down
+- **You're watching anyway** - You can see Cline's work in real-time and can interrupt if needed
+- **Iterating quickly** - Rapid prototyping where you want to see results fast
+
+### What Gets Auto-approved
+
+When enabled, these actions happen without prompting:
+- File reads
+- File writes  
+- Command execution
+- Browser actions
+- MCP tool calls
+
+You can also configure granular auto-approve settings (e.g., auto-approve reads but not writes) via `/settings` → Auto-approve tab, or see the [Auto-approve documentation](/features/auto-approve) for more details.
+
+<Warning>
+Auto-approve gives Cline full autonomy. Use on a clean git branch so you can easily revert changes if needed. You can always press `Ctrl+C` to stop Cline immediately.
+</Warning>
+
+## Session Summary
+
+When you exit with `Ctrl+C`, Cline displays a session summary showing:
+- Tasks completed
+- Files modified
+- Commands executed
+- Token usage
+
+This helps you track what was accomplished during your session.
+
+## Running Multiple Instances
+
+By default, all CLI instances share the same settings and state. However, you may want to run isolated instances with separate configurations for scenarios like:
+
+- **Different models for different tasks** - Use a fast, cheap model for quick questions in one terminal and a more capable model for complex refactoring in another
+- **Separate work and personal projects** - Keep API keys, rules, and task history isolated between contexts
+- **Testing configuration changes** - Experiment with new settings without affecting your main setup
+- **Team vs. individual settings** - Use shared team configuration for work projects and personal preferences for side projects
+
+To run isolated instances, use the `--config` flag with different directories:
+
+```bash
+# Work instance with team configuration
+cline --config ~/.cline-work
+
+# Personal instance with different model/provider
+cline --config ~/.cline-personal
+
+# Experimental instance for testing new settings
+cline --config ~/.cline-test
+```
+
+Each config directory maintains its own provider settings, API keys, task history, and preferences.
+
+<Tip>
+Use terminal multiplexers like tmux or split terminals to run multiple Cline instances in parallel, each working on different parts of your project with different models or settings.
+</Tip>
+
+## Tips for Effective Usage
+
+### Start with Context
+
+Give Cline context about what you're working on:
+
+```
+I'm building a REST API with Express. The routes are in @src/routes/ and models in @src/models/. Help me add user authentication.
+```
+
+### Use Plan Mode for Exploration
+
+When you're unsure about the best approach:
+
+```
+[Tab to Plan mode]
+How should I structure the database schema for a multi-tenant SaaS app?
+```
+
+### Iterate with Follow-ups
+
+The interactive CLI maintains conversation context. Build on previous messages:
+
+```
+> Add a login endpoint
+[Cline creates the endpoint]
+
+> Now add rate limiting to it
+[Cline modifies the same endpoint]
+
+> Add tests for both features
+[Cline creates test files]
+```
+
+## Next Steps
+
+<Columns cols={2}>
+  <Card title="CLI Workflows" icon="route" href="/cline-cli/three-core-flows">
+    Learn about interactive mode, direct execution, and automation patterns.
+  </Card>
+  
+  <Card title="Configuration" icon="gear" href="/cline-cli/configuration">
+    Explore `cline config` and advanced configuration options.
+  </Card>
+</Columns>

docs/cline-cli/overview.mdx

@@ -1,84 +1,224 @@
 ---
 title: "Overview"
-description: "Install the CLI, run your first task, and learn to automate code reviews and integrate AI agents into your development workflow"
+description: "Run Cline AI coding agents directly in your terminal with an interactive CLI or automated workflows"
 ---
 
-<Warning>
-**Preview Release - macOS and Linux Only**
-
-Cline CLI is currently in preview and only available for macOS and Linux users. Windows support is coming soon.
-</Warning>
-
 ## What is Cline CLI?
 
-Cline CLI runs AI coding agents directly in your terminal. Pipe git diffs for automated code reviews in CI/CD, run multiple instances simultaneously for parallel development, or integrate Cline into your existing shell workflows.
+Cline CLI brings the full power of Cline to your terminal. Whether you prefer an interactive experience or automated workflows for CI/CD pipelines, the CLI adapts to your needs.
 
-The CLI tracks instances across your system and outputs in formats designed for both humans and scripts—JSON, plain text, or rich terminal output.
+The CLI supports macOS, Linux, and Windows, and works with all the same AI providers as the VS Code extension.
 
 <Tip>
 Ready to get started? Check out the [installation guide](/cline-cli/installation) to install Cline CLI and run your first task.
 </Tip>
 
+## Two Ways to Use Cline CLI
+
+The CLI operates in two distinct modes, automatically selecting the appropriate one based on how you invoke it:
+
+### Interactive Mode
+
+Interactive mode is designed for **hands-on development sessions** where you want to collaborate with Cline in real-time. It provides a rich terminal interface that feels like chatting with an AI assistant.
+
+**When it activates:** Running `cline` without arguments, or when stdin is a TTY (terminal).
+
+```bash
+cline
+```
+
+Key features:
+
+- **Real-time conversation** - Type messages, see Cline's responses, and iterate on tasks
+- **Visual feedback** - Animated welcome screen, syntax-highlighted code, and progress indicators
+- **File mentions** with `@` - Reference workspace files with fuzzy search autocomplete
+- **Slash commands** with `/` - Quick access to `/settings`, `/history`, `/models`, and workflows
+- **Keyboard shortcuts** - `Tab` to toggle Plan/Act, `Shift+Tab` for auto-approve all
+- **Session summaries** - See tasks completed, files modified, and token usage on exit
+- **Settings panel** - Configure providers, models, and features without leaving the CLI
+
+Interactive mode keeps you in control. You review Cline's plan, approve or modify actions, and guide the conversation.
+
+[Learn more about interactive mode →](/cline-cli/interactive-mode)
+
+### Headless Mode (Non-Interactive)
+
+Headless mode is designed for **automation, scripting, and CI/CD pipelines** where human interaction isn't possible or desired.
+
+**When it activates:** Using the `-y`/`--yolo` flag, `--json` flag, piping input/output, or when stdin is not a TTY.
+
+```bash
+# Headless with auto-approval (YOLO mode)
+cline -y "Run tests and fix any failures"
+
+# Headless with JSON output for parsing
+cline --json "List all TODO comments" | jq '.text'
+
+# Headless via piped input
+cat README.md | cline "Summarize this document"
+
+# Chain multiple headless commands
+git diff | cline -y "explain these changes" | cline -y "write a commit message"
+```
+
+Key features:
+
+- **No visual interface** - Clean text or JSON output suitable for scripting
+- **Automatic execution** - With `-y`, Cline approves all actions and runs autonomously
+- **Process control** - Exits automatically when the task completes
+- **Piped workflows** - Read from stdin, write to stdout, chain with other commands
+- **Machine-readable output** - Use `--json` to get structured output for parsing
+
+<Warning>
+Headless mode with `-y` gives Cline full autonomy. Run on a clean git branch so you can easily revert changes if needed.
+</Warning>
+
+### Mode Detection Summary
+
+Cline automatically detects which mode to use based on your invocation. This table shows how different command patterns trigger each mode, helping you predict behavior in scripts and interactive sessions.
+
+| Invocation | Mode | Reason |
+|------------|------|--------|
+| `cline` | Interactive | No arguments, TTY connected |
+| `cline "task"` | Interactive | TTY connected |
+| `cline -y "task"` | Headless | YOLO flag forces headless |
+| `cline --json "task"` | Headless | JSON flag forces headless |
+| `cat file \| cline "task"` | Headless | stdin is piped |
+| `cline "task" > output.txt` | Headless | stdout is redirected |
+
+[Learn more about CLI workflows →](/cline-cli/three-core-flows)
+
 ## Supported Model Providers
 
-Cline CLI supports multiple AI model providers, giving you flexibility in choosing the best model for your needs:
+Cline CLI supports all providers available in the VS Code extension:
 
-- **Anthropic**
-- **OpenAI**
-- **OpenAI Compatible**
+- **Anthropic** (Claude)
+- **OpenAI** (GPT-4o, GPT-4)
+- **OpenAI Codex** (ChatGPT subscription)
 - **OpenRouter**
-- **X AI (Grok)**
 - **AWS Bedrock**
 - **Google Gemini**
-- **Ollama**
+- **X AI (Grok)**
 - **Cerebras**
+- **DeepSeek**
+- **Ollama** (local models)
+- **LM Studio** (local models)
+- **OpenAI Compatible** (any compatible API)
 
-During installation, you'll authenticate and configure your preferred provider using the `cline auth` command.
+During setup, authenticate with `cline auth` to configure your preferred provider. [See setup guide →](/cline-cli/installation#authenticate)
 
-## What you can build with this
+## What You Can Build
 
-**Automated code maintenance**
-- Schedule daily runs to identify and fix linting issues across your codebase
-- Create tasks that scan for security vulnerabilities and automatically patch them
-- Build scripts that update deprecated dependencies and run tests
+### Automated Code Maintenance
 
-**Multi-instance development**
-- Run separate Cline instances for frontend and backend simultaneously
-- Spawn instances for different feature branches, each with isolated state
-- Create parallel review processes for multiple PRs
+Keep your codebase healthy with automated fixes. Cline scans for issues and applies corrections across multiple files.
 
-**Custom workflows**
-- Build shell scripts that combine Cline with git hooks for pre-commit analysis
-- Create custom commands that pipe complex data structures through Cline for processing
-- Integrate with your existing toolchain (jq, grep, awk) for sophisticated automation
+```bash
+cline -y "Fix all ESLint errors in src/"
+```
+Finds and fixes linting violations throughout your source directory.
 
-**CI/CD integration**
-- Add Cline to GitHub Actions for automatic code review on every PR
-- Create GitLab pipelines that generate migration scripts from schema changes
-- Build Jenkins jobs that use Cline to analyze test failures and suggest fixes
+```bash
+cline -y "Update all deprecated React lifecycle methods"
+```
+Migrates legacy code patterns to modern equivalents (e.g., `componentWillMount` → `useEffect`).
+
+```bash
+cline -y "Update dependencies with known vulnerabilities"
+```
+Identifies outdated packages with security issues and updates them to safe versions.
+
+### CI/CD Integration
+
+Integrate Cline into your continuous integration pipelines for automated code review and documentation.
+
+```bash
+git diff origin/main | cline -y "Review these changes for issues"
+```
+Pipes your PR diff to Cline for automated code review, catching bugs and style issues before merge.
+
+```bash
+git log --oneline v1.0..v1.1 | cline -y "Write release notes"
+```
+Generates human-readable release notes from your commit history between two tags.
+
+```bash
+cline -y "Run tests and fix failures" --timeout 600
+```
+Executes your test suite, analyzes failures, and attempts fixes with a 10-minute timeout.
+
+### Development Workflows
+
+From quick edits to complex refactors, Cline adapts to your workflow.
+
+```bash
+cline
+```
+Launches interactive mode for exploratory development and back-and-forth collaboration.
+
+```bash
+cline "Refactor this function to use async/await"
+```
+Executes a focused task directly from the command line with approval prompts at key steps.
+
+```bash
+cline "Based on @src/api.ts, add error handling to all endpoints"
+```
+Uses file mentions (`@`) to give Cline context about specific files in your workspace.
 
-## Hooks integration
+### Custom Shell Pipelines
 
-[Hooks](/features/hooks/index) let you inject custom logic into Cline's workflow to validate operations and enforce policies. You can enable hooks when running tasks from the command line:
+Chain Cline with other CLI tools to build powerful automation workflows.
 
 ```bash
-# Enable hooks for a task
-cline "What does this repo do?" -s hooks_enabled=true
+gh pr diff 123 | cline -y "Review this PR"
+```
+Fetches a GitHub PR diff and pipes it directly to Cline for review.
 
-# Configure hooks globally via CLI
-cline config set hooks-enabled=true
+```bash
+cline --json "List all TODO comments" | jq '.text'
 ```
+Outputs structured JSON that you can process with tools like `jq` for scripting.
 
-This allows you to integrate hooks into automated workflows, CI/CD pipelines, and headless task execution for consistent enforcement across all environments.
+```bash
+git diff | cline -y "explain" | cline -y "write a haiku about these changes"
+```
+Chains multiple Cline invocations together for creative multi-step workflows.
+
+## Features at a Glance
+
+| Feature | Interactive Mode | Non-Interactive Mode |
+|---------|------------------|----------------------|
+| Interactive chat | ✓ | - |
+| File mentions (@) | ✓ | ✓ (inline) |
+| Slash commands (/) | ✓ | - |
+| Settings panel | ✓ | `cline config` |
+| Plan/Act toggle | ✓ (Tab) | `-p` / `-a` flags |
+| Auto-approve | ✓ (Shift+Tab) | `-y` flag |
+| Session summary | ✓ | - |
+| JSON output | - | `--json` |
+| Piped input | - | ✓ |
 
-## Learn more
+## Learn More
 
 <Columns cols={2}>
-  <Card title="Installation" icon="download" href="/cline-cli/installation">
-    Install Cline CLI and authenticate with your account to get started.
+  <Card title="Installation & Setup" icon="download" href="/cline-cli/installation">
+    Install Cline CLI and authenticate with your preferred provider.
+  </Card>
+  
+  <Card title="Interactive Mode" icon="terminal" href="/cline-cli/interactive-mode">
+    Master the interactive CLI with keyboard shortcuts and slash commands.
+  </Card>
+  
+  <Card title="CLI Workflows" icon="route" href="/cline-cli/three-core-flows">
+    Learn interactive mode, direct execution, and automation patterns.
+  </Card>
+  
+  <Card title="Configuration" icon="gear" href="/cline-cli/configuration">
+    Configure settings, rules, workflows, and environment variables.
   </Card>
   
-  <Card title="Three Core Flows" icon="route" href="/cline-cli/three-core-flows">
-    Master the three ways to use Cline CLI: interactive mode, headless automation, and multi-instance parallelization.
+  <Card title="Use in Other Editors" icon="code" href="/cline-cli/acp-editor-integrations">
+    Run Cline as an ACP agent in JetBrains, Neovim, Zed, and more.
   </Card>
 </Columns>

docs/cline-cli/samples/github-integration.mdx

@@ -100,21 +100,14 @@ jobs:
           # Install the Cline CLI
           sudo npm install -g cline
 
-      - name: Create Cline Instance
+      - name: Configure Cline CLI
         if: steps.detect.outputs.hit == 'true'
         env:
           OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
           CLINE_DIR: ${{ runner.temp }}/cline
         run: |
-          # Create instance and capture output
-          INSTANCE_OUTPUT=$(cline instance new 2>&1)
-          
-          # Parse address from output (format: "  Address: 127.0.0.1:36733")
-          CLINE_ADDRESS=$(echo "$INSTANCE_OUTPUT" | grep "Address:" | grep -oE '([0-9]{1,3}\.){3}[0-9]{1,3}:[0-9]+')
-          echo "CLINE_ADDRESS=$CLINE_ADDRESS" >> $GITHUB_ENV
-          
           # Configure API key
-          cline config set open-router-api-key=$OPENROUTER_API_KEY --address $CLINE_ADDRESS -v
+          cline config set open-router-api-key=$OPENROUTER_API_KEY -v
 
       - name: Download analyze script
         if: steps.detect.outputs.hit == 'true'
@@ -135,7 +128,7 @@ jobs:
         run: |
           set -euo pipefail
           
-          RESULT=$(./analyze-issue.sh "${ISSUE_URL}" "Analyze this issue. The user asked: ${COMMENT}" "$CLINE_ADDRESS")
+          RESULT=$(./analyze-issue.sh "${ISSUE_URL}" "Analyze this issue. The user asked: ${COMMENT}")
           
           {
             echo 'result<<EOF'
@@ -180,8 +173,7 @@ This tells the workflow where to download the analysis script from your reposito
 </Warning>
 
 The workflow will look for new or updated issues, check for `@cline` mentions, and then
-start up an instance of the Cline CLI to dig into the issue, providing feedback
-as a reply to the issue.
+start up the Cline CLI to dig into the issue, providing feedback as a reply to the issue.
 
 ### 2. Configure API Keys
 
@@ -246,19 +238,16 @@ if [ -z "$1" ]; then
     echo "Usage: $0 <github-issue-url> [prompt] [address]"
     echo "Example: $0 https://github.com/owner/repo/issues/123"
     echo "Example: $0 https://github.com/owner/repo/issues/123 'What is the root cause of this issue?'"
-    echo "Example: $0 https://github.com/owner/repo/issues/123 'What is the root cause of this issue?' 127.0.0.1:46529"
+    echo "Example: $0 https://github.com/owner/repo/issues/123 'What is the root cause of this issue?'"
     exit 1
 fi
 
 # Gather the args
 ISSUE_URL="$1"
 PROMPT="${2:-What is the root cause of this issue?}"
-if [ -n "$3" ]; then
-    ADDRESS="--address $3"
-fi
 
 # Ask Cline for its analysis, showing only the summary
-cline -y "$PROMPT: $ISSUE_URL" --mode act $ADDRESS -F json | \
+cline -y "$PROMPT: $ISSUE_URL" --mode act -F json | \
     sed -n '/^{/,$p' | \
     jq -r 'select(.say == "completion_result") | .text' | \
     sed 's/\\n/\n/g'
@@ -311,12 +300,10 @@ The workflow (`cline-responder.yml`):
 1. **Triggers** on issue comments (created or edited)
 2. **Detects** `@cline` mentions (case-insensitive)
 3. **Installs** Cline CLI globally using npm
-4. **Creates** a Cline instance using `cline instance new`
-5. **Configures** authentication using `cline config set open-router-api-key=...
-   --address ...`
+4. **Configures** authentication using `cline config set open-router-api-key=...`
 6. **Downloads** the reusable `analyze-issue.sh` script from the
    `github-issue-rca` sample
-7. **Runs** analysis with the instance address
+7. **Runs** analysis in Cline CLI
 8. **Posts** the analysis result as a comment
 
 ## Related Samples

docs/cline-cli/samples/model-orchestration.mdx

@@ -0,0 +1,227 @@
+---
+title: "Model Orchestration"
+description: "Use multiple AI models strategically: optimize costs, reduce bias, and leverage model-specific strengths in your workflows"
+---
+
+# Model Orchestration
+
+Cline CLI's `--config` and `--thinking` flags enable sophisticated multi-model workflows. Instead of using a single model for all tasks, you can route different work to different models based on cost, capability, and specialization.
+
+## Why Orchestrate Multiple Models?
+
+**Cost Optimization**
+- Use fast, cheap models (Haiku, Gemini Flash) for simple tasks like summarization
+- Reserve expensive models (Opus, O1) for complex reasoning and planning
+- Reduce API costs by 10-100x on routine operations
+
+**Bias Reduction**
+- Different models catch different issues in code reviews
+- Cross-validate solutions with multiple AI perspectives
+- Reduce blind spots from single-model thinking
+
+**Specialization**
+- Some models excel at code (Codex, DeepSeek)
+- Others are better at documentation (GPT-4, Claude)
+- Security analysis benefits from multiple viewpoints
+
+## Pattern 1: CI/CD Code Review
+
+See our production GitHub Actions workflow that uses Cline CLI for automated PR reviews: [cline-pr-review.yml](https://github.com/cline/cline/blob/main/.github/workflows/cline-pr-review.yml)
+
+**Key capabilities demonstrated:**
+- **Automated inline suggestions**: Creates GitHub suggestion blocks that authors can commit with one click
+- **SME identification**: Analyzes git history to find subject matter experts for each file
+- **Related issue discovery**: Searches for context from past issues and PRs
+- **Security-first permissions**: Read-only codebase access, can only post reviews
+- **Deep code analysis**: Understands intent, compares approaches, identifies edge cases
+
+The workflow runs on every PR and provides maintainers with comprehensive context to make faster, more informed decisions.
+
+## Pattern 2: Task Phase Optimization
+
+Use different models for different phases of work. Route simple tasks to cheap models, complex reasoning to premium models.
+
+### Example: Issue Analysis Pipeline
+
+```bash
+# Get latest issue content
+ISSUE_CONTENT=$(gh issue view $(gh issue list -L 1 | awk '{print $1}'))
+
+# Phase 1: Quick summary with cheap model
+SUMMARY=$(echo "$ISSUE_CONTENT" | cline -y --config ~/.cline-haiku \
+  "summarize this issue in 2-3 sentences")
+
+# Phase 2: Detailed plan with expensive model + thinking
+PLAN=$(echo "$SUMMARY" | cline -y --thinking --config ~/.cline-opus \
+  "create detailed implementation plan with edge cases")
+
+# Phase 3: Execute with mid-tier model
+echo "$PLAN" | cline -y --config ~/.cline-sonnet \
+  "implement the plan from above"
+```
+
+<Note>
+Each cline invocation needs to complete before passing output to the next phase. Use shell variables to store intermediate results rather than piping cline commands directly.
+</Note>
+
+**Cost impact:**
+- Haiku: $0.80 per million input tokens
+- Opus: $15 per million input tokens  
+- Sonnet: $3 per million input tokens
+
+This pattern uses Opus only when needed for complex reasoning, saving ~10x on API costs compared to using Opus for everything.
+
+### Setting Up Model Configs
+
+Create separate configuration directories for each model:
+
+```bash
+# Create config directories
+mkdir -p ~/.cline-haiku ~/.cline-sonnet ~/.cline-opus
+
+# Configure each with different models
+cline --config ~/.cline-haiku auth anthropic --modelid claude-haiku-4-20250514
+cline --config ~/.cline-sonnet auth anthropic --modelid claude-sonnet-4-20250514  
+cline --config ~/.cline-opus auth anthropic --modelid claude-opus-4-5-20251101
+
+# Or use different providers entirely
+cline --config ~/.cline-gemini auth gemini --modelid gemini-2.0-flash-exp
+cline --config ~/.cline-codex auth openai-codex --modelid gpt-5-latest
+```
+
+Now you can switch models per-task with `--config`:
+
+```bash
+cline --config ~/.cline-haiku "quick task"
+cline --config ~/.cline-opus "complex reasoning task"
+```
+
+## Pattern 3: Multi-Model Review & Consensus
+
+Get multiple AI perspectives on the same change, then synthesize their feedback.
+
+### Example: Diff Review Pipeline
+
+```bash
+# Get the latest commit
+DIFF=$(git show)
+
+# Review 1: Gemini's perspective
+echo "$DIFF" | cline -y --config ~/.cline-gemini \
+    "review this diff and write your analysis to gemini-review.md"
+
+# Review 2: Codex's perspective
+echo "$DIFF" | cline -y --config ~/.cline-codex \
+    "review this diff and write your analysis to codex-review.md"
+
+# Review 3: Opus's perspective
+echo "$DIFF" | cline -y --config ~/.cline-opus \
+    "review this diff and write your analysis to opus-review.md"
+
+# Synthesize all reviews into a consensus
+cat gemini-review.md codex-review.md opus-review.md | cline -y \
+    "summarize these 3 reviews and identify: 1) issues all models agree on, 2) issues only one model caught, 3) your final recommendation"
+```
+
+**Why this works:**
+- **Redundancy**: Issues caught by all 3 models are high-confidence
+- **Coverage**: Each model has blind spots; together they cover more ground
+- **Prioritization**: Consensus issues should be fixed first
+- **Learning**: See which model types catch which issue types
+
+### Advanced: Parallel Reviews
+
+Run reviews in parallel for faster feedback:
+
+```bash
+# Run all reviews simultaneously
+git show | cline -y --config ~/.cline-gemini "review and save to gemini-review.md" &
+git show | cline -y --config ~/.cline-codex "review and save to codex-review.md" &
+git show | cline -y --config ~/.cline-opus "review and save to opus-review.md" &
+
+# Wait for all to complete
+wait
+
+# Synthesize
+cat *-review.md | cline -y "create consensus review"
+```
+
+<Note>
+Parallel execution requires managing multiple Cline instances. See [Multi-instance workflows](/cline-cli/three-core-flows#3-multi-instance-run-parallel-agents) for details.
+</Note>
+
+## Extended Thinking for Complex Tasks
+
+Use the `--thinking` flag when Cline needs to analyze multiple approaches:
+
+```bash
+# Without thinking: Fast but may miss nuances
+cline -y "refactor this codebase"
+
+# With thinking: Slower but more thorough
+cline -y --thinking \
+    "refactor this codebase - consider: performance, maintainability, backward compatibility"
+```
+
+The `--thinking` flag allocates 1024 tokens for internal reasoning before Cline responds. Best for:
+- Architectural decisions
+- Security analysis
+- Complex refactoring
+- Multi-step planning
+
+## Best Practices
+
+1. **Profile your workload**: Track which tasks are simple vs. complex
+2. **Match models to tasks**: Use fast models for summaries, powerful models for reasoning
+3. **Automate switching**: Script model selection based on task type
+4. **Monitor costs**: Different models have 10-100x price differences
+5. **Validate important decisions**: Use multi-model consensus for critical changes
+
+## Production Examples
+
+### Cost-Optimized PR Review
+
+```bash
+# Haiku: Quick summary and issue identification
+gh pr view $PR | cline -y --config ~/.cline-haiku \
+    "list all issues to fix, output as JSON"
+
+# Opus with thinking: Deep analysis only if issues found
+if [ -s issues.json ]; then
+    cline -y --thinking --config ~/.cline-opus \
+        "analyze these issues and recommend fixes"
+fi
+```
+
+### Security-Focused Multi-Model Scan
+
+```bash
+# Different models have different security perspectives
+git diff main | cline -y --config ~/.cline-gemini "security review" > gemini-sec.md &
+git diff main | cline -y --config ~/.cline-opus "security review" > opus-sec.md &
+git diff main | cline -y --config ~/.cline-codex "security review" > codex-sec.md &
+wait
+
+# High-priority: Issues all 3 models found
+cat *-sec.md | cline -y "find security issues all 3 reviews mentioned"
+```
+
+## Related Documentation
+
+<Columns cols={2}>
+  <Card title="CLI Reference" icon="terminal" href="/cline-cli/cli-reference">
+    Complete documentation for --config and --thinking flags
+  </Card>
+  
+  <Card title="Three Core Flows" icon="route" href="/cline-cli/three-core-flows">
+    Learn about interactive mode, headless automation, and multi-instance workflows
+  </Card>
+  
+  <Card title="Model Selection Guide" icon="brain" href="/core-features/model-selection-guide">
+    Compare models and choose the right one for your needs
+  </Card>
+  
+  <Card title="CI/CD Integration" icon="github" href="/cline-cli/samples/github-integration">
+    Automate GitHub workflows with Cline CLI
+  </Card>
+</Columns>

docs/cline-cli/samples/overview.mdx

@@ -8,6 +8,22 @@ This section provides sample implementations that demonstrate various Cline CLI
 ## Available Samples
 
 <CardGroup cols={1}>
+  <Card 
+    title="Model Orchestration" 
+    icon="layer-group" 
+    href="/cline-cli/samples/model-orchestration"
+  >
+    Use multiple AI models strategically with --config and --thinking flags. Optimize costs by routing simple tasks to cheap models and complex reasoning to premium models. Includes patterns for CI/CD code review, task phase optimization, and multi-model consensus.
+  </Card>
+
+  <Card 
+    title="Worktree Workflows" 
+    icon="code-branch" 
+    href="/cline-cli/samples/worktree-workflows"
+  >
+    Use Git worktrees with the --cwd flag to run parallel tasks, test different approaches, and pipe context between isolated environments. Includes patterns for parallel execution, cross-worktree piping, and combining with model orchestration.
+  </Card>
+
   <Card 
     title="GitHub Root Cause Analysis" 
     icon="magnifying-glass-chart" 

docs/cline-cli/samples/worktree-workflows.mdx

@@ -0,0 +1,275 @@
+---
+title: "Worktree Workflows"
+description: "Use Git worktrees with Cline CLI to run parallel tasks, test different approaches, and pipe context between isolated environments"
+---
+
+# Worktree Workflows
+
+Git worktrees let you have multiple branches checked out simultaneously in different folders. Combined with Cline CLI's `--cwd` flag, this enables powerful parallel development workflows and isolated experimentation.
+
+<Tip>
+New to Git worktrees? See our comprehensive [Worktrees guide](/features/worktrees) for the full concept explanation, VS Code integration, and best practices.
+</Tip>
+
+## Quick Worktree Setup
+
+If you haven't used Git worktrees before, here's the essentials:
+
+```bash
+# Create a new worktree in ~/worktree-a on branch feature-a
+git worktree add ~/worktree-a -b feature-a
+
+# Create another worktree for a different feature
+git worktree add ~/worktree-b -b feature-b
+
+# List all worktrees
+git worktree list
+
+# Remove a worktree when done
+git worktree remove ~/worktree-a
+```
+
+Each worktree is a separate folder with its own branch checked out. They all share the same Git history and `.git` directory, but have independent working directories.
+
+## The `--cwd` Flag
+
+The `-c, --cwd <path>` flag tells Cline to run in a specific directory without changing your current location:
+
+```bash
+# Run Cline in a different directory
+cline --cwd ~/worktree-a -y "refactor the authentication code"
+
+# Short form
+cline -c ~/worktree-b -y "add unit tests"
+```
+
+This is the key to worktree workflows—you can run multiple Cline instances in different worktrees simultaneously from a single terminal.
+
+## Pattern 1: Parallel Task Execution
+
+Run different tasks in parallel across multiple worktrees. Each task works on a separate branch in complete isolation.
+
+### Example: Parallel Feature Development
+
+```bash
+# Terminal 1: Update docs in worktree-a
+cline --cwd ~/worktree-a -y "read the last 10 changes using git show and update our README with them" &
+
+# Terminal 2: TypeScript migration in worktree-b
+cline --cwd ~/worktree-b -y "update the index.js to use typescript" &
+
+# Terminal 3: Refactoring in worktree-c
+cline --cwd ~/worktree-c -y "refactor the cli/ folder to be more modular" &
+
+# Wait for all to complete
+wait
+```
+
+The `&` runs each command in the background, allowing all three to execute simultaneously.
+
+### When to Use Parallel Execution
+
+**Perfect for:**
+- Multiple independent features
+- Bulk refactoring across different modules
+- Running tests in one worktree while developing in another
+- Trying multiple approaches to the same problem
+
+**Not ideal for:**
+- Tasks that modify the same files (merge conflicts likely)
+- Tasks that depend on each other's results
+- When you need to monitor progress closely
+
+## Pattern 2: Cross-Worktree Context Piping
+
+Pipe output from one worktree as input to another. Use when a task in one worktree needs context from attempts in another worktree.
+
+### Example: Learning from Failures
+
+```bash
+# Try approach A in worktree-a, capture only the failure summary
+cline --cwd ~/worktree-a -y \
+  "edit the index.ts to be better and then npm run. if it fails, output ONLY the failure summary. nothing else but the failure summary" \
+  | cline --cwd ~/worktree-b -y \
+  "i've tried to edit the index.ts in a different worktree but it failed. use a different approach for this work tree"
+```
+
+**How it works:**
+1. First Cline instance runs in `worktree-a`, attempts a change, tests it
+2. If it fails, outputs just the failure summary
+3. That summary is piped to a second Cline instance in `worktree-b`
+4. Second instance sees the failure and tries a different approach
+
+### When to Use Context Piping
+
+**Perfect for:**
+- A/B testing different solutions
+- Learning from failed attempts
+- Iterative refinement (try → analyze → try differently)
+- Comparing outputs across approaches
+
+**Not ideal for:**
+- Simple tasks that don't need cross-context
+- When both worktrees would succeed independently
+- Real-time collaboration (use parallel execution instead)
+
+## Combining with Other CLI Features
+
+### Different Models Per Worktree
+
+Use `--config` to run different models in different worktrees:
+
+```bash
+# Cheap model for simple docs update
+cline --cwd ~/worktree-docs --config ~/.cline-haiku -y \
+  "update README with latest changes"
+
+# Expensive model for complex refactoring
+cline --cwd ~/worktree-refactor --config ~/.cline-opus --thinking -y \
+  "refactor authentication system for better security"
+```
+
+This optimizes costs while maintaining quality where it matters.
+
+### Task Isolation
+
+Keep long-running worktree sessions isolated by running each task against a different worktree path:
+
+```bash
+# Run tasks in dedicated worktrees
+cline --cwd ~/worktree-a -y "long-running task"
+cline --cwd ~/worktree-b -y "another task"
+```
+
+Each worktree has its own Git branch and working directory, so task history and changes stay separated without needing instance management.
+
+### With YOLO Mode
+
+The `-y` (YOLO) flag is essential for worktree workflows:
+
+```bash
+# Without -y: Opens interactive chat (blocks other tasks)
+cline --cwd ~/worktree-a "refactor code"
+
+# With -y: Runs autonomously (doesn't block)
+cline --cwd ~/worktree-a -y "refactor code" &
+```
+
+For parallel execution, always use `-y` to avoid blocking on user approval.
+
+## Real-World Workflow Example
+
+Here's a complete workflow showing how these patterns work together:
+
+```bash
+# Setup: Create three worktrees
+git worktree add ~/cline-worktrees/feature-auth -b feature/authentication
+git worktree add ~/cline-worktrees/feature-api -b feature/api-endpoints
+git worktree add ~/cline-worktrees/fix-tests -b fix/failing-tests
+
+# Pattern 1: Run parallel independent tasks
+cline -c ~/cline-worktrees/feature-auth -y --config ~/.cline-sonnet \
+  "implement JWT authentication" &
+
+cline -c ~/cline-worktrees/feature-api -y --config ~/.cline-sonnet \
+  "create REST API endpoints for user management" &
+
+cline -c ~/cline-worktrees/fix-tests -y --config ~/.cline-haiku \
+  "fix all failing unit tests" &
+
+wait
+echo "All parallel tasks complete!"
+
+# Pattern 2: Use piping for iterative refinement
+cline -c ~/cline-worktrees/feature-auth -y \
+  "test the authentication with curl. output only errors if any" \
+  | cline -c ~/cline-worktrees/feature-auth -y \
+  "fix the authentication issues described in the input"
+
+# Merge successful changes back
+cd ~/cline-worktrees/feature-auth
+git checkout main
+git merge feature/authentication
+
+# Cleanup
+git worktree remove ~/cline-worktrees/feature-auth
+```
+
+## Best Practices
+
+<AccordionGroup>
+  <Accordion title="Worktree Organization">
+    - **Use a dedicated folder**: Create `~/cline-worktrees/` for all worktrees
+    - **Meaningful branch names**: Use `feature/`, `fix/`, `refactor/` prefixes
+    - **Clean up regularly**: Remove worktrees after merging branches
+  </Accordion>
+
+  <Accordion title="Task Isolation">
+    - **Independent features only**: Don't parallelize tasks that touch the same files
+    - **Test in isolation**: Each worktree should have its own test run
+    - **Separate configs**: Use `.worktreeinclude` to copy `node_modules` and build artifacts
+  </Accordion>
+
+  <Accordion title="Resource Management">
+    - **Monitor disk space**: Each worktree is a full checkout
+    - **Limit parallel tasks**: Running too many simultaneously can slow your system
+    - **Use background jobs wisely**: Track with `jobs` command, kill with `kill %1`, etc.
+  </Accordion>
+
+  <Accordion title="Error Handling">
+    - **Check exit codes**: Use `|| echo "Task failed"` to catch errors
+    - **Log outputs**: Redirect to files for debugging: `> worktree-a.log 2>&1`
+    - **Graceful cleanup**: Always remove worktrees after tasks complete
+  </Accordion>
+</AccordionGroup>
+
+## Troubleshooting
+
+<AccordionGroup>
+  <Accordion title="&quot;Branch already checked out&quot; error">
+    Git doesn't allow the same branch in multiple worktrees. Solutions:
+    - Use different branch names for each worktree
+    - Remove the existing worktree first: `git worktree remove <path>`
+  </Accordion>
+
+  <Accordion title="Tasks not running in parallel">
+    Make sure you're using:
+    - `&` at the end of each command to background it
+    - `-y` flag so Cline doesn't wait for approval
+    - Different worktrees (not the same path)
+  </Accordion>
+
+  <Accordion title="Pipe not working as expected">
+    Verify:
+    - First command outputs to stdout (not stderr)
+    - Second command reads from stdin (use `--` separator if needed)
+    - Both commands use correct `--cwd` paths
+  </Accordion>
+
+  <Accordion title="Changes not appearing in worktree">
+    Check:
+    - You're in the right worktree: `git worktree list`
+    - Files aren't gitignored
+    - You committed/staged changes if needed
+  </Accordion>
+</AccordionGroup>
+
+## Related Documentation
+
+<Columns cols={2}>
+  <Card title="Worktrees Overview" icon="code-branch" href="/features/worktrees">
+    Complete guide to Git worktrees, VS Code integration, and .worktreeinclude
+  </Card>
+  
+  <Card title="Model Orchestration" icon="layer-group" href="/cline-cli/samples/model-orchestration">
+    Use different models strategically with --config and --thinking flags
+  </Card>
+  
+  <Card title="CLI Reference" icon="terminal" href="/cline-cli/cli-reference">
+    Complete documentation for --cwd and all other CLI flags
+  </Card>
+  
+  <Card title="Three Core Flows" icon="route" href="/cline-cli/three-core-flows">
+    Learn about interactive mode, task mode, and plain text workflows
+  </Card>
+</Columns>

docs/cline-cli/three-core-flows.mdx

@@ -1,158 +1,292 @@
 ---
-title: "Three Core Flows"
-description: "Learn the three ways to use Cline CLI: interactive mode, headless automation, and multi-instance parallelization"
+title: "CLI Workflows"
+description: "Learn the three ways to use Cline CLI: interactive mode, direct task execution, and automation"
 ---
 
-Two concepts to understand:
+Cline CLI supports three primary workflows, each optimized for different use cases. Choose the approach that best fits your needs.
 
-**Task** - A single job for Cline to complete ("add tests to utils.js"). You describe what you want, Cline plans how to do it, then executes the plan. Tasks run on instances.
+<Note>
+**Migrating from an older CLI version?** Instance commands (`cline instance new/list/kill`) have been removed in Cline CLI 2.0. The new architecture is simpler. Just run `cline` for interactive mode or `cline "task"` for direct execution.
+</Note>
 
-**Instance** - An independent Cline workspace. Each instance runs one task at a time. Create multiple instances to run multiple tasks that work on different parts of your project in parallel.
+## 1. Interactive Mode
 
-## 1. Interactive mode: Plan first, then act
+The interactive CLI provides the richest experience for interactive development.
 
-Start here to see how Cline works. Interactive mode opens a chat session where you can review plans before execution.
+### Getting Started
 
 ```bash
 cline
 ```
 
-Cline opens an interactive session in your current directory. Type your task as a message. Cline enters Plan mode and proposes a step-by-step strategy.
+This launches an interactive session in your current directory. Type your task, and Cline will analyze and execute it.
 
-Review or edit the plan in chat. When you're ready, switch to execution:
+### Key Features
 
-```bash
-/act
+**Plan/Act Mode Toggle** - Press `Tab` to switch between modes:
+- **Plan Mode**: Cline analyzes your request and presents a strategy
+- **Act Mode**: Cline executes actions directly
+
+**Auto-approve Toggle** - Press `Shift+Tab` to enable automatic approval for all actions.
+
+**Slash Commands** - Type `/` for quick access to:
+- `/settings` - Configure providers, models, and features
+- `/models` - Quick model switching
+- `/history` - Browse and resume previous tasks
+- `/clear` - Start a fresh task
+- `/help` - Show available commands
+
+**File Mentions** - Type `@` to reference workspace files:
+```
+@src/utils.ts add error handling to this file
 ```
 
-Cline executes the approved steps—reading files, writing code, running commands. You maintain control throughout the process.
+**Session Summary** - When you exit with `Ctrl+C`, Cline displays a summary of your session including tasks completed, files modified, and token usage.
+
+### When to Use Interactive Mode
+
+- Exploring a new codebase
+- Complex refactoring that requires back-and-forth
+- Learning how Cline approaches problems
+- Tasks where you want to review before executing
+
+[Full Interactive Mode Guide →](/cline-cli/interactive-mode)
 
-## 2. Headless single-shot: Complete a task without chat
+## 2. Direct Task Execution
 
-Use this for automation where you want a one-liner that just does the work.
+Execute tasks directly from the command line without entering interactive mode.
+
+### Basic Usage
 
 ```bash
-cline instance new --default
-cline task new -y "Generate unit tests for all Go files"
+cline "Add unit tests to utils.js"
 ```
 
-With the `-y` (YOLO) flag, Cline plans and executes autonomously without interactive chat. Perfect for CI, cron jobs, or scripts.
+Cline analyzes your task, creates a plan, and executes it. You'll be prompted for approval at key decision points.
+
+### Piping Context
 
-Examples:
+Pipe file contents or command output into Cline:
 
 ```bash
-# Create a complete feature
-cline task new -y "Create a REST API for user authentication"
+# Explain a file
+cat README.md | cline "Summarize this document"
 
-# Generate documentation
-cline task new -y "Add JSDoc comments to all functions in src/"
+# Review git changes
+git diff | cline "Review these changes and suggest improvements"
 
-# Refactor code
-cline task new -y "Convert all var declarations to const/let"
+# Analyze command output
+npm test 2>&1 | cline "Analyze these test failures and fix them"
 ```
 
-Monitor your task with:
+### Chaining Cline Commands
+
+Pipe Cline's output into another Cline instance for creative workflows:
 
 ```bash
-# View task status
-cline task view
+# Explain changes, then write a commit message
+git diff | cline -y "explain these changes" | cline -y "write a commit message for this"
 
-# Follow task progress in real-time
-cline task view --follow
+# Generate code, then write tests
+cline -y "create a fibonacci function" | cline -y "write unit tests for this code"
+
+# Fun: Generate a poem about your code
+git diff | cline -y "explain" | cline -y "write a haiku about this"
 ```
 
-Press Ctrl+C to exit the view.
+### Including Images
 
-<Note>
-Run YOLO mode with care on a directory or a clean Git branch. You get speed in exchange for oversight, so be ready to revert if needed.
-</Note>
+Attach images to your task:
 
-## 3. Multi-instance: Run parallel agents
+```bash
+cline task -i screenshot.png "Fix the layout issue shown in this screenshot"
 
-Multiple instances let you parallelize work on the same project without colliding contexts. Run frontend, backend, and infrastructure tasks simultaneously.
+# Or reference inline
+cline "Fix the UI shown in @./design-mockup.png"
+```
 
-Create your first instance:
+### Mode Selection
 
 ```bash
-cline instance new
+# Start in Plan mode (analyze before acting)
+cline -p "Design a REST API for user management"
+
+# Start in Act mode (default)
+cline -a "Fix the typo in README.md"
 ```
 
-This returns an instance address you'll use to target tasks. Attach a task to this instance:
+### When to Use Direct Execution
+
+- Quick, well-defined tasks
+- Tasks with sufficient context in the prompt
+- Scripting and shell workflows
+- When you don't need interactive conversation
+
+## 3. Automation & CI/CD
+
+For fully autonomous operation in scripts, CI/CD pipelines, and automated workflows.
+
+### YOLO Mode (Yes Mode)
+
+The `-y` or `--yolo` flag enables fully autonomous operation:
 
 ```bash
-# Frontend work on first instance
-cline task new -y "Build React components"
+cline -y "Run the test suite and fix any failures"
 ```
 
-Create a second instance and set it as default in one command:
+In YOLO mode:
+- All actions are auto-approved
+- Output is plain text (non-interactive)
+- Process exits automatically when complete
+- Perfect for CI/CD and scripts
+
+<Warning>
+Run YOLO mode on a clean git branch or directory. You get speed in exchange for oversight, so be ready to revert if needed.
+</Warning>
+
+### JSON Output
+
+Use `--json` for machine-readable output:
 
 ```bash
-cline instance new --default
+cline --json "List all TODO comments in the codebase" | jq '.text'
 ```
 
-Now you can create tasks without specifying the address—they automatically use the default instance:
+JSON output follows the same format as task files in `~/.cline/data/tasks/<id>/ui_messages.json`.
+
+**JSON Message Schema:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `"ask"` or `"say"` | Message category |
+| `text` | `string` | Message content |
+| `ts` | `number` | Unix timestamp (ms) |
+| `reasoning` | `string` | (Optional) Model reasoning |
+| `partial` | `boolean` | (Optional) Streaming flag |
+
+### Timeout Control
+
+Set a maximum execution time:
 
 ```bash
-# Backend work on the new default instance
-cline task new -y "Implement API endpoints"
+cline -y --timeout 600 "Run full test suite"
 ```
 
-List all running instances:
+### Environment Variables
 
+Control Cline behavior via environment variables:
+
+**CLINE_DIR** - Custom configuration directory:
 ```bash
-cline instances list
+export CLINE_DIR=/path/to/config
+cline -y "your task"
 ```
 
-Stop all instances when done:
-
+**CLINE_COMMAND_PERMISSIONS** - Restrict allowed commands:
 ```bash
-cline instances kill -a
+export CLINE_COMMAND_PERMISSIONS='{"allow": ["npm *", "git *"], "deny": ["rm -rf *"]}'
+cline -y "your task"
 ```
 
-<Tip>
-Keep track of instance addresses returned by `cline instance new`. When scripting multiple agents, store these IDs and direct your tasks to the appropriate instance.
-</Tip>
+See [Configuration](/cline-cli/configuration#environment-variables) for full documentation.
+
+### GitHub Actions Example
+
+Automate PR reviews with Cline:
+
+```yaml
+name: AI Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      
+      - name: Install Cline
+        run: npm install -g cline
+      
+      - name: Configure Cline
+        run: cline auth -p anthropic -k ${{ secrets.ANTHROPIC_API_KEY }}
+      
+      - name: Review PR
+        run: |
+          git diff origin/main...HEAD | cline -y "Review this PR for:
+          - Potential bugs
+          - Security issues  
+          - Performance concerns
+          - Code style violations
+          
+          Provide a summary of findings."
+```
 
-## Configuring context window for local providers
+### Shell Script Example
 
-For Ollama and LM Studio, you can configure the model context window via CLI:
+Create a code review script:
 
 ```bash
-# For Ollama
-cline config s ollama-api-options-ctx-num=32768
+#!/bin/bash
+# review.sh - AI-powered code review
+
+set -e
+
+# Get the diff
+DIFF=$(git diff HEAD~1)
+
+if [ -z "$DIFF" ]; then
+  echo "No changes to review"
+  exit 0
+fi
 
-# For LM Studio
-cline config s lm-studio-max-tokens=32768
+# Run Cline review
+echo "$DIFF" | cline -y --json "Review this code diff for issues" | jq -r '.text'
 ```
 
-For other providers (Anthropic, OpenRouter, etc.), the context window is defined per model in the model metadata and is not user-configurable—Cline uses each model's built-in context limits automatically.
+### When to Use Automation Mode
 
-## Choosing the right flow
+- CI/CD pipelines
+- Scheduled maintenance tasks
+- Batch processing
+- Any workflow requiring non-interactive execution
 
-- **Interactive mode**: Best for exploring new problems, learning how Cline works, or when you want to review plans before execution
-- **Headless single-shot**: Perfect for automation, CI/CD, and tasks where you trust Cline to execute without supervision
-- **Multi-instance**: Use when you need to parallelize work or maintain separate contexts for different parts of your project
+## Choosing the Right Flow
 
-<Tip>
-For in-depth commands and flags, check out the [CLI reference](/cline-cli/cli-reference) page for complete documentation on all available options.
-</Tip>
+| Use Case | Recommended Flow |
+|----------|------------------|
+| Exploring a new codebase | Interactive Mode |
+| Complex refactoring | Interactive Mode (Plan first) |
+| Quick file edits | Direct Execution |
+| Code review | Direct Execution with pipe |
+| CI/CD integration | Automation (`-y` flag) |
+| Scheduled tasks | Automation (`-y` flag) |
+| Learning Cline | Interactive Mode |
 
-## Next steps
+## Next Steps
 
 <Columns cols={2}>
-  <Card title="CLI reference" icon="terminal" href="/cline-cli/cli-reference">
-    Complete command documentation including configuration, instance management, and task commands.
+  <Card title="Interactive Mode" icon="terminal" href="/cline-cli/interactive-mode">
+    Master keyboard shortcuts, slash commands, and file mentions.
   </Card>
   
-  <Card title="Plan and Act" icon="brain" href="/features/plan-and-act">
-    Deep dive into Plan and Act modes, including when to use each and how to switch between them.
+  <Card title="CLI Reference" icon="book" href="/cline-cli/cli-reference">
+    Complete command documentation with all flags and options.
   </Card>
   
-  <Card title="YOLO mode" icon="zap" href="/features/yolo-mode">
-    Understand how YOLO mode works and when to use full automation versus manual approval.
+  <Card title="Configuration" icon="gear" href="/cline-cli/configuration">
+    Environment variables, rules, and advanced settings.
   </Card>
   
-  <Card title="Task management" icon="clipboard-check" href="/features/tasks/task-management">
-    Learn how Cline tracks and manages tasks, including saving and restoring state from checkpoints.
+  <Card title="YOLO Mode" icon="zap" href="/features/yolo-mode">
+    Deep dive into autonomous execution and safety considerations.
   </Card>
 </Columns>

docs/docs.json

@@ -87,11 +87,16 @@
 						"pages": [
 							"cline-cli/overview",
 							"cline-cli/installation",
+							"cline-cli/interactive-mode",
+							"cline-cli/configuration",
 							"cline-cli/three-core-flows",
+							"cline-cli/acp-editor-integrations",
 							{
 								"group": "CLI Samples",
 								"pages": [
 									"cline-cli/samples/overview",
+									"cline-cli/samples/model-orchestration",
+									"cline-cli/samples/worktree-workflows",
 									"cline-cli/samples/github-issue-rca",
 									"cline-cli/samples/github-integration"
 								]
@@ -438,6 +443,10 @@
 		{
 			"source": "/features/conditional-rules",
 			"destination": "/features/cline-rules/conditional-rules"
+		},
+		{
+			"source": "/cline-cli/authentication",
+			"destination": "/cline-cli/installation"
 		}
 	],
 	"search": {

docs/features/worktrees.mdx

@@ -5,13 +5,6 @@ sidebarTitle: "Worktrees"
 
 Worktrees let you work on multiple branches simultaneously, each in its own folder. This enables Cline to work on tasks in parallel across separate VS Code windows, or lets Cline work independently while you continue coding in your main workspace.
 
-<Frame>
-	<img
-		src="https://storage.googleapis.com/cline_public_images/docs/assets/worktrees-overview.png"
-		alt="Worktrees view showing multiple linked worktrees"
-	/>
-</Frame>
-
 ## What Are Git Worktrees?
 
 A Git worktree is a linked copy of your repository in a separate folder, checked out to a specific branch. All worktrees share the same Git history and `.git` directory, but each has its own working directory with different code checked out.
@@ -123,13 +116,6 @@ When you're done working in a worktree and ready to merge your changes back to t
 3. Choose whether to delete the worktree after merging
 4. Click **Merge**
 
-<Frame>
-	<img
-		src="https://storage.googleapis.com/cline_public_images/docs/assets/worktrees-merge.png"
-		alt="Merge worktree modal"
-	/>
-</Frame>
-
 #### Handling Merge Conflicts
 
 If your branch has conflicts with the main branch, Cline will detect them and show you the conflicting files. You have two options:
@@ -226,6 +212,24 @@ Worktrees are not available in certain workspace configurations:
 
 The Worktrees view will display a message explaining the limitation if either of these applies to your workspace.
 
+## Using Worktrees with Cline CLI
+
+Cline CLI's `--cwd` flag unlocks powerful command-line worktree workflows:
+
+- **Parallel execution**: Run multiple Cline instances simultaneously in different worktrees
+- **Context piping**: Pipe output from one worktree as input to another for iterative refinement
+- **Combined with other features**: Use with `--config` for different models per worktree, or `--thinking` for deep analysis
+
+Example:
+```bash
+# Run parallel tasks in different worktrees
+cline --cwd ~/worktree-a -y "refactor authentication" &
+cline --cwd ~/worktree-b -y "add unit tests" &
+wait
+```
+
+For complete CLI worktree patterns and examples, see [Worktree Workflows](/cline-cli/samples/worktree-workflows).
+
 ## Troubleshooting
 
 <AccordionGroup>

implementation_plan.md

@@ -0,0 +1,342 @@
+ # Implementation Plan: Cline CLI Documentation Update
+
+[Overview]
+Update the Cline CLI documentation to reflect the new CLI 2.0 architecture that removes instances, adds a rich TUI experience, and introduces streamlined authentication options.
+
+The Cline CLI 2.0 has undergone significant changes. The previous architecture used explicit instance management (`cline instance new`, `cline instance list`, etc.) which has been completely removed. The new architecture simplifies the user experience:
+
+1. **TUI Mode**: Running `cline` without arguments launches a full-featured terminal UI built with React Ink, featuring an animated robot, file mentions (@), slash commands (/), session summaries, and inline settings panels. This provides a "Claude Code-like" experience.
+
+2. **CLI Mode**: Running `cline "prompt"` executes tasks directly. With `--yolo` flag, it runs non-interactively with output to stdout, making it ideal for CI/CD, piping, and bash scripts.
+
+3. **Authentication**: Multiple options including Cline account OAuth, ChatGPT subscription OAuth (via Codex), import from existing CLI tools (Codex CLI, OpenCode), and BYO API keys. Supports all providers from the VS Code extension (superset).
+
+The documentation must clearly separate these two user journeys (TUI interactive vs CLI automation) while documenting deprecated features for users migrating from older versions.
+
+**Note:** The CLI is now generally available (no longer preview) and supports macOS, Linux, and Windows.
+
+[Types]
+No code type changes required - this is a documentation-only update.
+
+This implementation plan only covers documentation files (`.mdx` files in `docs/cline-cli/`). No TypeScript interfaces, types, or code modifications are needed.
+
+[Files]
+Update existing files and create new documentation pages for comprehensive coverage.
+
+**Files to UPDATE (in-place):**
+- `docs/cline-cli/overview.mdx` - Remove instance references, reframe around TUI vs CLI modes
+- `docs/cline-cli/installation.mdx` - Expand with prerequisites, post-install steps, authentication
+- `docs/cline-cli/three-core-flows.mdx` - Complete rewrite to remove instances, replace with TUI/CLI/Automation flows
+- `docs/cline-cli/cli-reference.mdx` - Replace outdated man page content with current man page from `cli/man/cline.1.md`
+
+**Files to CREATE:**
+- `docs/cline-cli/tui-guide.mdx` - New comprehensive guide for the TUI experience
+- `docs/cline-cli/authentication.mdx` - New guide covering all auth options
+- `docs/cline-cli/configuration.mdx` - New guide for `cline config` and settings management
+
+**Files to MODIFY:**
+- `docs/docs.json` - Add new pages to navigation under CLI group
+
+[Functions]
+No function changes required - documentation only.
+
+This is a documentation update with no code changes to functions, methods, or handlers.
+
+[Classes]
+No class changes required - documentation only.
+
+This is a documentation update with no code changes to classes or components.
+
+[Dependencies]
+No dependency changes required.
+
+This is a documentation update with no package changes.
+
+[Testing]
+Documentation should be verified for accuracy by cross-referencing with source code.
+
+**Verification steps:**
+1. Cross-reference all documented features against `cli/src/index.ts` entry point
+2. Verify keyboard shortcuts against `cli/src/components/ChatView.tsx`
+3. Verify auth options against `cli/src/components/AuthView.tsx`
+4. Verify slash commands against `cli/src/components/HelpPanelContent.tsx`
+5. Verify config options against `cli/src/components/ConfigView.tsx` and `SettingsPanelContent.tsx`
+6. Verify import sources against `cli/src/utils/import-configs.ts`
+7. Run `npm run docs:dev` (if available) to preview documentation locally
+
+**Content accuracy checks:**
+- [ ] All keyboard shortcuts match source code
+- [ ] All command flags match `cli/src/index.ts`
+- [ ] Auth provider list matches `AuthView.tsx`
+- [ ] Import sources correctly documented (Codex CLI, OpenCode - NOT "Claude Code")
+- [ ] Deprecated features clearly marked
+
+[Implementation Order]
+Execute documentation updates in dependency order to ensure consistency.
+
+1. **Update `docs/docs.json`** - Add new page entries to navigation first so links work
+2. **Create `docs/cline-cli/authentication.mdx`** - Auth is foundational, other docs reference it
+3. **Create `docs/cline-cli/tui-guide.mdx`** - Core new content for TUI users
+4. **Create `docs/cline-cli/configuration.mdx`** - Config management guide
+5. **Update `docs/cline-cli/overview.mdx`** - Reframe overview with new architecture
+6. **Update `docs/cline-cli/installation.mdx`** - Expand installation guide
+7. **Update `docs/cline-cli/three-core-flows.mdx`** - Rewrite as TUI/CLI/Automation flows
+8. **Update `docs/cline-cli/cli-reference.mdx`** - Replace with current man page content
+9. **Verify all cross-references and links work correctly**
+
+---
+
+## Detailed File Specifications
+
+### 1. `docs/docs.json` (UPDATE)
+
+Add new pages to the CLI navigation group:
+
+```json
+{
+  "group": "CLI",
+  "pages": [
+    "cline-cli/overview",
+    "cline-cli/installation",
+    "cline-cli/authentication",
+    "cline-cli/tui-guide",
+    "cline-cli/configuration",
+    "cline-cli/three-core-flows",
+    {
+      "group": "CLI Samples",
+      "pages": [
+        "cline-cli/samples/overview",
+        "cline-cli/samples/github-issue-rca",
+        "cline-cli/samples/github-integration"
+      ]
+    },
+    "cline-cli/cli-reference"
+  ]
+}
+```
+
+### 2. `docs/cline-cli/authentication.mdx` (CREATE)
+
+**Purpose:** Comprehensive guide to all authentication options
+
+**Sections:**
+- Quick start (sign in with Cline - recommended)
+- Sign in with ChatGPT subscription (OpenAI Codex OAuth)
+- Import from existing CLI tools:
+  - Import from Codex CLI (`~/.codex/auth.json`)
+  - Import from OpenCode (`~/.local/share/opencode/auth.json`)
+- Bring your own API keys (manual provider configuration)
+- Supported providers list with examples
+- Switching providers (`cline auth`)
+- Quick setup flags (`cline auth -p <provider> -k <key> -m <model>`)
+
+**Key corrections from user input:**
+- User said "import from Claude Code" - INCORRECT. Actual sources are:
+  - Codex CLI (OpenAI's CLI tool)
+  - OpenCode
+- Document the actual import sources from `cli/src/utils/import-configs.ts`
+
+### 3. `docs/cline-cli/tui-guide.mdx` (CREATE)
+
+**Purpose:** Guide to the interactive terminal UI experience
+
+**Sections:**
+- Launching the TUI (`cline` without arguments)
+- The welcome screen and robot animation
+- Input field and message display
+- Keyboard shortcuts:
+  - `Tab` - Toggle Plan/Act mode
+  - `Shift+Tab` - Toggle auto-approve all
+  - `Enter` - Submit message
+  - `Esc` - Exit/cancel
+  - `↑/↓` - Navigate history
+  - `Home/End` - Cursor movement
+  - `Ctrl+A/E/W/U` - Text editing
+- File mentions with `@`:
+  - Type `@` to search workspace files
+  - Uses ripgrep for fast searching
+- Slash commands with `/`:
+  - `/settings` - Open settings panel
+  - `/models` - Quick model switching
+  - `/history` - Browse task history
+  - `/clear` - Start fresh task
+  - `/help` - Show help
+  - `/exit` - Exit CLI
+  - Workflow commands
+- Settings panel (`/settings`):
+  - API tab (provider, model, thinking)
+  - Auto-approve tab
+  - Features tab
+  - Account tab
+  - Other tab
+- Session summary on exit
+- Running multiple instances with `--config`:
+  - Default: settings shared across all instances
+  - Use `cline --config /path/to/config` for isolated configs
+  - Recommend tmux/terminal multiplexing for parallel work
+
+### 4. `docs/cline-cli/configuration.mdx` (CREATE)
+
+**Purpose:** Guide to `cline config` command and settings management
+
+**Sections:**
+- Running `cline config`
+- Configuration tabs:
+  - Settings (global state, workspace state)
+  - Rules (`.clinerules` files, Cursor rules, Windsurf rules)
+  - Workflows
+  - Hooks (if enabled)
+  - Skills (if enabled)
+- Keyboard navigation in config view
+- Editing configuration values
+- Configuration directory structure (`~/.cline/data/`)
+- Environment variables (`CLINE_DIR`, `CLINE_COMMAND_PERMISSIONS`)
+- Using `--config` flag for separate configurations
+
+### 5. `docs/cline-cli/overview.mdx` (UPDATE)
+
+**Changes:**
+- Remove all references to instances (`cline instance new/list/kill`)
+- Reframe around two modes: TUI (interactive) and CLI (automation)
+- Update "What you can build" section to remove multi-instance examples
+- Add section about new TUI features
+- Link to new authentication and TUI guide pages
+- Note deprecation of instance commands
+
+**New structure:**
+1. What is Cline CLI?
+2. Two ways to use Cline CLI:
+   - TUI Mode (interactive development)
+   - CLI Mode (automation and scripting)
+3. Supported Model Providers
+4. What you can build
+5. Learn more (links)
+
+### 6. `docs/cline-cli/installation.mdx` (UPDATE)
+
+**Changes:**
+- Remove "Preview Release - macOS and Linux Only" warning (CLI is now GA and supports Windows)
+- Add note that CLI supports macOS, Linux, and Windows
+- Add Node.js version requirement (20+, recommend 22)
+- Add version specification (`npm install -g [email protected]`)
+- Add more detail on post-install authentication
+- Link to new authentication guide
+- Add troubleshooting tips
+- Add verification steps
+
+**New structure:**
+1. Prerequisites (Node.js version)
+2. Installation: `npm install -g cline` (or `npm install -g [email protected]`)
+3. Authentication (`cline auth` - link to auth guide)
+4. Quick Start (two paths: TUI and CLI)
+5. Next Steps (links to guides)
+
+### 7. `docs/cline-cli/three-core-flows.mdx` (UPDATE - Major Rewrite)
+
+**Complete rewrite removing all instance references.**
+
+**New title suggestion:** "CLI Workflows" or "Getting Started Workflows"
+
+**New structure:**
+1. **Interactive TUI Mode** (replaces old "Interactive mode")
+   - Launch with `cline`
+   - Plan/Act mode toggle (Tab key)
+   - Using slash commands and file mentions
+   - Auto-approve toggle (Shift+Tab)
+   - Session summary on exit (Ctrl+C)
+2. **Direct Task Execution** (replaces old "Headless single-shot")
+   - `cline "prompt"` syntax
+   - Piping context (`cat file | cline "explain"`)
+   - Piping cline into cline: `git diff | cline -y "explain" | cline -y "write poem"`
+   - Image attachments
+3. **Automation & CI/CD** (replaces old "Multi-instance")
+   - `--yolo` / `-y` flag for non-interactive mode (also called "yes mode")
+   - `--json` output for parsing (same format as `~/.cline/data/tasks/<id>/ui_messages.json`)
+   - `--timeout` for long-running tasks
+   - Environment variables:
+     - `CLINE_DIR` - custom config directory
+     - `CLINE_COMMAND_PERMISSIONS` - restrict allowed shell commands
+   - Example GitHub Actions workflow for PR review
+
+**Creative use cases from engineer demo:**
+- Chain cline commands: `git diff | cline -y "explain" | cline -y "write a poem about this"`
+- GitHub PR review workflow with `gh` CLI integration
+
+**Deprecation notice:**
+Add a callout at the top noting that instance commands (`cline instance new/list/kill`) have been removed in favor of the simpler architecture.
+
+### 8. `docs/cline-cli/cli-reference.mdx` (UPDATE)
+
+**Changes:**
+- Replace the outdated embedded man page with content from `cli/man/cline.1.md`
+- The current man page in the docs references old instance commands
+- The actual man page (`cli/man/cline.1.md`) has correct, updated content
+- Convert man page markdown format to mdx documentation format
+- Add JSON output schema section
+- Add environment variables section
+- Remove all instance command references
+
+---
+
+---
+
+## Additional Features from Engineer Demo
+
+### Man Page
+- `man cline` - View in-depth documentation in terminal
+
+### Dev Tools
+- `cline dev log` - Opens log file for debugging
+- `cline update` - Check for and install updates
+
+### JSON Output Format
+- Same format as saved task files: `~/.cline/data/tasks/<id>/ui_messages.json`
+- Useful for programmatic use cases
+- Pipe through `jq` for easier parsing
+- Example: `cline --json "prompt" | jq '.text'`
+
+---
+
+## Verification Checklist
+
+After implementation, verify these user requirements are documented:
+
+- [x] New TUI experience explained
+- [x] NPM installation covered
+- [x] Authorization options:
+  - [x] Sign in with Cline
+  - [x] Sign in with ChatGPT Subscription (Codex OAuth)
+  - [x] Import from Codex CLI (CORRECTED from "Claude Code")
+  - [x] Import from OpenCode
+  - [x] Bring your own API keys
+  - [x] Bedrock support mentioned
+- [x] `cline auth` for changing providers
+- [x] Basic CLI usage:
+  - [x] `cline "task"` syntax
+  - [x] Piping context
+  - [x] `--yolo` / `-y` for CI/CD (also called "yes mode")
+- [x] TUI features:
+  - [x] `cline` alone launches TUI
+  - [x] Tab to toggle Plan/Act mode
+  - [x] Shift+Tab for auto-approve all
+  - [x] Session summary on exit (Ctrl+C)
+  - [x] `--config` for separate configs
+- [x] Instance deprecation noted
+- [x] `cline config` for rules, workflows, hooks, skills
+- [x] @ file mentions with autocomplete (fuzzy search)
+- [x] / slash commands with autocomplete
+  - [x] `/settings` documented
+  - [x] `/models` documented
+  - [x] `/history` documented
+  - [x] Workflows generate slash commands
+- [x] /settings panel sections documented (arrow keys to navigate tabs)
+- [x] Environment variables:
+  - [x] `CLINE_DIR` documented
+  - [x] `CLINE_COMMAND_PERMISSIONS` documented (security measure)
+- [x] Dev tools:
+  - [x] `cline dev log` documented
+  - [x] `cline update` documented
+  - [x] `man cline` documented
+- [x] JSON output format documented
+- [x] Piping cline into cline documented
+- [x] GitHub Actions PR review example included