---
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
cline --json "summarize this changelog" | jq -r '.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` | Open the interactive config view |
| `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 |

## 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` (default `medium`) |
| `-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

```bash
export CLINE_COMMAND_PERMISSIONS='{"allow": ["npm *", "git *"], "deny": ["rm -rf *", "sudo *"]}'
```

### Include images in tasks

```bash
cline -i "fix the layout issue shown in @./screenshot.png"

# or reference inline
cline "fix the UI shown in @./design-mockup.png"
```

### Set execution timeout

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

## Next Steps

- [CLI Reference](/cli/cli-reference)