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

Redirected stdout is headless-only. Plain ante > out.txt with no prompt refuses to start, because the TUI draws to stdout and boots by asking the terminal where the cursor is. Pass a prompt, or pipe one in, to capture output to a file.

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)
--profile <NAME>	Process-wide selection of an existing ~/.ante/<name>.settings.json; ANTE_PROFILE is equivalent, an unknown name falls back to settings.json, and the built-in bare profile disables ambient features, skills, MCP servers, session saving, and auto-memory
--effort <LEVEL>	Override the model's effort level: min, low, medium, high, xhigh, or max
--yolo	Use yolo permission mode, auto-approving tool calls
--permission-mode <MODE>	Use strict, auto, or yolo. Headless defaults to yolo; under strict or auto, a call that would require an interactive approval is denied immediately instead of pausing forever
--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 shorter built-in tool descriptions; the system instructions are already compact and stay the same
--skills / --no-skills	Load or skip skill discovery, overriding the skills setting. With --no-skills, no skills are advertised or invocable
--include-skills <SKILLS>	Add exact skill names for this run, replacing the include_skills setting. Use a comma-separated value or repeat the flag
--exclude-skills <SKILLS>	Remove exact skill names for this run, replacing the exclude_skills setting. Use a comma-separated value or repeat the flag; exclusions win
--enable-auto-memory / --disable-auto-memory	Turn auto-memory on or off, overriding the auto_memory setting (headless default: off)
--tools <TOOLS>	Replace the default tool set with exactly these tools. Use a comma-separated value or repeat the flag; the removed --allowed-tools name is rejected
--include-tools <TOOLS>	Add tools on top of the default set, or on top of the --tools base set. Use a comma-separated value or repeat the flag
--exclude-tools <TOOLS>	Remove tools after --tools and --include-tools are applied. Use a comma-separated value or repeat the flag; the deprecated --disallowed-tools alias remains accepted
-r, --resume <SESSION_ID>	Resume a previously saved session by its ID
--session-save / --no-session-save	Save or skip session persistence, overriding the session_save setting. With --no-session-save, no transcript or resumable snapshot is written; conflicts with --resume
--check	Run a verification pass after the main task completes
--offline-model [MODEL]	Load a local or verified model through llama serve, use the local provider, and shut the router down on exit. Accepts a path, discovered filename, or verified model name/URL; omit the value for the saved default. Conflicts with --model and --provider

A resumed headless session keeps its saved system prompts and prompt mode; prompt flags affect fresh sessions only. Model calls use the same streaming transport and idle timeout as the TUI, even when the selected output format shows only completed messages.

Output formats

Minimal (default)

Shows only agent messages, info, and errors:

ante -p "what does this project do"

Human

Shows readable blocks for messages, tool activity, and turn status. ANSI styling is used only on a terminal and is disabled by a nonempty NO_COLOR:

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
• Unattended policy is explicit — The default is yolo. An explicit --permission-mode strict or auto is honored, but any call that would need a prompt is denied at admission because no one can answer it
• The default prompt describes a single unattended turn — It tells the model that no one can answer questions or send another message and that the session ends with the turn. Include the required inputs and output format in your initial prompt
• 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 saved model, provider, effort, and dialog are restored; settings the snapshot did not pin resolve from the host's current defaults. Headless resume does not need the current default provider to match the session's provider. Explicit --provider and --model flags override the saved selection before the new prompt runs, so you can continue on another connected provider.

Since v0.3.1, tool filters also apply on resume. --tools replaces the base set, --include-tools adds to it, and --exclude-tools wins over both. Without --tools, the base set comes from the current tools setting or the default tool set:

ante --resume ses_01ARZ3NDEKTSV4RRFFQ69G5FAV \
  --tools Read,Glob,Grep \
  -p "review the previous changes without editing files"

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.

Headless mode requires a session ID: bare --resume is only available in the interactive TUI and returns an error when combined with -p or piped input.

Examples

CI: lint and fix

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

Code generation

ante --model claude-sonnet-5-5 --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"