Headless Mode

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. When you choose a JSON format, stdout carries only JSON and progress output goes to stderr.

Text (default)

Returns the agent's final response as plain text:

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

JSON

Use --json local to print exactly one JSON object when the run ends:

autohand -p "List all TypeScript files" --json local

On success, the object holds the final response in content. On failure, it holds the error in message:

{"type":"result","content":"Found 15 TypeScript files..."}
{"type":"error","message":"Command did not complete successfully."}

Stream JSON

Use --output-format stream-json, or its shorter form --json stream (--json alone does the same), to print line-delimited JSON events as the run progresses:

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

Each line is one JSON event. Event types include thinking, tool_start, tool_end, file_modified, result, and error:

{"type":"thinking","thought":"The user wants an overview of the codebase..."}
{"type":"result","content":"Here's an overview..."}

--output-format accepts only stream-json, and it cannot be combined with --json local. Parse stream output one line at a time.

Session management

Each headless run starts a new session and saves it to session history. Use these options to control that history:

# Keep this run out of session history
autohand -p "..." --ephemeral

# List saved sessions
autohand sessions

# Resume a saved session interactively
autohand resume <session-id>

# Branch from a saved session without changing its history
autohand --fork <session-id>

Model selection

Specify a model for the headless run:

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

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

Permission control

Auto-confirm risky actions

Use --yes to auto-confirm risky actions (use with caution):

autohand -p "Refactor this file" --yes

Restrict available tools

The --allowed-tools and --disallowed-tools flags control which tools the agent can use for this run. Pass a comma-separated list of tool names, or repeat the flag:

# Only offer specific tools
autohand -p "Analyze this codebase" --allowed-tools "read_file,find_grep,list_tree"

# Block specific tools
autohand -p "Summarize the open TODOs" --disallowed-tools "delete_path,run_command"

Permission modes

# Auto-confirm risky actions
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

Run budgets

Set limits so an unattended run stops on its own. When a limit is reached, the turn fails with the limit named and the command exits with status 1:

autohand -p "Fix the failing tests" --yes \
  --max-requests 40 --max-tokens 500000 --max-duration 900

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?" --json local)
echo "$result" | jq -r '.content'

Read-only analysis

Use --restricted to deny dangerous operations during a review:

autohand -p "Review this codebase for potential security issues" --restricted

Scheduled tasks with cron

Run Autohand CLI on a schedule using cron. These entries assume the cron user signed in once with autohand login:

# Daily code review at 9am
0 9 * * * cd /path/to/project && autohand -p "Review recent changes and summarize any issues" --restricted --output-format stream-json >> /var/log/autohand-review.jsonl 2>> /var/log/autohand-review.err

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

CI/CD integration

Use Autohand CLI in your CI pipeline. CI runners need --bare and the variables described in Authenticate in CI and containers:

# GitHub Actions example
- name: Generate release notes
  env:
    AUTOHAND_PROVIDER: autohandai
    AUTOHAND_API_KEY: ${{ secrets.AUTOHAND_API_KEY }}
    AUTOHAND_AI_API_KEY: ${{ secrets.AUTOHAND_API_KEY }}
  run: |
    autohand --bare -p "Generate release notes from commits since last tag" \
      --restricted \
      --json local > release-notes.json

Pipe with Unix tools

Compose Autohand CLI with other Unix tools. Piped input is read in full before the run starts, so pass a finite stream:

# Check recent log lines for anomalies
tail -n 500 app.log | autohand -p "List any errors or anomalies in these log lines"

# Translate new strings
git diff -- '*.json' | autohand -p "Translate any new English strings in this diff 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:

Use --path to set the workspace directory for a run.

Authenticate in CI and containers

A CI runner or container usually has no stored Autohand sign-in. On such a machine, autohand -p waits for a browser sign-in and the job hangs. Use an API key from Autohand Console and run the CLI with --bare.

1. Create an API key in Autohand Console and store it as a CI secret.
2. Set these variables for the job:

   Variable	Value
   AUTOHAND_PROVIDER	autohandai
   AUTOHAND_API_KEY	Your Console API key. --bare uses it for sign-in.
   AUTOHAND_AI_API_KEY	The same API key. The Autohand provider uses it for model requests.
   AUTOHAND_MODEL	Optional. fantail (default) or moa.

3. Add --bare to every autohand command in the job.

# GitHub Actions step
- name: Review changes
  env:
    AUTOHAND_PROVIDER: autohandai
    AUTOHAND_API_KEY: ${{ secrets.AUTOHAND_API_KEY }}
    AUTOHAND_AI_API_KEY: ${{ secrets.AUTOHAND_API_KEY }}
  run: |
    git diff origin/main...HEAD | autohand --bare --restricted \
      -p "Read AGENTS.md first. Review this diff for bugs and missing tests."

--bare also skips hooks, LSP, plugin sync, auto-memory, and automatic AGENTS.md loading. Skills still load. When the task depends on project instructions, ask the agent to read AGENTS.md in the prompt.

A long-lived machine where a person ran autohand login once for the runner user keeps its sign-in, so jobs on that machine do not need --bare.

If you install with AUTOHAND_INSTALL_DIR="$HOME/.local/bin", run mkdir -p "$HOME/.local/bin" first. Fresh runners do not have that directory.

Frequently asked questions