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

# Headless Mode

> Run Cline autonomously in scripts, CI/CD pipelines, and automated workflows

Headless mode runs Cline without an interactive interface — perfect for automation, scripting, and CI/CD pipelines where human interaction isn't possible or desired. Cline executes tasks, produces clean text or JSON output, and exits when complete.

For collaborative, conversational development, see [Interactive Mode](/cline-cli/interactive-mode) instead.

<Note>
  **Migrating from an older CLI version?** Instance commands (`cline instance new/list/kill`) have been removed in Cline CLI 2.0. The new architecture is simpler — just use `cline -y "task"` for headless execution.
</Note>

## When Headless Mode Activates

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

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

If none of these apply (e.g., 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 approves all actions and runs without prompts:

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

In YOLO mode:

* All actions are auto-approved
* Output is plain text (non-interactive)
* Process exits automatically when complete
* Perfect for CI/CD and scripts

<Warning>
  YOLO mode gives Cline full autonomy. Run on a clean git branch so you can easily revert changes if needed.
</Warning>

### Mode Selection

Control whether Cline plans first or acts immediately:

```bash theme={"system"}
# Start in Plan mode (analyze before acting)
cline -y -p "Design a REST API for user management"

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

## Piping Context

Pipe file contents or command output into Cline to provide context:

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

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

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

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

When stdin is piped, Cline automatically enters headless mode — the piped content becomes part of the task context.

## Chaining Commands

Pipe Cline's output into another Cline instance for multi-step workflows:

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

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

# Fun: Generate a poem about your code
git diff | cline -y "explain" | cline -y "write a haiku about this"
```

## JSON Output

Use `--json` for machine-readable output that's easy to parse in scripts:

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

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

**JSON Message Schema:**

| Field       | Type               | Description                |
| ----------- | ------------------ | -------------------------- |
| `type`      | `"ask"` or `"say"` | Message category           |
| `text`      | `string`           | Message content            |
| `ts`        | `number`           | Unix timestamp (ms)        |
| `reasoning` | `string`           | (Optional) Model reasoning |
| `partial`   | `boolean`          | (Optional) Streaming flag  |

## Including Images

Attach images to your headless task:

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

# Or reference inline
cline -y "Fix the UI shown in @./design-mockup.png"
```

## Timeout Control

Set a maximum execution time to prevent runaway tasks:

```bash theme={"system"}
cline -y --timeout 600 "Run full test suite"
```

## Environment Variables

Control Cline behavior via environment variables — useful for CI/CD where you can't use interactive configuration.

**CLINE\_DIR** — Custom configuration directory:

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

**CLINE\_COMMAND\_PERMISSIONS** — Restrict allowed commands:

```bash theme={"system"}
export CLINE_COMMAND_PERMISSIONS='{"allow": ["npm *", "git *"], "deny": ["rm -rf *"]}'
cline -y "your task"
```

See [Configuration](/cline-cli/configuration#environment-variables) for full documentation.

## CI/CD Integration

### GitHub Actions Example

Automate PR reviews with Cline:

```yaml theme={"system"}
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 }}
      
      - 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."
```

### Shell Script Example

Create a reusable code review script:

```bash theme={"system"}
#!/bin/bash
# review.sh - AI-powered code review

set -e

# Get the diff
DIFF=$(git diff HEAD~1)

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

# Run Cline review
echo "$DIFF" | cline -y --json "Review this code diff for issues" | jq -r '.text'
```

## Common Use Cases

| Use Case               | Example                                                          |
| ---------------------- | ---------------------------------------------------------------- |
| 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"`                    |
| Batch processing       | `cline -y --json "List all TODO comments" \| jq '.text'`         |

## Next Steps

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

  <Card title="CLI Reference" icon="book" href="/cline-cli/cli-reference">
    Complete command documentation with all flags and options.
  </Card>

  <Card title="Configuration" icon="gear" href="/cline-cli/configuration">
    Environment variables, rules, and advanced settings.
  </Card>

  <Card title="CLI Samples" icon="flask" href="/cline-cli/samples/overview">
    Real-world examples of headless workflows and automation patterns.
  </Card>
</Columns>