> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/cline/cline/llms.txt
> Use this file to discover all available pages before exploring further.

# Headless mode

> Run Cline non-interactively in scripts, CI/CD pipelines, and automated workflows — with piped input, JSON output, and full autonomous execution.

Headless mode runs Cline without an interactive UI. It's designed for automation, scripting, and CI/CD pipelines where no human is present. Cline executes the task, writes output to stdout, and exits when complete.

For hands-on development with a terminal UI, see [interactive mode](/cline-cli/interactive-mode) instead.

<Note>
  **Migrating from Cline CLI 1.x?** Instance commands (`cline instance new/list/kill`) were removed in CLI 2.0. Use `cline -y "task"` for headless execution instead.
</Note>

## When headless mode activates

Cline enters headless mode automatically when any of the following conditions are met:

| Invocation                  | Trigger              |
| --------------------------- | -------------------- |
| `cline -y "task"`           | `-y`/`--yolo` flag   |
| `cline --json "task"`       | `--json` flag        |
| `cat file \| cline "task"`  | stdin is piped       |
| `cline "task" > output.txt` | stdout is redirected |

If none of these apply — for example, running `cline` or `cline "task"` in a terminal — Cline launches in [interactive mode](/cline-cli/interactive-mode).

## YOLO mode (fully autonomous)

The `-y` or `--yolo` flag enables fully autonomous operation. Cline auto-approves all actions and runs without any prompts:

```bash theme={null}
cline -y "Run the test suite and fix any failures"
```

In YOLO mode:

* All file writes, shell commands, browser actions, and MCP tool calls are approved automatically
* Output is plain text — no UI rendering
* The process exits automatically when the task completes
* Suitable for CI/CD and unattended scripts

<Warning>
  YOLO mode gives Cline full autonomy over your working directory. Always run on a clean git branch so you can revert changes if needed.
</Warning>

### Controlling the mode before execution

Use `-p` (Plan) or `-a` (Act) to control how Cline approaches the task:

```bash theme={null}
# Analyze and plan before making changes
cline -y -p "Design a REST API for user management"

# Execute immediately (Act mode is the default)
cline -y -a "Fix the typo in README.md"
```

## Piping context into Cline

Pipe file contents or command output to provide context:

```bash theme={null}
# Summarize a document
cat README.md | cline "Summarize this document"

# Review git changes
git diff | cline "Review these changes and suggest improvements"

# Analyze test failures and fix them
npm test 2>&1 | cline "Analyze these test failures and fix them"

# Review a GitHub PR
gh pr diff 123 | cline -y "Review this PR"
```

When stdin is piped, Cline automatically enters headless mode — the piped content is prepended to the task prompt as context.

## Chaining commands

Pipe Cline's output into another Cline invocation to build multi-step workflows:

```bash theme={null}
# Explain changes, then generate a commit message
git diff | cline -y "explain these changes" | cline -y "write a commit message for this"

# Generate a function, then write tests for it
cline -y "create a fibonacci function" | cline -y "write unit tests for this code"

# Combine with standard shell tools
cline -y "list all TODO comments" | grep "FIXME" | wc -l
```

## JSON output

Use `--json` to get machine-readable output, one JSON object per line:

```bash theme={null}
cline --json "List all TODO comments in the codebase" | jq '.text'
```

The `--json` flag forces headless mode automatically.

**JSON message schema:**

| Field       | Type               | Description                                                   |
| ----------- | ------------------ | ------------------------------------------------------------- |
| `type`      | `"ask"` or `"say"` | Message category                                              |
| `text`      | `string`           | Human-readable message content                                |
| `ts`        | `number`           | Unix timestamp in milliseconds                                |
| `say`       | `string`           | Subtype when `type` is `"say"` (e.g., `"text"`, `"tool"`)     |
| `ask`       | `string`           | Subtype when `type` is `"ask"` (e.g., `"tool"`, `"followup"`) |
| `reasoning` | `string`           | Model reasoning (omitted when empty)                          |
| `partial`   | `boolean`          | `true` while streaming; omitted when complete                 |

Example output:

```json theme={null}
{"type":"say","text":"I'll scan the codebase for TODO comments now.","ts":1760501486669,"say":"text"}
{"type":"say","text":"Found 12 TODO comments across 5 files.","ts":1760501490123,"say":"text"}
```

JSON output follows the same schema as task files stored in `~/.cline/data/tasks/<id>/ui_messages.json`.

## Including images

Attach one or more images to a headless task with `-i`:

```bash theme={null}
cline -y -i screenshot.png "Fix the layout issue shown in this screenshot"

# Multiple images
cline -y -i before.png -i after.png "What changed between these two screenshots?"
```

