Headless Mode - Autohand Docs

Basic usage

Use the -p flag to pass a prompt directly:

# Run a one-off prompt
autohand -p "Look around this repo and write a README.md documenting it"

You can also pipe input to Autohand CLI:

# Pipe input
echo "Explain this error" | autohand -p

Output formats

Autohand CLI supports three output formats in headless mode:

Text (default)

Returns the agent's response as plain text:

autohand -p "What files are in this directory?"

JSON

Returns a structured JSON response with metadata:

autohand -p "List all TypeScript files" --output-format json

Example output:

{
  "type": "result",
  "result": "Found 15 TypeScript files...",
  "session_id": "session-abc123",
  "usage": {
    "prompt_tokens": 1250,
    "completion_tokens": 89
  }
}

Stream JSON

Returns line-delimited JSON events for real-time streaming. This is useful for preventing timeouts and getting incremental progress:

autohand -p "Explain this codebase" --output-format stream-json

Each line is a JSON event:

{"type":"init","session_id":"session-...","model":"claude-sonnet","tools":[...]}
{"type":"message","messageType":"reasoning","content":"The user is asking...","seqId":1}
{"type":"message","messageType":"assistant","content":"Here's an overview...","seqId":5}
{"type":"message","messageType":"stop_reason","stopReason":"end_turn"}
{"type":"message","messageType":"usage","promptTokens":294,"completionTokens":97}
{"type":"result","subtype":"success","result":"Here's an overview...","session_id":"session-..."}

Messages are streamed at the token level with incrementing seqId.

Session management

By default, headless mode auto-resumes the last session used in the current directory (just like interactive mode). This means your session retains memory across headless runs.

# Create a new session
autohand -p "..." --new

# Use a specific session
autohand -p "..." --session <session-id>

# Resume last session (default behavior)
autohand -p "..." --resume

Model selection

Specify a model for the headless run:

autohand -p "..." --model claude-sonnet
autohand -p "..." -m gpt-4o
autohand -p "..." -m llama-3.1-70b

See Configuration for the full list of supported models and providers.

Permission control

Auto-allow all tools

Use --yes to bypass all permission prompts (use with caution):

autohand -p "Refactor this file" --yes

Restrict available tools

The --tools flag controls which tools are available to the agent:

# Only load specific tools
autohand -p "Analyze this codebase" --tools "read_file,search,list_tree"

# No tools (conversation only)
autohand -p "What do you think about this approach?" --tools ""

Permission modes

# Auto-allow edits only
autohand -p "Fix the type errors" --yes

# Read-only mode (deny all dangerous operations)
autohand -p "Review this PR" --restricted

# Preview actions without applying changes
autohand -p "What would you change?" --dry-run

Examples

Automated tasks

# Run lint and fix errors
autohand -p "Run the linter and fix any errors" --unrestricted

Structured output for scripts

Use JSON output to parse results programmatically:

result=$(autohand -p "What is the main entry point of this project?" --output-format json)
echo $result | jq '.result'

Read-only analysis

Use --tools to restrict the agent to read-only operations:

autohand -p "Review this codebase for potential security issues" --tools "read_file,search,list_tree"

Scheduled tasks with cron

Run Autohand CLI on a schedule using cron:

# Daily code review at 9am
0 9 * * * cd /path/to/project && autohand -p "Review recent changes and summarize any issues" --tools "read_file,search,list_tree" --output-format json >> /var/log/autohand-review.log 2>&1

# Weekly dependency check
0 10 * * 1 cd /path/to/project && autohand -p "Check for outdated dependencies and security vulnerabilities" --unrestricted >> /var/log/autohand-deps.log 2>&1

CI/CD integration

Use Autohand CLI in your CI pipeline:

# GitHub Actions example
- name: Generate release notes
  run: |
    autohand -p "Generate release notes from commits since last tag" \
      --tools "read_file,search" \
      --output-format json > release-notes.json

Pipe with Unix tools

Compose Autohand CLI with other Unix tools:

# Monitor logs and alert on anomalies
tail -f app.log | autohand -p "Alert me if you see any errors or anomalies"

# Translate new strings
git diff --name-only | grep "\.json$" | xargs autohand -p "Translate any new English strings to French"

# Explain git diff
git diff HEAD~1 | autohand -p "Explain what changed in this commit"

Environment variables

Configure headless mode behavior with environment variables:

Variable	Description
`AUTOHAND_MODEL`	Default model to use
`AUTOHAND_OUTPUT_FORMAT`	Default output format (text, json, stream-json)
`AUTOHAND_API_KEY`	API key for the configured provider
`AUTOHAND_WORKSPACE`	Working directory override
`AUTOHAND_CONFIG`	Path to config file

Frequently asked questions

What is headless mode in Autohand?

Headless mode runs Autohand without interactive prompts, making it suitable for CI/CD pipelines, automated scripts, and background task execution. The agent processes instructions from the --prompt flag or stdin, performs the work, and exits. No user input is required during execution.

How do I run Autohand in headless mode?

Use the --prompt flag with a task description: autohand --prompt 'fix lint errors and commit'. Combine with --yes to auto-confirm actions and --auto-commit to commit results. For CI pipelines, pipe input: echo 'update dependencies' | autohand --prompt. The exit code reflects success or failure.

Can I use headless mode in CI/CD pipelines?

Yes. Autohand headless mode is designed for CI/CD. Common uses include running code reviews on pull requests, generating release notes, fixing lint errors, translating strings, and updating documentation. Set cost limits with --max-cost and use --restricted to prevent destructive operations in automated environments.