cline/docs/cline-cli/three-core-flows.mdx

---
title: "Headless Mode"
description: "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
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
# 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
# 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
# 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
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
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
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
export CLINE_DIR=/path/to/config
cline -y "your task"
```

**CLINE_COMMAND_PERMISSIONS** — Restrict allowed commands:
```bash
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
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
#!/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>