mirror of
https://github.com/cline/cline.git
synced 2026-10-25 18:33:44 +08:00
0adccbdb70
* docs: match the CLI reference to CLI 3.0.68 The CLI reference and the pages that repeat it had drifted from the CLI. They named a `dev` command that no longer exists, swapped the --config and --data-dir defaults, described `connect` as an IDE adapter, said --thinking defaults to medium, and showed a JSON output shape (say/ask messages) that the CLI never prints. The documented `jq -r .text` example prints only nulls. Replace the pasted help with the 3.0.68 output and document what it lists: --compaction, --worktree, --update, --kanban, `skill`, `dashboard`, the `auth` options, `config <target>`, `connect --stop` and `--restart`, `mcp add`/`remove`, the `history` subcommands and options, and the `hub` subcommands including `drain` and `upgrade`. Rewrite the JSON section around the agent_event and run_result lines, with a jq filter that prints the final answer. Note that -k also saves the key, drop the `-i` image example (-i opens the TUI), and use the Cline provider's model id in the API auth example. Co-authored-by: Harshil Mistry <125483347+harshil-mistry@users.noreply.github.com> Co-authored-by: MarMar Labs <marmar9615@icloud.com> * docs: correct CLI defaults and JSON notes from review --retries defaults to 3, not the 6 that `cline --help` prints; note the discrepancy under the pasted help. Without --thinking, Cline uses the reasoning level saved from the TUI before the provider's default. Drop --page, which the CLI accepts but ignores. Say that a --timeout stops the run without a run_aborted line, and that scripts should skip line types they don't use. Use Claude Sonnet 5.5 in the auth examples, and say "in your terminal" where the pages described commands that need one. * fix(cli): make --help match what the CLI does `cline --help` said --retries defaults to 6, but runs use 3. The help now reads the same CLI_DEFAULT_MAX_CONSECUTIVE_MISTAKES constant that main.ts passes to the session, and a test ties the two together. --thinking now says that, without the flag, the CLI uses the level saved in the TUI before the provider default. -k says the key is also saved as the provider's key. `history --page` is hidden from help: the CLI never reads it, but it stays accepted so existing scripts keep working. The CLI reference shows the corrected help and no longer notes the wrong --retries default. The CLI README's -k and --thinking rows match. * fix(cli): name /model in the --thinking help Readers don't know what "the TUI" is. The level --thinking falls back to is the one chosen in the model picker, which users open with /model, so the help, the CLI reference, the overview and the README now say that. * fix(cli): warn that cline history --page is ignored cline history lists the newest sessions up to --limit and has never read --page. The option stays accepted so existing scripts keep working, but it now prints a deprecation notice to stderr. The terminal tests that expected --page in help, or ran it as if it selected a page, are removed. * fix(cli): say hub upgrade does not wait for --zen tasks cline hub upgrade waits only until no client is attached. A --zen run detaches once the hub accepts it, and scheduled runs never attach, so the upgrade can stop both mid-run. The help text and the hub command lists in the docs now say so. * docs: drop dashboard from the root help listing cline --help no longer lists dashboard; it is cline hub dashboard. * fix(cli): require a count for --retries; fix connect --restart example --retries was declared with an optional value, so a bare --retries set it to true and the CLI crashed calling .trim() on it. The option now requires a count, and a bare --retries fails with commander's "argument missing" error. cline connect passes options after the channel to the channel's connector, so "cline connect telegram --restart" never reached connect. The examples now put --stop and --restart before the channel, and the reference says why. * docs: scope the JSON line format to agent runs The JSON section read as the format of every --json, but only agent runs print typed lines. cline history --json prints one array, and each cline config target prints its own shape. The heading and both pages now say the line format is for tasks, and name the others. --------- Co-authored-by: Dominic Cooney <55120+dominiccooney@users.noreply.github.com> Co-authored-by: Harshil Mistry <125483347+harshil-mistry@users.noreply.github.com> Co-authored-by: MarMar Labs <marmar9615@icloud.com>
147 lines
4.2 KiB
Plaintext
147 lines
4.2 KiB
Plaintext
---
|
|
title: "CLI Overview"
|
|
sidebarTitle: "CLI Overview"
|
|
description: "Use Cline CLI for interactive terminal sessions and automated headless workflows."
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
- Cline CLI installed (install via `npm i -g cline`)
|
|
- Provider authenticated (`cline auth`) — use the Cline Provider, ClinePass, or your own provider key ([Authorization Guide](/getting-started/authorizing-with-cline#cli-setup))
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Interactive session
|
|
cline
|
|
|
|
# Run one task immediately
|
|
cline "refactor this module to use async/await"
|
|
|
|
# Structured output for scripts
|
|
cline --json "list TODO comments"
|
|
```
|
|
|
|
## Headless mode
|
|
|
|
Use headless mode for scripts/automation and processable output.
|
|
|
|
Headless is triggered when using flags like `--json`, when stdin is piped, or when output is redirected.
|
|
|
|
#### When headless activates
|
|
|
|
| Invocation | Reason |
|
|
|---|---|
|
|
| `cline --json "task"` | JSON output mode |
|
|
| `cat file \| cline "task"` | stdin is piped |
|
|
| `cline "task" > output.txt` | stdout is redirected |
|
|
|
|
```bash
|
|
# CI/script style execution
|
|
git diff | cline "review these changes"
|
|
|
|
# JSON for parsing: print only the final answer
|
|
cline --json "summarize this changelog" | jq -r 'select(.type == "run_result") | .text'
|
|
```
|
|
|
|
See: [Headless Mode](#headless-mode)
|
|
|
|
### Autonomous execution
|
|
|
|
For fully unattended runs, use auto-approval:
|
|
|
|
```bash
|
|
cline --auto-approve true "run tests and fix failures"
|
|
```
|
|
|
|
Mode selection also works in headless runs:
|
|
|
|
```bash
|
|
# plan-first
|
|
cline -p "design migration plan"
|
|
|
|
# act immediately (default)
|
|
cline "apply migration"
|
|
```
|
|
|
|
<Warning>
|
|
Autonomous execution can modify files and run commands without further prompts. Use a clean branch and review results.
|
|
</Warning>
|
|
|
|
## High-Value Commands
|
|
|
|
```bash
|
|
cline --help
|
|
cline <command> --help
|
|
```
|
|
|
|
| Command | Purpose |
|
|
|---|---|
|
|
| `cline` | Start interactive mode or run a prompt |
|
|
| `cline auth` | Authenticate and set provider/model |
|
|
| `cline config` | Show the current configuration |
|
|
| `cline mcp` | Manage MCP servers |
|
|
| `cline doctor` | Diagnose/fix configuration issues |
|
|
| `cline history` | Show and manage task history |
|
|
| `cline schedule` | Manage scheduled tasks |
|
|
| `cline hub` | Manage local hub daemon |
|
|
| `cline kanban` | Run the Kanban app |
|
|
|
|
## Most-Used Global Flags
|
|
|
|
Source of truth: [CLI Reference](/cli/cli-reference)
|
|
|
|
| Flag | Purpose |
|
|
|---|---|
|
|
| `-p, --plan` | Start in Plan mode |
|
|
| `--auto-approve <boolean>` | Global tool auto-approval (`true`/`false`, default `true`) |
|
|
| `-m, --model <model>` | Override model for this run |
|
|
| `-P, --provider <id>` | Override provider for this run |
|
|
| `-c, --cwd <path>` | Set working directory |
|
|
| `--config <dir>` | Use config directory |
|
|
| `--data-dir <dir>` | Use isolated local state |
|
|
| `--json` | Output newline-delimited JSON messages |
|
|
| `--thinking <level>` | Set reasoning effort: `none\|low\|medium\|high\|xhigh`. Bare `--thinking` uses `medium`. Without the flag, Cline uses the level you last chose with `/model`, or else the provider's default |
|
|
| `-t, --timeout <seconds>` | Set task timeout |
|
|
|
|
## Automation Patterns
|
|
|
|
### Pipe context in
|
|
|
|
```bash
|
|
cat README.md | cline "summarize key setup steps"
|
|
git diff | cline "review for potential regressions"
|
|
```
|
|
|
|
### Chain tasks
|
|
|
|
```bash
|
|
git diff | cline "explain these changes" | cline "write a commit message"
|
|
```
|
|
|
|
### Restrict command execution
|
|
|
|
The CLI has no allow or deny list for shell commands. To block commands, use a `PreToolUse` hook that cancels `run_commands` calls you don't allow, like the [.clineignore hook](/customization/clineignore#enforcing-clineignore-with-a-hook).
|
|
|
|
### Include images in tasks
|
|
|
|
Mention an image file with `@` and the CLI attaches it to the prompt:
|
|
|
|
```bash
|
|
cline "fix the UI shown in @./design-mockup.png"
|
|
```
|
|
|
|
### Set execution timeout
|
|
|
|
```bash
|
|
cline --timeout 600 "run full test suite"
|
|
```
|
|
|
|
## JSON Output Schema
|
|
|
|
When you give Cline a task with `--json`, each line is a JSON object with a `type`. Agent events arrive as `agent_event` lines, and a `run_result` line holds the final `text` when the run finishes. The [CLI Reference](/cli/cli-reference#json-output-for-agent-runs) describes the line types.
|
|
|
|
## Next Steps
|
|
|
|
- [CLI Reference](/cli/cli-reference)
|
|
- [ACP](/usage/acp) — use Cline as the coding agent in Zed, JetBrains IDEs, Neovim, and other ACP clients |