Headless CLI

The headless CLI runs a single prompt and exits — ideal for scripting, CI pipelines, and automation.

aether headless "Explain the main function in this project"

Flags

Flag	Type	Default	Description
[PROMPT]...	positional	—	Prompt text (joined with spaces)
-m, --model	string	—	Model spec (e.g., anthropic:claude-sonnet-4-5)
-a, --agent	string	—	Named agent from settings.json
-C, --cwd	path	.	Working directory
--mcp-config	path	—	Path to MCP config file
--system-prompt	string	—	Additional system prompt text
--output	string	text	Output format: text, pretty, json
-v, --verbose	flag	—	Verbose logging to stderr
--events	string	—	Comma-separated event filter (e.g. tool_call,tool_result). Omit to emit all.

Note

--model and --agent are mutually exclusive. If neither is set, Aether uses the first userInvocable agent from settings.json.

Output formats

text

Plain text output — just the agent’s response.

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

pretty

Formatted output with markdown rendering.

aether headless --output pretty "Summarize the README"

json

Structured JSON output — useful for piping into other tools.

aether headless --output json "List all TODO comments" | jq '.response'

Event filtering

By default, headless mode emits all event types. Use --events to restrict output to specific event kinds:

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

Available event kinds:

Event kind	Description
text	Final text output
thought	Extended thinking / reasoning
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
model_switched	Model changed (alloying)
tool_progress	Tool execution progress
context_compaction_started	Compaction beginning
context_compaction_result	Compaction completed
context_usage	Token usage update
context_cleared	Context was cleared

Note

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

Reading from stdin

If no prompt is given and stdin is not a TTY, Aether reads the prompt from stdin:

echo "Explain this code" | aether headless

cat error.log | aether headless "What went wrong?"

This is useful for piping file contents or command output into Aether.

Examples

Quick question with a specific model

aether headless -m anthropic:claude-sonnet-4-5 "What does the Config struct do?"

Using a named agent

aether headless -a researcher "Find all API endpoints in this project"

CI pipeline

aether headless \
  -m anthropic:claude-haiku-4-5 \
  --output json \
  "Review the staged changes and list any issues" \
  > review.json

Different working directory

aether headless -C /path/to/project "Summarize the architecture"

Other subcommands

show-prompt

Print the fully assembled system prompt (useful for debugging):

aether show-prompt
aether show-prompt --agent researcher

Flag	Type	Default	Description
-C, --cwd	path	.	Working directory
--mcp-config	path	—	Path to MCP config file (repeatable)
--system-prompt	string	—	Additional system prompt text
-a, --agent	string	—	Named agent to inspect

agent new

Initialize a new Aether project:

aether agent new [path]

See Getting Started for details.

agent list

List all agents in the project:

aether agent list [path]

agent remove

Remove an agent from the project:

aether agent remove <name> [path]