claude-headless-mode

```bash

# Simple prompt

claude -p "Summarize this repo"

# With file input

claude -p "Review this code" < file.py

# Pipe output

claude -p "List all functions" | grep "def "

```

| Format | Flag | Use Case |

|--------|------|----------|

| Text | --output-format text | Human-readable (default) |

| JSON | --output-format json | Single JSON result |

| Stream JSON | --output-format stream-json --verbose | Real-time streaming |

Text Output (Default)

```bash

claude -p "What is 2+2?"

# Output: 4

```

JSON Output

```bash

claude -p "What is 2+2?" --output-format json

```

Returns wrapper with metadata:

```json

{

"type": "result",

"subtype": "success",

"result": "4",

"duration_ms": 1234,

"total_cost_usd": 0.01,

"session_id": "...",

"structured_output": null

}

```

Extract just the result:

```bash

claude -p "What is 2+2?" --output-format json | jq -r '.result'

```

Stream JSON Output

```bash

claude -p "Long analysis" --output-format stream-json --verbose

```

• Streams newline-delimited JSON as execution progresses
• Shows tool calls, messages, progress in real-time
• Final line contains the result
• Requires --verbose flag

Extract final result:

```bash

claude -p "Analyze code" --output-format stream-json --verbose \

| tee /dev/stderr \

| tail -1 \

| jq -r '.result'

```

Force Claude to return data matching a specific schema:

```bash

claude -p "Extract function names from auth.py" \

--output-format json \

--json-schema '{

"type": "object",

"properties": {

"functions": { "type": "array", "items": { "type": "string" } }

},

"required": ["functions"]

}'

```

Result appears in structured_output field:

```json

{

"result": "...",

"structured_output": {

"functions": ["login", "logout", "verify_token"]

}

}

```

Schema Examples

Simple object:

```json

{

"type": "object",

"properties": {

"answer": { "type": "integer" }

},

"required": ["answer"]

}

```

Task result (success/failure):

```json

{

"type": "object",

"properties": {

"status": { "type": "string", "enum": ["success", "failure"] },

"summary": { "type": "string" },

"files_changed": { "type": "array", "items": { "type": "string" } },

"error_category": { "type": "string" },

"suggestion": { "type": "string" }

},

"required": ["status", "summary"]

}

```

Extract from schema result:

```bash

OUTPUT=$(claude -p "$PROMPT" --output-format json --json-schema "$SCHEMA")

STATUS=$(echo "$OUTPUT" | jq -r '.structured_output.status')

SUMMARY=$(echo "$OUTPUT" | jq -r '.structured_output.summary')

```

| Option | Description |

|--------|-------------|

| -p, --print | Headless mode (required) |

| --output-format | text, json, stream-json |

| --json-schema | Enforce output schema |

| --verbose | Required for stream-json |

| --model | Select model (sonnet, opus, haiku) |

| --max-turns | Limit agentic turns |

| --permission-mode | bypassPermissions, plan, etc. |

| --allowedTools | Restrict available tools |

```bash

# Skip all permission prompts (trusted environments only)

claude -p "Fix all linting errors" --permission-mode bypassPermissions

# Plan mode (read-only exploration)

claude -p "Analyze architecture" --permission-mode plan

```

CI/CD Integration

```bash

# Run tests and get structured result

RESULT=$(claude -p "Run tests and report results" \

--output-format json \

--json-schema '{"type":"object","properties":{"passed":{"type":"boolean"},"failures":{"type":"array","items":{"type":"string"}}},"required":["passed"]}')

if [ "$(echo $RESULT | jq '.structured_output.passed')" = "true" ]; then

echo "Tests passed"

else

echo "Tests failed"

exit 1

fi

```

Batch Processing

```bash

for file in src/*.py; do

claude -p "Review $file for security issues" \

--output-format json \

--json-schema '{"type":"object","properties":{"issues":{"type":"array"}},"required":["issues"]}' \

| jq ".structured_output.issues"

done

```

Fresh Context Task Execution

```bash

# Each invocation is independent (no conversation history)

claude -p "Task 1: Create migration" --output-format json

claude -p "Task 2: Add model" --output-format json

claude -p "Task 3: Write tests" --output-format json

```

Share TaskList across headless invocations using CLAUDE_CODE_TASK_LIST_ID.

Environment Variable

```bash

# All invocations share the same TaskList

export CLAUDE_CODE_TASK_LIST_ID="my-project"

claude -p "Use TaskCreate to add: Setup database"

claude -p "Use TaskCreate to add: Write migrations"

claude -p "Use TaskList to show all tasks" # Shows both tasks

```

Pattern: Orchestrator + Workers

```bash

TASK_LIST_ID="epic-$(date +%Y%m%d)"

export CLAUDE_CODE_TASK_LIST_ID="$TASK_LIST_ID"

# Orchestrator creates tasks

claude -p "Use TaskCreate for each: Task 1, Task 2, Task 3"

# Workers execute (each sees shared TaskList)

for task_id in 1 2 3; do

claude -p "Use TaskUpdate to mark task #$task_id as in_progress, implement it, then mark completed"

done

# Check final state

claude -p "Use TaskList to show status"

```

Task Tools

| Tool | Purpose |

|------|---------|

| TaskCreate | Create new task with subject, description |

| TaskList | List all tasks with status |

| TaskUpdate | Update task status (in_progress, completed) or add blockedBy |

| TaskGet | Get full details of a specific task |

Dependencies

```bash

# Task 2 depends on Task 1

claude -p "Use TaskUpdate on task #2 to set blockedBy: [1]"

```

Tasks persist to ~/.claude/tasks/ and survive session restarts.

• Each -p invocation starts fresh (no context from previous runs)
• Use --output-format json for programmatic parsing
• structured_output field contains schema-validated data
• result field contains raw text response
• Stream JSON requires --verbose flag
• Cost info available in JSON output: total_cost_usd