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 <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>

apps/cli/README.md

@@ -250,7 +250,7 @@ Schedules can route results back to chat surfaces with `--delivery-adapter`, `--
 | `-s, --system <prompt>` | Override the system prompt |
 | `-P, --provider <id>` | Provider id (default: `cline`) |
 | `-m, --model <id>` | Model id (default: `anthropic/claude-sonnet-4.6`) |
-| `-k, --key <api-key>` | API key override for this run |
+| `-k, --key <api-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 <seconds>` | Optional run timeout in seconds |
@@ -258,7 +258,7 @@ Schedules can route results back to chat surfaces with `--delivery-adapter`, `--
 | `--config <path>` | Configuration directory (used for CLI home resolution) |
 | `--hooks-dir <path>` | 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 <agentic\|basic\|off>` | Context compaction mode. Defaults to `agentic`; use `basic` for local truncation or `off` to disable. |
 | `--retries <count>` | Maximum consecutive mistakes (retries) before halting (default: `3`) |
 | `--json` | Output NDJSON instead of styled text |

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);
 

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 <count>", "Maximum number of sessions to show", "50")
-		.option("--page <number>", "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 <number>").hideHelp())
 		.option("--config <dir>", "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()) {

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 <seconds>",

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/,
+		);
+	});
 });

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 <path>", "Working directory")
 			.option(
 				"--thinking <level>",
-				"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 <mode>", CLI_COMPACTION_MODE_OPTION_DESCRIPTION)
 			.option(
@@ -46,7 +47,10 @@ export function addRootOptions(cmd: Command): Command {
 			)
 			.option("--id <session-id>", "Resume an existing session by ID")
 			.option("-P, --provider <id>", "Provider id (default: cline)")
-			.option("-k, --key <api-key>", "API key override for this run")
+			.option(
+				"-k, --key <api-key>",
+				"API key for this run, also saved as the provider's key",
+			)
 			.option(
 				"-m, --model <model-id>",
 				"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 <count>",
+				`Number of maximum consecutive mistakes (retries) before exiting (default: ${CLI_DEFAULT_MAX_CONSECUTIVE_MISTAKES})`,
 			)
 			.option(
 				"-t, --timeout <seconds>",

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<void> {
 				mode: effectiveMode,
 			}),
 			execution: {
-				maxConsecutiveMistakes: args.retries ?? 3,
+				maxConsecutiveMistakes:
+					args.retries ?? CLI_DEFAULT_MAX_CONSECUTIVE_MISTAKES,
 			},
 			checkpoint: CLI_DEFAULT_CHECKPOINT_CONFIG,
 			compaction: buildCliCompactionConfig(effectiveCompactionMode),

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);

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);
 	});
 });

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");
 	});
 });

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"]);
 	});
 });