Headless Mode - Cline

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 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.

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