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 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 launches the agent named by the top-level agent setting (when set), otherwise 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 Microsoft Foundry, configure the resource endpoint and optionally map the catalog model to its deployment name:

aether headless --model azure-foundry:gpt-5.5 \
  --provider azure-foundry.url=https://my-resource.openai.azure.com/openai/v1 \
  --provider azure-foundry.request-model=production-coding-deployment \
  "Summarize the architecture"

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 the top-level `agent` setting if set, else the 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`	MCP config file. Repeatable. Replaces the agent’s MCP source list for the run.
`--mcp-config-json`	`string`	Inline MCP config JSON. Repeatable. Replaces the agent’s MCP source list for the run.
`--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`, `PROVIDER.request-model`, 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

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. Background MCP tasks get their own lines as they start and finish (Tool deferred ..., Background task completed ..., Background task failed ..., Background task cancelled ...).

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

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

aether headless --output pretty "Summarize the README"

Newline-delimited AgentEvent JSON. Each stdout line has a top-level category discriminator and a nested event with a type discriminator.

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

Structured JSON output

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

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

Example lines:

{"category":"tool","event":{"type":"call","request":{"id":"tc1","name":"bash","arguments":"{}"}}}
{"category":"message","event":{"type":"text","message_id":"msg1","chunk":"done","is_complete":true}}
{"category":"turn","event":{"type":"ended","outcome":{"status":"completed"}}}

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.
`auto_continue`	Agent auto-continuing.
`model_switched`	Model changed through alloying.
`tool_progress`	Tool execution progress.
`context_compaction_started`	Context compaction beginning.
`context_compaction_ended`	Context compaction finished (completed, failed, or cancelled).
`context_compaction_result`	Context compaction completed.
`context_usage`	Current context-window usage.
`session_usage`	Per-call tokens and estimated cost, plus cumulative totals.
`context_cleared`	Context was cleared.
`turn_started`	Turn processing began.
`turn_ended`	Turn completed, failed, or was cancelled.
`llm_retry_scheduled`	LLM retry backoff was scheduled.
`llm_call_started`	LLM call began, including retries.
`llm_call_ended`	LLM call completed, failed, or was cancelled.
`tool_execution_started`	Tool execution began.
`tool_definitions_updated`	Available tool definitions changed.

When --events is set, terminal outcomes are shown only if turn_ended is explicitly listed.

The process exits non-zero when the turn ends with a failed outcome, regardless of event filtering.

MCP and settings overrides

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

MCP configs provided with --mcp-config or --mcp-config-json replace the agent’s MCP source list for that run (they are not merged with the agent’s configured sources).

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

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

`generate`

Call a model directly with a single prompt and print its response. Unlike headless mode, generate runs no agent loop, no tools, and no MCP servers — it is a raw model call.

aether generate --model anthropic:claude-sonnet-4-5-20250929 --prompt "Explain traits in Rust"

Read the prompt from a file or stdin with --prompt-file -:

cat schema.json | aether generate --model zai:glm-5.1 --prompt-file -

Flag	Type	Description
`--model`	`string`	Model spec (`provider:model`). Required.
`--prompt`	`string`	Prompt text. Mutually exclusive with `--prompt-file`.
`--prompt-file`	`path` or `-`	Read the prompt from a file, or `-` for stdin. Mutually exclusive with `--prompt`.
`--system`	`string`	Optional system prompt.
`--temperature`	`number`	Sampling temperature.
`--top-p`	`number`	Nucleus sampling probability mass.
`--max-tokens`	`number`	Upper bound on generated tokens.
`--reasoning-effort`	`minimal \| low \| medium \| high \| xhigh \| max`	Reasoning effort for models that support extended thinking.
`--output`	`text \| pretty \| json`	Output format. `text` prints the raw response; `json`/`pretty` wrap it as `{ "text": "<response>", "model": "<model>" }`. Defaults to `text`.

See Getting Started and Settings for project scaffolding details.