Headless Mode

Headless mode runs Ante without the TUI — it processes a prompt, executes the task, and exits. This is ideal for scripting, CI/CD pipelines, and automated workflows.

Basic usage

Use the -p / --prompt flag to pass a prompt:

ante -p "explain what this project does"

Or with the long form:

ante --prompt "add tests for the auth module"

Stdin input

Pipe content from stdin:

cat src/main.rs | ante -p "review this code for bugs"

Combine stdin with a prompt:

echo "function add(a, b) { return a + b }" | ante -p "add TypeScript types"

When both stdin and a prompt argument are provided, they are concatenated (stdin first, then the prompt).

CLI reference

ante [OPTIONS] [--prompt <PROMPT>]

Flag	Description
-p, --prompt <PROMPT>	The prompt to run
-m, --model <MODEL>	Override the model name
--provider <PROVIDER>	Override the API provider (e.g. anthropic, openai, gemini, xai, openrouter, local)
--effort <LEVEL>	Override the model's effort level: min, low, medium, high, xhigh, or max
--yolo	Skip all tool approval prompts
--permission-mode <MODE>	Accepted for CLI compatibility, but headless runs always use yolo because there is no interactive approval prompt
--output-format <FORMAT>	Output format: json, human, minimal (default: minimal)
--system-prompt <PROMPT>	Replace the default system prompt entirely. Conflicts with --system-prompt-file
--system-prompt-file <PATH>	Read the replacement system prompt from a UTF-8 file. Conflicts with --system-prompt
--append-system-prompt <TEXT>	Append text to the system prompt
--short-prompt	Use the compact prompt set: a condensed system prompt and shorter built-in tool descriptions
--tools <TOOLS>...	Replace the default tool set with exactly these tools. Deprecated alias: --allowed-tools still works but prints a warning
--include-tools <TOOLS>...	Add tools on top of the default set, or on top of the --tools base set
--exclude-tools <TOOLS>...	Remove tools after --tools and --include-tools are applied. Deprecated alias: --disallowed-tools still works but prints a warning
-r, --resume <SESSION_ID>	Resume a previously saved session by its ID
--no-session-save	Skip session persistence — no transcript or resumable snapshot is written. Conflicts with --resume
--check	Run a verification pass after the main task completes
--offline-model <PATH>	Path to a local GGUF file. Boots a local llama-server, points the session at the local provider, and tears it down on exit

Output formats

Minimal (default)

Shows only agent messages, info, and errors:

ante -p "what does this project do"

Human

Shows all events in a human-readable format with ANSI colors:

ante --output-format human -p "fix the type error in main.rs"

JSON

Outputs every event as a JSON object (one per line), suitable for machine consumption:

ante --output-format json -p "list all TODO comments" | jq '.event'

Verification check

The --check flag runs a second pass after the main task, asking the agent to review its own work:

ante --check -p "refactor the auth module to use async/await"

The verification pass will:

1. Review what was accomplished against the original request
2. Complete anything missing or incomplete
3. Optimize where possible without affecting correctness

Context enrichment

In headless mode, Ante automatically appends the current directory's folder structure to your prompt. This gives the agent awareness of the project layout without you needing to describe it.

Headless behavior notes

• Raw streaming deltas are suppressed — Output shows complete messages, not the incremental chunks, so logs stay clean
• Yolo policy is implied — All tool calls are auto-approved (no interactive prompts), regardless of --permission-mode
• Authentication is checked eagerly — If the provider isn't authenticated, Ante exits immediately with an error
• Fails fast if the daemon dies — If the agent process exits before finishing the task, Ante reports an error instead of a success exit code

Resuming a session

Pass --resume <SESSION_ID> to continue a previously saved session. Ante replays the persisted history, then applies the new prompt as the next turn:

ante --resume ses_01ARZ3NDEKTSV4RRFFQ69G5FAV -p "now add tests"

The session ID is printed when a TUI session exits (Resume this session with: ante --resume ses_...).

Sessions started with --no-session-save are never persisted, so they cannot be resumed later.

Examples

CI: lint and fix

ante --yolo -p "run cargo clippy and fix all warnings"

Code generation

ante --model claude-sonnet-4-6 --check \
  -p "add comprehensive unit tests for src/core/session.rs"

Restricted tools

# Read-only analysis — no file writes or shell access
ante --tools Read Glob Grep \
  -p "analyze the codebase architecture and summarize it"

Pipe a diff for review

git diff HEAD~1 | ante -p "review this diff for bugs and security issues"