From 0adccbdb70efcd5317ee25caab71abdc0fb29393 Mon Sep 17 00:00:00 2001 From: Dominic Cooney Date: Wed, 7 Oct 2026 20:38:35 +0900 Subject: [PATCH] docs, fix(cli): match the CLI reference and --help to what the CLI does (#14895) * 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 `, `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 * 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 --- apps/cli/README.md | 4 +- apps/cli/src/commands/history-command.test.ts | 21 +- apps/cli/src/commands/history-command.ts | 12 +- apps/cli/src/commands/hub.ts | 2 +- apps/cli/src/commands/program.test.ts | 19 ++ apps/cli/src/commands/program.ts | 12 +- apps/cli/src/main.ts | 8 +- apps/cli/src/runtime/defaults.ts | 6 + apps/cli/src/tests/cli/history.test.ts | 19 +- apps/cli/src/tests/flags.test.ts | 5 +- apps/cli/src/tests/help.test.ts | 2 +- docs/api/authentication.mdx | 2 +- docs/cli/cli-reference.mdx | 212 ++++++++++++------ docs/cli/connectors.mdx | 5 +- docs/mcp/mcp-overview.mdx | 17 +- docs/sdk/architecture/hub-spoke.mdx | 2 + docs/usage/cli-overview.mdx | 31 +-- 17 files changed, 245 insertions(+), 134 deletions(-) diff --git a/apps/cli/README.md b/apps/cli/README.md index 52a16026bb..2feead9d02 100644 --- a/apps/cli/README.md +++ b/apps/cli/README.md @@ -250,7 +250,7 @@ Schedules can route results back to chat surfaces with `--delivery-adapter`, `-- | `-s, --system ` | Override the system prompt | | `-P, --provider ` | Provider id (default: `cline`) | | `-m, --model ` | Model id (default: `anthropic/claude-sonnet-4.6`) | -| `-k, --key ` | API key override for this run | +| `-k, --key ` | API key for this run, also saved as the provider's key | | `-p, --plan` | Run in plan mode (default is act mode) | | `-i, --tui` | Interactive TUI multi-turn mode | | `-t, --timeout ` | Optional run timeout in seconds | @@ -258,7 +258,7 @@ Schedules can route results back to chat surfaces with `--delivery-adapter`, `-- | `--config ` | Configuration directory (used for CLI home resolution) | | `--hooks-dir ` | Additional hooks directory hint for runtime hook injection | | `--acp` | ACP (Agent Client Protocol) mode | -| `--thinking [none\|low\|medium\|high\|xhigh]` | Model thinking level when supported. Defaults to `medium` when the flag is provided without a level; thinking is off when the flag is omitted. | +| `--thinking [none\|low\|medium\|high\|xhigh]` | Model thinking level when supported. Defaults to `medium` when the flag is provided without a level. Without the flag, the CLI uses the level you last chose with `/model`, or the provider default. | | `--compaction ` | Context compaction mode. Defaults to `agentic`; use `basic` for local truncation or `off` to disable. | | `--retries ` | Maximum consecutive mistakes (retries) before halting (default: `3`) | | `--json` | Output NDJSON instead of styled text | diff --git a/apps/cli/src/commands/history-command.test.ts b/apps/cli/src/commands/history-command.test.ts index c4877b9d11..23a2526cb1 100644 --- a/apps/cli/src/commands/history-command.test.ts +++ b/apps/cli/src/commands/history-command.test.ts @@ -10,7 +10,10 @@ const historyMocks = vi.hoisted(() => ({ vi.mock("./history", () => historyMocks); -import { registerHistoryCommand } from "./history-command"; +import { + HISTORY_PAGE_DEPRECATION, + registerHistoryCommand, +} from "./history-command"; function createHarness(isInteractiveTTY: boolean) { const program = new Command() @@ -80,6 +83,22 @@ describe("registerHistoryCommand", () => { expect(setExitCode).toHaveBeenCalledWith(0); }); + it("warns that --page is ignored, hides it from help, and still lists history", async () => { + const { program, io, setExitCode } = createHarness(false); + const history = program.commands.find((cmd) => cmd.name() === "history"); + + await program.parseAsync(["history", "--page", "2"], { from: "user" }); + + expect(history?.helpInformation()).not.toContain("--page"); + expect(io.writeErr).toHaveBeenCalledWith(HISTORY_PAGE_DEPRECATION); + expect(historyMocks.runHistoryList).toHaveBeenCalledWith({ + limit: 50, + outputMode: "text", + io, + }); + expect(setExitCode).toHaveBeenCalledWith(0); + }); + it("returns an error when delete is missing --session-id", async () => { const { program, io, setExitCode } = createHarness(false); diff --git a/apps/cli/src/commands/history-command.ts b/apps/cli/src/commands/history-command.ts index 137e47e8ea..247eeed494 100644 --- a/apps/cli/src/commands/history-command.ts +++ b/apps/cli/src/commands/history-command.ts @@ -1,4 +1,4 @@ -import type { Command } from "commander"; +import { type Command, Option } from "commander"; import type { TuiStartupTarget } from "../tui/types"; import type { CliOutputMode } from "../utils/types"; import { @@ -8,6 +8,9 @@ import { runHistoryUpdate, } from "./history"; +export const HISTORY_PAGE_DEPRECATION = + "--page is deprecated and ignored: cline history lists the newest sessions, up to --limit."; + type HistoryCommandIo = { writeln: (text?: string) => void; writeErr: (text: string) => void; @@ -42,10 +45,15 @@ export function registerHistoryCommand({ .description("List session history or manage saved sessions") .option("--json", "Output as JSON") .option("--limit ", "Maximum number of sessions to show", "50") - .option("--page ", "Page number for paginated results") + // Accepted so existing scripts keep working, but hidden and ignored: + // history lists only the newest --limit sessions. + .addOption(new Option("--page ").hideHelp()) .option("--config ", "configuration directory") .action(async () => { const opts = historyCmd.opts(); + if (opts.page !== undefined) { + io.writeErr(HISTORY_PAGE_DEPRECATION); + } const limit = Number.parseInt(opts.limit, 10); const outputMode = resolveHistoryOutputMode(program, historyCmd); if (outputMode === "text" && isInteractiveTTY()) { diff --git a/apps/cli/src/commands/hub.ts b/apps/cli/src/commands/hub.ts index 08af0273c5..34380528de 100644 --- a/apps/cli/src/commands/hub.ts +++ b/apps/cli/src/commands/hub.ts @@ -209,7 +209,7 @@ export function createHubCommand( hub .command("upgrade") .description( - "Drain, wait for the hub to go idle, stop it, and start a fresh one", + "Drain the hub and restart it; does not wait for --zen or scheduled tasks", ) .option( "--wait ", diff --git a/apps/cli/src/commands/program.test.ts b/apps/cli/src/commands/program.test.ts index e9e704d3cc..4979d9c9ee 100644 --- a/apps/cli/src/commands/program.test.ts +++ b/apps/cli/src/commands/program.test.ts @@ -5,6 +5,7 @@ import { setHomeDir, } from "@cline/shared/storage"; import { afterAll, beforeAll, describe, expect, it } from "vitest"; +import { CLI_DEFAULT_MAX_CONSECUTIVE_MISTAKES } from "../runtime/defaults"; import { createProgram } from "./program"; /** Render an absolute path under `home` the way help text does: `~/...`. */ @@ -58,4 +59,22 @@ describe("root option help text", () => { `Use isolated local state at this directory path (default: ${dataDirDefault})`, ); }); + + it("reports the --retries default that runs use", () => { + const help = createProgram() + .configureHelp({ helpWidth: 500 }) + .helpInformation(); + + expect(help).toContain( + `before exiting (default: ${CLI_DEFAULT_MAX_CONSECUTIVE_MISTAKES})`, + ); + }); + + it("rejects --retries without a count", () => { + const program = createProgram().configureOutput({ writeErr: () => {} }); + + expect(() => program.parse(["--retries"], { from: "user" })).toThrow( + /argument missing/, + ); + }); }); diff --git a/apps/cli/src/commands/program.ts b/apps/cli/src/commands/program.ts index ad5b6f1024..b0940495a6 100644 --- a/apps/cli/src/commands/program.ts +++ b/apps/cli/src/commands/program.ts @@ -1,5 +1,6 @@ import { Command, CommanderError, Option } from "commander"; import { version } from "../../package.json"; +import { CLI_DEFAULT_MAX_CONSECUTIVE_MISTAKES } from "../runtime/defaults"; import { CLI_COMPACTION_MODE_OPTION_DESCRIPTION, parseCliCompactionMode, @@ -37,7 +38,7 @@ export function addRootOptions(cmd: Command): Command { .option("-c, --cwd ", "Working directory") .option( "--thinking ", - "Set reasoning effort: none|low|medium|high|xhigh. Bare --thinking uses medium; omitted leaves provider default.", + "Set reasoning effort: none|low|medium|high|xhigh. Bare --thinking uses medium; omitted uses the level last chosen with /model, or the provider default.", ) .option("--compaction ", CLI_COMPACTION_MODE_OPTION_DESCRIPTION) .option( @@ -46,7 +47,10 @@ export function addRootOptions(cmd: Command): Command { ) .option("--id ", "Resume an existing session by ID") .option("-P, --provider ", "Provider id (default: cline)") - .option("-k, --key ", "API key override for this run") + .option( + "-k, --key ", + "API key for this run, also saved as the provider's key", + ) .option( "-m, --model ", "Model to use for the session with the selected provider", @@ -57,8 +61,8 @@ export function addRootOptions(cmd: Command): Command { ) .option("-z, --zen", "Start a session that runs in the background hub") .option( - "--retries [value]", - "Number of maximum consecutive mistakes (retries) before exiting (default: 6)", + "--retries ", + `Number of maximum consecutive mistakes (retries) before exiting (default: ${CLI_DEFAULT_MAX_CONSECUTIVE_MISTAKES})`, ) .option( "-t, --timeout ", diff --git a/apps/cli/src/main.ts b/apps/cli/src/main.ts index 5b09fe36d9..0e52e53617 100644 --- a/apps/cli/src/main.ts +++ b/apps/cli/src/main.ts @@ -16,7 +16,10 @@ import { autoUpdateOnStartup, getPreferredKanbanInstaller, } from "./commands/update"; -import { CLI_DEFAULT_CHECKPOINT_CONFIG } from "./runtime/defaults"; +import { + CLI_DEFAULT_CHECKPOINT_CONFIG, + CLI_DEFAULT_MAX_CONSECUTIVE_MISTAKES, +} from "./runtime/defaults"; import type { TuiStartupTarget } from "./tui/types"; import { filterChatModels } from "./utils/chat-models"; import { registerClineClientIdentity } from "./utils/cline-client-identity"; @@ -1045,7 +1048,8 @@ export async function runCli(): Promise { mode: effectiveMode, }), execution: { - maxConsecutiveMistakes: args.retries ?? 3, + maxConsecutiveMistakes: + args.retries ?? CLI_DEFAULT_MAX_CONSECUTIVE_MISTAKES, }, checkpoint: CLI_DEFAULT_CHECKPOINT_CONFIG, compaction: buildCliCompactionConfig(effectiveCompactionMode), diff --git a/apps/cli/src/runtime/defaults.ts b/apps/cli/src/runtime/defaults.ts index 7de9828653..2796079013 100644 --- a/apps/cli/src/runtime/defaults.ts +++ b/apps/cli/src/runtime/defaults.ts @@ -8,6 +8,12 @@ export const CLI_DEFAULT_LOOP_DETECTION = { hardThreshold: 5, } as const; +/** + * Consecutive mistakes a run tolerates before it stops or asks how to + * continue, when `--retries` is not given. `--help` reports this value. + */ +export const CLI_DEFAULT_MAX_CONSECUTIVE_MISTAKES = 3; + /** * Default checkpoint configuration for the CLI. * Core leaves checkpoints disabled by default (opt-in); diff --git a/apps/cli/src/tests/cli/history.test.ts b/apps/cli/src/tests/cli/history.test.ts index ca3217632f..757ce17aa8 100644 --- a/apps/cli/src/tests/cli/history.test.ts +++ b/apps/cli/src/tests/cli/history.test.ts @@ -2,8 +2,7 @@ // cline history - CLI tests // // Covers: -// - `cline history --limit X` - pagination limit -// - `cline history --page N` - page selection +// - `cline history --limit X` - result limit // - `cline history --config` - custom config directory // - `cline history --help` - help page // --------------------------------------------------------------------------- @@ -21,7 +20,7 @@ test.describe("cline history --help", () => { }); test("shows history help page with all flags", async ({ terminal }) => { - await expectVisible(terminal, ["Usage:", "--limit", "--page", "--config"]); + await expectVisible(terminal, ["Usage:", "--limit", "--config"]); }); }); @@ -36,19 +35,7 @@ test.describe("cline history --limit", () => { terminal, }) => { // The default config has 2 tasks in taskHistory.json; with limit=1 - // we should see pagination or only 1 task entry per page - await expectVisible(terminal, /history|task/i); - }); -}); - -test.describe("cline history --page", () => { - test.use({ - program: { file: CLINE_BIN, args: ["history", "--page", "1"] }, - ...TERMINAL_WIDE, - env: clineEnv("default"), - }); - - test("shows history for the specified page", async ({ terminal }) => { + // we should see only 1 task entry await expectVisible(terminal, /history|task/i); }); }); diff --git a/apps/cli/src/tests/flags.test.ts b/apps/cli/src/tests/flags.test.ts index 16c5d9e38b..f782ef5d2d 100644 --- a/apps/cli/src/tests/flags.test.ts +++ b/apps/cli/src/tests/flags.test.ts @@ -5,7 +5,7 @@ import { expectVisible } from "./helpers/terminal.js"; // Wide enough that long option descriptions (e.g. --thinking) render on a // single line. At narrower widths commander wraps them, splitting phrases -// like "omitted leaves provider default" across lines so the contiguous +// like "the level last chosen with /model" across lines so the contiguous // getByText assertions below fail. const HELP_TERMINAL = { columns: 200, rows: 50 }; @@ -29,7 +29,7 @@ test.describe("root flag descriptions", () => { "Configuration directory", "Set reasoning effort:", "Bare --thinking uses medium", - "omitted leaves provider default", + "the level last chosen with /model, or the provider default", "consecutive mistakes", "Output messages as JSON", "Check for updates and install if available", @@ -55,7 +55,6 @@ test.describe("history flag descriptions", () => { test("all history flags have correct descriptions", async ({ terminal }) => { await expectVisible(terminal, "number of sessions to show"); - await expectVisible(terminal, "Page number"); await expectVisible(terminal, "configuration directory"); }); }); diff --git a/apps/cli/src/tests/help.test.ts b/apps/cli/src/tests/help.test.ts index 95a83a5c61..2738a97e93 100644 --- a/apps/cli/src/tests/help.test.ts +++ b/apps/cli/src/tests/help.test.ts @@ -69,7 +69,7 @@ test.describe("cline history --help", () => { }); test("shows history usage and all flags", async ({ terminal }) => { - await expectVisible(terminal, ["Usage:", "--limit", "--page", "--config"]); + await expectVisible(terminal, ["Usage:", "--limit", "--config"]); }); }); diff --git a/docs/api/authentication.mdx b/docs/api/authentication.mdx index b1a208f97b..6eb749d5d2 100644 --- a/docs/api/authentication.mdx +++ b/docs/api/authentication.mdx @@ -66,7 +66,7 @@ The Cline CLI uses these tokens when you authenticate via: cline auth # Or quick setup with an API key -cline auth -p cline -k "YOUR_API_KEY" -m anthropic/claude-sonnet-4-6 +cline auth -p cline -k "YOUR_API_KEY" -m anthropic/claude-sonnet-5.5 ``` See the [CLI Reference](/cli/cli-reference#auth-options-provider) for all auth options. diff --git a/docs/cli/cli-reference.mdx b/docs/cli/cli-reference.mdx index a12e83c1d7..138885d1b6 100644 --- a/docs/cli/cli-reference.mdx +++ b/docs/cli/cli-reference.mdx @@ -14,7 +14,9 @@ cline --help # Show help for a specific command cline [options] [command] [prompt] ``` -## Help Menu (Source of Truth) +## Help Menu + +This is the output of `cline --help`. Run it to see the options in your version. ```text Usage: cline [options] [command] [prompt] @@ -22,46 +24,50 @@ Usage: cline [options] [command] [prompt] Cline CLI - AI coding assistant in your terminal Arguments: - prompt Your prompt. Default to start in act mode with auto-approve enabled. + prompt Your prompt. Default to start in act mode with auto-approve enabled. Options: - -V, --version Output the version number - -p, --plan Run in plan mode - --json Output messages as JSON instead of styled text - --auto-approve Set tool auto-approval for all tools (default: true) - -t, --timeout Optional timeout in seconds (default: 0 for no timeout) - -m, --model Model to use for the session with the selected provider - -v, --verbose Show verbose output - -c, --cwd Working directory - --config Configuration directory (default: ~/.cline/data/settings) - --data-dir Use isolated local state at this directory path (default: ~/.cline) - --thinking Set reasoning effort level between none|low|medium|high|xhigh (default: medium) - --retries Maximum consecutive mistakes (retries) before halting - --hooks-dir Directory path to additional hooks for runtime hook injection (default: ~/.cline/hooks) - --acp Run in Agent Client Protocol (ACP) mode for editor integration - -i, --tui Open the terminal user interface (TUI) for interactive sessions - --id Resume an existing session by ID - -k, --key API key override for this run - -P, --provider Provider id (default: cline) - -s, --system Override the default system prompt - -z, --zen Start a session that runs in the background hub - -h, --help display help for command + -V, --version Output the version number + -p, --plan Run in plan mode + --json Output messages as JSON instead of styled text + --auto-approve Set tool auto-approval for all tools (default: true) + -c, --cwd Working directory + --thinking Set reasoning effort: none|low|medium|high|xhigh. Bare --thinking uses medium; omitted uses the level last chosen with /model, or the provider default. + --compaction Context compaction mode: agentic|basic|off (default: agentic) + -i, --tui Open the terminal user interface (TUI) for interactive sessions + --id Resume an existing session by ID + -P, --provider Provider id (default: cline) + -k, --key API key for this run, also saved as the provider's key + -m, --model Model to use for the session with the selected provider + -s, --system Override the default system prompt + -z, --zen Start a session that runs in the background hub + --retries Number of maximum consecutive mistakes (retries) before exiting (default: 3) + -t, --timeout Optional timeout in seconds (default: 0 for no timeout) + --acp Run in Agent Client Protocol (ACP) mode for editor integration + --config Configuration directory (default: ~/.cline) + --data-dir Use isolated local state at this directory path (default: ~/.cline/data) + --hooks-dir Directory path to additional hooks for runtime hook injection (default: ~/.cline/hooks) + --worktree Auto-create a detached git worktree under ~/.cline/worktrees/ and run the task there + --update Check for updates and install if available + --kanban Run the kanban app + -v, --verbose Show verbose output + -h, --help display help for command Commands: - auth [options] [provider] Authenticate a provider and configure what model is used - config [options] Show current configuration - connect [options] [adapter] Connect to an editor or IDE adapter - mcp Manage MCP servers - dev Developer tools and utilities - doctor Diagnose and fix configuration issues - history|h [options] List session history or manage saved sessions - hook Handle a hook payload from stdin - plugin Manage Cline Plugins - schedule Manage scheduled tasks - hub Manage the local hub daemon - update [options] Check for updates and install if available - version Show Cline CLI version number - kanban Launch the kanban app and exit + auth [options] [provider] Authenticate a provider and configure what model is used + config [options] Show current configuration + plugin Manage Cline Plugins + skill [args...] Manage Cline Skills via the open skills CLI (npx skills) + connect [options] [channel] Connect to an external channel + mcp Manage MCP servers + doctor Diagnose and fix configuration issues + history|h [options] List session history or manage saved sessions + hook Handle a hook payload from stdin + schedule Manage scheduled tasks + hub Manage the local hub daemon + update [options] Check for updates and install if available + version Show Cline CLI version number + kanban Run the kanban app ``` ## Global Options @@ -76,18 +82,22 @@ Commands: | `-m, --model ` | Model to use for the session with the selected provider | | `-v, --verbose` | Show verbose output | | `-c, --cwd ` | Working directory | -| `--config ` | Configuration directory (default: `~/.cline/data/settings`) | -| `--data-dir ` | Use isolated local state at this directory path (default: `~/.cline`) | -| `--thinking ` | Set reasoning effort: `none\|low\|medium\|high\|xhigh` (default `medium`) | -| `--retries ` | Maximum consecutive mistakes (retries) before halting | +| `--config ` | Configuration directory (default: `~/.cline`) | +| `--data-dir ` | Use isolated local state at this directory path (default: `~/.cline/data`) | +| `--thinking ` | 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 | +| `--compaction ` | Context compaction mode: `agentic`, `basic` or `off` (default: `agentic`) | +| `--retries ` | Maximum consecutive mistakes (retries) before exiting (default: `3`) | | `--hooks-dir ` | Directory path to additional hooks for runtime hook injection (default: `~/.cline/hooks`) | | `--acp` | Run in Agent Client Protocol (ACP) mode for [editor integration](/usage/acp) | | `-i, --tui` | Open the terminal user interface (TUI) for interactive sessions | | `--id ` | Resume an existing session by ID | -| `-k, --key ` | API key override for this run | +| `-k, --key ` | API key for this run. The CLI also saves it as the provider's key | | `-P, --provider ` | Provider id (default: `cline`) | | `-s, --system ` | Override the default system prompt | | `-z, --zen` | Start a session that runs in the background hub | +| `--worktree` | Create a detached git worktree under `~/.cline/worktrees/` and run the task there | +| `--update` | Check for updates and install if available | +| `--kanban` | Run the Kanban app | | `-h, --help` | Display help for command | ## Commands @@ -105,44 +115,64 @@ echo "prompt" | cline ### `auth [options] [provider]` -Configure authentication with an AI provider. +Configure authentication with an AI provider. Without options, `cline auth` opens an interactive setup. To set up without prompts, pass the provider, key and model: ```bash cline auth +cline auth -p anthropic -k "$ANTHROPIC_API_KEY" -m claude-sonnet-5-5 ``` -### `config [options]` +| Option | Description | +|--------|-------------| +| `-p, --provider ` | Provider ID (or pass it as the first argument) | +| `-k, --apikey ` | API key | +| `-m, --modelid ` | Model ID | +| `-b, --baseurl ` | Base URL | +| `--azure-api-version ` | Azure API version | -Show current configuration. +### `config [options] [target]` + +`cline config` opens the configuration view in your terminal. To print one part of the configuration instead, for example in a script, name a target: `workflows`, `rules`, `skills`, `agents`, `plugins`, `hooks`, `mcp` or `tools`. ```bash cline config +cline config mcp +cline config tools --json ``` -### `connect [options] [adapter]` +| Option | Description | +|--------|-------------| +| `--json` | Print the target as JSON | -Connect to messaging platforms. See [Connectors](/cli/connectors). +### `connect [options] [channel]` + +Connect Cline to a messaging channel: `telegram`, `slack`, `discord`, `gchat`, `whatsapp` or `linear`. Without a channel, `cline connect` opens a setup wizard. See [Connectors](/cli/connectors). ```bash cline connect -cline connect [adapter] +cline connect telegram -k +cline connect telegram --help # Options for one channel ``` +| Option | Description | +|--------|-------------| +| `--stop` | Stop every connector, or only the named channel's | +| `--restart` | Restart the named channel's connector. Pass the same options you started it with | + +Put `--stop` and `--restart` before the channel, as in `cline connect --stop telegram`. Options after the channel go to the channel's connector. + ### `mcp` -Manage MCP servers. See [MCP](/mcp/mcp-overview). +Manage MCP servers. `cline mcp` opens a menu in your terminal to list, add, edit, enable or disable, authorize and delete servers. See [MCP](/mcp/mcp-overview). ```bash cline mcp +cline mcp add files --yes -- npx -y @modelcontextprotocol/server-filesystem . +cline mcp add docs https://example.com/mcp --transport http --header "Authorization: Bearer TOKEN" --yes +cline mcp remove docs ``` -### `dev` - -Developer tools and utilities. - -```bash -cline dev -``` +`cline mcp add` (or `install`) saves a server: a command and its arguments after `--` for a local server, or a URL for a remote one. Without `--yes`, it opens the add wizard with those fields filled in. `cline mcp remove` (or `uninstall`) deletes a server by name. ### `doctor` @@ -150,17 +180,29 @@ Diagnose and fix configuration issues. ```bash cline doctor +cline doctor fix # Kill all running Cline processes +cline doctor log # Open the CLI log file ``` ### `history|h [options]` -List session history or manage saved sessions. +List session history or manage saved sessions. `cline history` opens a session picker in your terminal. When its output goes to a script or a file, it prints the list instead. ```bash cline history -cline h +cline history --json --limit 10 +cline history export -o session.html +cline history delete --session-id ``` +| Option or command | Description | +|--------|-------------| +| `--json` | Print the sessions as JSON | +| `--limit ` | Maximum number of sessions to show, newest first (default: `50`) | +| `export ` | Export a session as a standalone HTML file (`-o, --output ` names the file) | +| `delete --session-id ` | Delete a session from history | +| `update --session-id ` | Change a session's `--title`, `--prompt` or `--metadata ` | + ### `hook` Handle a hook payload from stdin. @@ -200,12 +242,28 @@ Manage scheduled agents. See [Scheduling](/cli/scheduling). cline schedule ``` -### `hub` +### `skill [args...]` -Manage the local hub daemon. Running `cline hub` without a subcommand prints help. +Manage skills through the open [skills CLI](https://www.npmjs.com/package/skills) (`npx skills`). `add` and `remove` install into Cline unless you pass your own `--agent`. See [Skills](/customization/skills). ```bash -cline hub +cline skill add +cline skill list +cline skill remove +``` + +### `hub` + +Manage the local hub daemon. The hub starts automatically when Cline needs it. Running `cline hub` without a subcommand prints help. + +```bash +cline hub status # Show whether the hub is running +cline hub ensure # Start the hub if it isn't running and print its URL +cline hub start # Same as ensure +cline hub stop # Stop the hub and the sessions running in it +cline hub drain # Refuse new work while accepted runs finish (--off lifts it) +cline hub upgrade # Drain the hub and restart it; does not wait for --zen or scheduled tasks +cline hub dashboard # Open the hub dashboard in a browser ``` #### `hub dashboard [options]` @@ -252,7 +310,7 @@ cline -V ### `kanban` -Launch the kanban app and exit. +Run the Kanban app. See [Kanban](/usage/kanban). ```bash cline kanban @@ -276,23 +334,29 @@ cline kanban 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. [.clineignore](/customization/clineignore#enforcing-clineignore-with-a-hook) shows a hook that blocks tool calls this way. -## JSON Output Format +## JSON Output for Agent Runs -When using `--json`, each message is a JSON object on its own line: +When you give Cline a task with `--json`, the CLI prints one JSON object per line. Every line has a `type` and a `ts` (an ISO 8601 timestamp). Other commands print their own JSON shapes: for example, `cline history --json` prints one array of sessions, and `cline config --json` prints that target's entries. ```json -{"type": "say", "text": "I'll create the file now.", "ts": 1760501486669, "say": "text"} +{"ts":"2026-10-07T04:49:43.041Z","type":"agent_event","event":{"type":"done","reason":"completed","text":"Hello!","iterations":1}} ``` -| Field | Type | Description | -|-------|------|-------------| -| `type` | `"ask"` or `"say"` | Message category | -| `text` | `string` | Message content | -| `ts` | `number` | Unix timestamp in milliseconds | -| `say` | `string` | Subtype when `type` is `"say"` | -| `ask` | `string` | Subtype when `type` is `"ask"` | -| `reasoning` | `string` | Model reasoning (if available) | -| `partial` | `boolean` | `true` while streaming | +| `type` | Description | +|--------|-------------| +| `agent_event` | An event from the agent, in `event`. `event.type` is one of the [agent events](/sdk/reference/events#agentevent): `content_start`, `content_update`, `content_end`, `iteration_start`, `iteration_end`, `usage`, `notice`, `done` or `error` | +| `hook_event` | A lifecycle hook ran (`hookEventName`, `agentId`, `taskId`) | +| `team_event` | An event from an [agent team](/cli/agent-teams), in `event` | +| `run_result` | The run finished: `finishReason`, `iterations`, `usage`, `durationMs`, `model` and the final `text`. A stopped run has `finishReason` `aborted` | +| `run_aborted` | Follows `run_result` when you or another client stopped the run (`reason`, `message`) | + +Errors, including a `--timeout` that stops the run, are printed to stderr as `{"type":"error","message":...}`. Other line types can appear, such as `run_start` with `--verbose`, so have scripts skip types they don't use. + +To print only the final answer: + +```bash +cline --json "summarize this changelog" | jq -r 'select(.type == "run_result") | .text' +``` ## Configuration Files diff --git a/docs/cli/connectors.mdx b/docs/cli/connectors.mdx index 317781d89d..7e5db3f0cc 100644 --- a/docs/cli/connectors.mdx +++ b/docs/cli/connectors.mdx @@ -250,7 +250,10 @@ cline connect linear --api-key --signing-secret --base-url cline connect --stop # Stop a specific connector -cline connect telegram --stop +cline connect --stop telegram + +# Restart a connector, with the options you started it with +cline connect --restart telegram -k ``` ## Hook Command Protocol diff --git a/docs/mcp/mcp-overview.mdx b/docs/mcp/mcp-overview.mdx index 30e67d74b4..ffaedb4e42 100644 --- a/docs/mcp/mcp-overview.mdx +++ b/docs/mcp/mcp-overview.mdx @@ -45,7 +45,7 @@ Edit your MCP config file and add either: ### CLI MCP wizard -From CLI, run: +Run this in your terminal: ```bash cline mcp @@ -58,11 +58,22 @@ The wizard supports: | List servers | Show configured servers and enabled/disabled status | | Add server | Create a new MCP server entry | | Edit server | Modify an existing server | -| Enable/Disable | Toggle a server without deleting it | +| Enable/disable server | Toggle a server without deleting it | +| Authorize OAuth | Run or rerun browser authorization for a remote server | | Delete server | Remove a server permanently | When adding a server, the CLI prompts for server name, transport type, command/args (for stdio), or URL/headers (for remote transports). +To add or remove a server from a script, skip the menu: + +```bash +cline mcp add files --yes -- npx -y @modelcontextprotocol/server-filesystem . +cline mcp add docs https://example.com/mcp --transport http --header "Authorization: Bearer TOKEN" --yes +cline mcp remove docs +``` + +Without `--yes`, `cline mcp add` opens the add wizard with those fields filled in. + ## Configuration examples ### Local server (STDIO) @@ -139,7 +150,7 @@ In MCP settings you can: MCP also works in Cline CLI. Configure servers in CLI MCP settings and use the same server definitions. -You can also list servers non-interactively: +To list servers without the wizard: ```bash cline config mcp diff --git a/docs/sdk/architecture/hub-spoke.mdx b/docs/sdk/architecture/hub-spoke.mdx index 0eb65f0fb8..743fc87661 100644 --- a/docs/sdk/architecture/hub-spoke.mdx +++ b/docs/sdk/architecture/hub-spoke.mdx @@ -123,6 +123,8 @@ cline hub start # Start the hub daemon cline hub stop # Stop it cline hub status # Check if running cline hub ensure # Start if not running, return URL +cline hub drain # Refuse new work while accepted runs finish (--off lifts it) +cline hub upgrade # Drain the hub and restart it; does not wait for --zen or scheduled tasks ``` The hub listens on `127.0.0.1:25463` by default (set `CLINE_HUB_PORT` to change the port) and logs to `~/.cline/data/logs/hub-daemon.log`. diff --git a/docs/usage/cli-overview.mdx b/docs/usage/cli-overview.mdx index a8d8ce3659..210b4334de 100644 --- a/docs/usage/cli-overview.mdx +++ b/docs/usage/cli-overview.mdx @@ -40,8 +40,8 @@ Headless is triggered when using flags like `--json`, when stdin is piped, or wh # CI/script style execution git diff | cline "review these changes" -# JSON for parsing -cline --json "summarize this changelog" | jq -r '.text' +# 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) @@ -79,13 +79,13 @@ cline --help |---|---| | `cline` | Start interactive mode or run a prompt | | `cline auth` | Authenticate and set provider/model | -| `cline config` | Open the interactive config view | +| `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` | Launch Kanban app | +| `cline kanban` | Run the Kanban app | ## Most-Used Global Flags @@ -101,7 +101,7 @@ Source of truth: [CLI Reference](/cli/cli-reference) | `--config ` | Use config directory | | `--data-dir ` | Use isolated local state | | `--json` | Output newline-delimited JSON messages | -| `--thinking ` | Set reasoning effort: `none\|low\|medium\|high\|xhigh` (default `medium`) | +| `--thinking ` | 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 ` | Set task timeout | ## Automation Patterns @@ -125,10 +125,9 @@ The CLI has no allow or deny list for shell commands. To block commands, use a ` ### Include images in tasks -```bash -cline -i "fix the layout issue shown in @./screenshot.png" +Mention an image file with `@` and the CLI attaches it to the prompt: -# or reference inline +```bash cline "fix the UI shown in @./design-mockup.png" ``` @@ -140,21 +139,7 @@ cline --timeout 600 "run full test suite" ## JSON Output Schema -When using `--json`, each line is a JSON message object. - -```json -{"type":"say","text":"I'll create the file now.","ts":1760501486669,"say":"text"} -``` - -| Field | Type | Description | -|---|---|---| -| `type` | `"ask"` or `"say"` | Message category | -| `text` | `string` | Message content | -| `ts` | `number` | Unix timestamp in milliseconds | -| `say` | `string` | Subtype when `type` is `"say"` | -| `ask` | `string` | Subtype when `type` is `"ask"` | -| `reasoning` | `string` | Optional model reasoning | -| `partial` | `boolean` | Streaming flag | +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