Headless CLI

aether headless runs a single prompt, streams events to stdout, and exits.

aether headless "Explain the settings loader in this project"

Invocation

aether headless [OPTIONS] [PROMPT]...

If prompt words are provided, Aether joins them with spaces. If no prompt is provided and stdin is not a TTY, Aether reads stdin, trims it, and uses that as the prompt.

git diff --staged | aether headless "Review these changes"

Agent selection

Headless mode has two ways to choose what runs:

Option	Behavior
--agent <name>	Resolve a named userInvocable agent from settings.
--model <provider:model>	Create an ad-hoc default agent using that model.

--agent and --model are mutually exclusive. If neither is provided, Aether resolves the first user-invocable agent from settings. If there are no configured agents, it falls back to Aether’s built-in default agent spec.

aether headless --agent Researcher "Find the API route definitions"

aether headless --model zai:glm-5.1 \
  "Summarize the architecture"

Use --provider for provider-specific request routing and connection overrides. For Bedrock inference profiles, keep --model as the Bedrock model ID and pass the ARN separately:

aether headless --model bedrock:anthropic.claude-sonnet-4-5-20250929-v1:0 \
  --provider bedrock.inference-profile-arn=arn:aws:bedrock:us-west-2:000000000000:application-inference-profile/000000000000 \
  "Summarize the architecture"

Flags

Flag	Type	Description
[PROMPT]...	positional	Prompt text. Reads stdin if omitted and stdin is not a TTY.
-a, --agent	string	Named agent from settings. Defaults to first user-invocable agent.
-m, --model	string	Ad-hoc model spec. Mutually exclusive with --agent.
-C, --cwd	path	Working directory. Defaults to ..
--settings-json	string	Inline settings JSON.
--settings-file	path	Settings JSON file.
--mcp-config	path	Additional MCP config file. Repeatable.
--mcp-config-json	string	Additional inline MCP config JSON. Repeatable.
--system-prompt	string	Additional system prompt text.
--output	text | pretty | json	Output format. Defaults to text.
-v, --verbose	flag	Verbose diagnostic logging to stderr.
--events	comma-separated list	Event kinds to emit. Omit to emit all.
--provider	provider.field=value	Provider override. Supports PROVIDER.url, PROVIDER.auth, and bedrock.inference-profile-arn.

--sandbox-image is a global CLI flag, so it can appear before the subcommand or in the subcommand options shown by help.

Output formats

text

Human-readable lines. Final text is printed as plain text; tool calls, tool results, errors, context usage, and other selected events are formatted as simple lines.

aether headless --output text "What does this project do?"

pretty

Pretty-printed AgentMessage JSON for humans. Each emitted event is serialized with serde_json::to_string_pretty.

aether headless --output pretty "Summarize the README"

json

Newline-delimited AgentMessage JSON. Each stdout line is one compact object with a type discriminator such as tool_call, text, or done.

aether headless --output json --events text,tool_call,tool_result,done \
  "List TODO comments"

Structured JSON output

--output json writes NDJSON to stdout: one aether_core::events::AgentMessage JSON object per line. Parse each line independently:

let event: aether_core::events::AgentMessage = serde_json::from_str(line)?;

Example lines:

{"type":"tool_call","request":{"id":"tc1","name":"bash","arguments":"{}"},"model_name":"test"}
{"type":"text","message_id":"msg1","chunk":"done","is_complete":true,"model_name":"claude"}
{"type":"done"}

Diagnostics from tracing are written to stderr. Keep stdout and stderr separate when parsing JSON output.

Event filtering

By default, headless mode emits every output event. Use --events to restrict output:

aether headless --output json --events tool_call,tool_result \
  "Refactor this module"

Available event kinds:

Event kind	Description
text	Final text chunks.
thought	Final reasoning/thought chunks.
tool_call	Tool invocation.
tool_result	Tool return value.
tool_error	Tool failure.
error	Agent-level error.
cancelled	Operation cancelled.
auto_continue	Agent auto-continuing.
retrying	Agent retrying after a failure.
model_switched	Model changed through alloying.
tool_progress	Tool execution progress.
context_compaction_started	Context compaction beginning.
context_compaction_result	Context compaction completed.
context_usage	Token usage update.
context_cleared	Context was cleared.
done	Agent run completed.

When --events is set, error events are shown only if error is explicitly listed.

MCP and settings overrides

Headless mode resolves normal Aether settings from global and project settings unless you provide --settings-file or --settings-json.

Additional MCP configs provided with --mcp-config or --mcp-config-json override the agent’s MCP source list for that run.

aether headless \
  --agent Researcher \
  --mcp-config .aether/readonly-mcp.json \
  "Map the auth flow"

Related commands

show-prompt

Print the fully assembled system prompt for debugging:

aether show-prompt --agent Researcher

show-prompt accepts --cwd, settings overrides, MCP config overrides, --system-prompt, --agent, and --sandbox-image.

eval

Run declarative eval files in Docker sandboxes. Evals execute aether headless --output json under the hood and aggregate pass/fail results.

aether eval evals/ --output json

See Evals for eval file examples, Docker requirements, and result handling.

agent

Manage project agents:

aether agent new [path]
aether agent list [path]
aether agent remove <name> [path]

See Getting Started and Settings for project scaffolding details.