opensource/cline
3
0
Fork 0
mirror of https://github.com/cline/cline.git synced 2026-10-25 10:26:36 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
d8d4077dfd98478e381ff6640029a8390945d349
cline/docs/cli/cli-reference.mdx
T
Dominic CooneyDominic CooneyHarshil MistryMarMar Labs
 0adccbdb70 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>
2026-10-07 20:38:35 +09:00

393 lines
16 KiB
Plaintext
Raw Blame History

---
title: "CLI Reference"
description: "Complete command reference for Cline CLI including all commands, flags, and configuration options."
---
```bash
cline --help # Show all commands
cline <command> --help # Show help for a specific command
```
## Synopsis
```bash
cline [options] [command] [prompt]
```
## Help Menu
This is the output of `cline --help`. Run it to see the options in your version.
```text
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.
Options:
-V, --version Output the version number
-p, --plan Run in plan mode
--json Output messages as JSON instead of styled text
--auto-approve <boolean> Set tool auto-approval for all tools (default: true)
-c, --cwd <path> Working directory
--thinking <level> 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 <mode> Context compaction mode: agentic|basic|off (default: agentic)
-i, --tui Open the terminal user interface (TUI) for interactive sessions
--id <session-id> Resume an existing session by ID
-P, --provider <id> Provider id (default: cline)
-k, --key <api-key> API key for this run, also saved as the provider's key
-m, --model <model-id> Model to use for the session with the selected provider
-s, --system <system-prompt> Override the default system prompt
-z, --zen Start a session that runs in the background hub
--retries <count> Number of maximum consecutive mistakes (retries) before exiting (default: 3)
-t, --timeout <seconds> Optional timeout in seconds (default: 0 for no timeout)
--acp Run in Agent Client Protocol (ACP) mode for editor integration
--config <path> Configuration directory (default: ~/.cline)
--data-dir <path> Use isolated local state at this directory path (default: ~/.cline/data)
--hooks-dir <path> 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
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
| Option | Description |
|--------|-------------|
| `-V, --version` | Output the version number |
| `-p, --plan` | Run in plan mode |
| `--json` | Output messages as JSON instead of styled text |
| `--auto-approve <boolean>` | Set tool auto-approval for all tools (default: `true`; in [ACP mode](/usage/acp#auto-approving-tools) the default is `false`) |
| `-t, --timeout <seconds>` | Optional timeout in seconds (default: `0` for no timeout) |
| `-m, --model <model-id>` | Model to use for the session with the selected provider |
| `-v, --verbose` | Show verbose output |
| `-c, --cwd <path>` | Working directory |
| `--config <path>` | Configuration directory (default: `~/.cline`) |
| `--data-dir <path>` | Use isolated local state at this directory path (default: `~/.cline/data`) |
| `--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 |
| `--compaction <mode>` | Context compaction mode: `agentic`, `basic` or `off` (default: `agentic`) |
| `--retries <count>` | Maximum consecutive mistakes (retries) before exiting (default: `3`) |
| `--hooks-dir <path>` | 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 <session-id>` | Resume an existing session by ID |
| `-k, --key <api-key>` | API key for this run. The CLI also saves it as the provider's key |
| `-P, --provider <id>` | Provider id (default: `cline`) |
| `-s, --system <system-prompt>` | 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
### `cline` (default)
Start a task or enter interactive mode.
```bash
cline
cline "your prompt here"
cline "Run tests and fix failures"
echo "prompt" | cline
```
### `auth [options] [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
```
| Option | Description |
|--------|-------------|
| `-p, --provider <id>` | Provider ID (or pass it as the first argument) |
| `-k, --apikey <key>` | API key |
| `-m, --modelid <id>` | Model ID |
| `-b, --baseurl <url>` | Base URL |
| `--azure-api-version <version>` | Azure API version |
### `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
```
| Option | Description |
|--------|-------------|
| `--json` | Print the target as JSON |
### `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 telegram -k <BOT-TOKEN>
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. `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
```
`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`
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. `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 history --json --limit 10
cline history export <session-id> -o session.html
cline history delete --session-id <session-id>
```
| Option or command | Description |
|--------|-------------|
| `--json` | Print the sessions as JSON |
| `--limit <count>` | Maximum number of sessions to show, newest first (default: `50`) |
| `export <session-id>` | Export a session as a standalone HTML file (`-o, --output <path>` names the file) |
| `delete --session-id <id>` | Delete a session from history |
| `update --session-id <id>` | Change a session's `--title`, `--prompt` or `--metadata <json>` |
### `hook`
Handle a hook payload from stdin.
```bash
cat payload.json | cline hook
```
### `plugin`
Manage Cline plugins. Install plugins from file URLs, npm, git repositories, or local paths. See [Plugins](/customization/plugins) for full details and the plugin manifest format.
```bash
cline plugin install <source> # Install a plugin
cline plugin i <source> # Shorthand alias
```
| Option | Description |
|--------|-------------|
| `--npm` | Treat source as an npm package |
| `--git` | Treat source as a git repository |
| `--force` | Replace an existing install for the same source |
| `--json` | Output result as JSON |
| `--cwd <path>` | Install to `<path>/.cline/plugins` instead of the global directory |
Try it with the [TypeScript Navigation Plugin](https://github.com/cline/typescript-lsp-plugin):
```bash
cline plugin install https://github.com/cline/typescript-lsp-plugin.git
```
### `schedule`
Manage scheduled agents. See [Scheduling](/cli/scheduling).
```bash
cline schedule
```
### `skill [args...]`
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 skill add <owner/repo>
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]`
Start the Cline Hub browser dashboard to view connected clients and sessions, send messages, and restart the hub. The command opens your default browser and stays running until you press Ctrl+C.
```bash
cline hub dashboard
cline hub dashboard --port 9090 --no-open
cline hub dashboard --help
```
| Option | Description |
| --- | --- |
| `-c, --cwd <path>` | Workspace root (default: current directory). |
| `--config <dir>` | Configuration directory. |
| `--data-dir <dir>` | Use isolated local state and enable sandbox mode. |
| `--host <host>` | Dashboard bind host (default: `127.0.0.1`). |
| `--port <port>` | Dashboard HTTP/WebSocket port (default: `8787`). |
| `--public-url <url>` | Public dashboard URL for LAN or tunnel access. |
| `--room-secret <secret>` | Invite secret for browser access; required when binding to a non-local host. |
| `--no-open` | Print the dashboard URL without opening a browser. |
Anyone with access to the dashboard can drive sessions and restart the hub. For LAN or tunnel access, use a strong room secret and share the printed invite URL only with trusted people.
The old `cline dashboard` invocation remains a hidden compatibility alias. Use `cline hub dashboard` in new scripts.
### `update [options]`
Check for updates and install if available.
```bash
cline update
```
### `version`
Show Cline CLI version number.
```bash
cline version
cline -V
```
### `kanban`
Run the Kanban app. See [Kanban](/usage/kanban).
```bash
cline kanban
```
## Environment Variables
| Variable | Description |
|----------|-------------|
| `CLINE_DIR` | Custom configuration directory (replaces `~/.cline/`), like `--config` |
| `CLINE_DATA_DIR` | Custom data directory (replaces `~/.cline/data/`) |
| `CLINE_HUB_PORT` | Port of the local hub (default: `25463`) |
| `CLINE_HUB_ADDRESS` | Hub address for `cline schedule` commands, like their `--address` option |
| `CLINE_SESSION_BACKEND_MODE` | Force backend mode (`local`, `hub`, `remote`, `auto`) |
| `CLINE_SANDBOX_DATA_DIR` | Sandbox session storage directory |
| `CLINE_SANDBOX` | Enable sandbox mode |
| `CLINE_HOOKS_DIR` | Additional hooks directory |
| `CLINE_LOG_PATH` | CLI log file (default: `~/.cline/data/logs/cline.log`). `cline doctor log` opens it |
| `CLINE_BUILD_ENV` | Set to `development` for debug features |
| `CLINE_DEBUG_PORT_BASE` | Base port for Node.js inspector |
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 for Agent Runs
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 <target> --json` prints that target's entries.
```json
{"ts":"2026-10-07T04:49:43.041Z","type":"agent_event","event":{"type":"done","reason":"completed","text":"Hello!","iterations":1}}
```
| `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
```
~/.cline/
data/
settings/
providers.json # API keys and provider config
global-settings.json # Global settings
cline_mcp_settings.json # MCP server config (override with CLINE_MCP_SETTINGS_PATH)
teams/ # Team state
sessions/ # One folder of messages per session
db/
sessions.db # Session index (SQLite)
logs/
cline.log # CLI log (open with `cline doctor log`)
hub-daemon.log # Hub logs
rules/ # Global rules
skills/ # Global skills
hooks/ # Global hooks
agents/ # Global agent definitions
plugins/ # Global plugins
_installed/ # Managed by `cline plugin install`
.cline/ # Project root
rules/ # Project rules
skills/ # Project skills
hooks/ # Lifecycle hooks
agents/ # Project agent definitions
plugins/ # Project plugins
```
[Config](/getting-started/config#configuration-directory-layout) lists every location Cline reads.
Reference in New Issue View Git Blame Copy Permalink