You can also reference images inline using `@`:

```bash theme={null}
cline -y "Fix the UI shown in @./design-mockup.png"
```

## Setting a timeout

Prevent runaway tasks with `--timeout`:

```bash theme={null}
# Stop after 10 minutes
cline -y --timeout 600 "Run the full test suite and fix any failures"
```

The value is in seconds. If the task doesn't complete within the timeout, Cline stops and exits with a non-zero code.

## Three core headless workflows

### Batch processing

Process multiple files or apply changes across a repository in one pass:

```bash theme={null}
# Fix all TypeScript errors in the project
cline -y "Fix all TypeScript errors in src/"

# Add JSDoc comments to all exported functions
cline -y "Add JSDoc comments to every exported function in lib/"

# Normalize import paths across the codebase
cline -y "Update all imports in src/ to use path aliases instead of relative paths"
```

### CI/CD integration

Integrate Cline into automated pipelines for code review, testing, and documentation:

```yaml theme={null}
# .github/workflows/ai-review.yml
name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: '22'

      - name: Install Cline
        run: npm install -g cline

      - name: Configure Cline
        run: cline auth -p anthropic -k ${{ secrets.ANTHROPIC_API_KEY }} -m claude-sonnet-4-5-20250929

      - name: Review PR
        run: |
          git diff origin/main...HEAD | cline -y "Review this PR for:
          - Potential bugs
          - Security issues
          - Performance concerns
          - Code style violations

          Provide a summary of findings."
```

### Scripting

Build reusable shell scripts that incorporate AI analysis:

```bash theme={null}
#!/bin/bash
# review.sh — AI-powered code review for the last commit

set -e

DIFF=$(git diff HEAD~1)

if [ -z "$DIFF" ]; then
  echo "No changes to review"
  exit 0
fi

echo "$DIFF" | cline -y --json "Review this code diff for bugs and security issues" \
  | jq -r 'select(.type == "say") | .text'
```

## Environment variables

Control Cline's behavior without interactive configuration — useful for CI/CD environments.

### `CLINE_DIR`

Override the configuration directory:

```bash theme={null}
export CLINE_DIR=/path/to/custom/config
cline -y "your task"
```

All settings, secrets, and task history are stored in this directory instead of `~/.cline/data/`. Use this to:

* Run isolated Cline instances in parallel (e.g., parallel CI jobs)
* Separate configurations for different projects or teams
* Test configuration changes without affecting your main setup

### `CLINE_COMMAND_PERMISSIONS`

Restrict which shell commands Cline can execute:

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

| Field            | Type       | Description                                                                       |
| ---------------- | ---------- | --------------------------------------------------------------------------------- |
| `allow`          | `string[]` | Glob patterns for allowed commands. If set, only matching commands are permitted. |
| `deny`           | `string[]` | Glob patterns for denied commands. Deny rules take precedence over allow.         |
| `allowRedirects` | `boolean`  | Whether to allow shell redirects (`>`, `>>`, `<`). Default: `false`.              |

Examples:

```bash theme={null}
# Allow only npm and git
export CLINE_COMMAND_PERMISSIONS='{"allow": ["npm *", "git *"]}'

# Allow dev tools, block dangerous commands
export CLINE_COMMAND_PERMISSIONS='{"allow": ["npm *", "git *", "node *"], "deny": ["rm -rf *", "sudo *"]}'
```

<Warning>
  When `allow` is set, all commands that don't match the allow patterns are denied. Use this in security-sensitive environments like shared CI runners.
</Warning>

## Common use cases

| Use case               | Command                                                          |
| ---------------------- | ---------------------------------------------------------------- |
| Code review            | `git diff \| cline -y "Review these changes"`                    |
| Fix test failures      | `cline -y "Run tests and fix any failures"`                      |
| Generate release notes | `git log --oneline v1.0..v1.1 \| cline -y "Write release notes"` |
| Fix lint errors        | `cline -y "Fix all ESLint errors in src/"`                       |
| Update dependencies    | `cline -y "Update dependencies with known vulnerabilities"`      |
| Migrate code patterns  | `cline -y "Update all deprecated React lifecycle methods"`       |
| PR automation          | `gh pr diff 123 \| cline -y "Review this PR"`                    |
| Structured output      | `cline --json "List all TODO comments" \| jq '.text'`            |

## Next steps

<CardGroup cols={2}>
  <Card title="Interactive mode" icon="terminal" href="/cline-cli/interactive-mode">
    For hands-on development with keyboard shortcuts and slash commands.
  </Card>

  <Card title="CLI reference" icon="book" href="/cline-cli/cli-reference">
    Complete documentation for all flags and commands.
  </Card>
</CardGroup>