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

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`	Token usage update.
`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.

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"

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