Skip to main content
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.
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.

​
When Headless Mode Activates

Cline automatically enters headless mode when any of these conditions are met:
InvocationReason
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.txtstdout 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: 
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
YOLO mode gives Cline full autonomy. Run on a clean git branch so you can easily revert changes if needed.

​
Mode Selection

Control whether Cline plans first or acts immediately: 
# 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: 
# 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: 
# 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: 
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:
FieldTypeDescription
type"ask" or "say"Message category
textstringMessage content
tsnumberUnix timestamp (ms)
reasoningstring(Optional) Model reasoning
partialboolean(Optional) Streaming flag

​
Including Images

Attach images to your headless task: 
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: 
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: 
export CLINE_DIR=/path/to/config
cline -y "your task"
CLINE_COMMAND_PERMISSIONS — Restrict allowed commands: 
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: 
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: 
#!/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 CaseExample
Code reviewgit diff | cline -y "Review these changes"
Fix test failurescline -y "Run tests and fix any failures"
Generate release notesgit log --oneline v1.0..v1.1 | cline -y "Write release notes"
Fix lint errorscline -y "Fix all ESLint errors in src/"
Update dependenciescline -y "Update dependencies with known vulnerabilities"
Migrate code patternscline -y "Update all deprecated React lifecycle methods"
PR automationgh pr diff 123 | cline -y "Review this PR"
Batch processingcline -y --json "List all TODO comments" | jq '.text'

​
Next Steps

Interactive Mode

For hands-on development with keyboard shortcuts, slash commands, and file mentions.

CLI Reference

Complete command documentation with all flags and options.

Configuration

Environment variables, rules, and advanced settings.

CLI Samples

Real-world examples of headless workflows and automation patterns.