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

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.

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.

YOLO mode (fully autonomous)

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

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

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

Controlling the mode before execution

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

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

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

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

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:

{"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:

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

cline -y "Fix the UI shown in @./design-mockup.png"

Setting a timeout

Prevent runaway tasks with --timeout:

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

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

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

#!/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:

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:

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:

# 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 *"]}'

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.

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

Interactive mode

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

CLI reference

Complete documentation for all flags and commands.