Skip to content

COMMANDS.md

Latest commit

 

History

History
824 lines (690 loc) · 45.5 KB

COMMANDS.md

File metadata and controls

824 lines (690 loc) · 45.5 KB
Raw

Aether Agent — Command Reference

Complete reference for every command, flag, slash command, and environment variable. For a quick tour, see the README.

The complete manifest-derived reference is docs/generated/commands.md. Regenerate it with npm run docs:generate; verify drift with npm run docs:check.

aether [global flags] <command> [args]
aether [global flags] "<prompt>"        # bare prompt = one-shot chat
aether                                  # no args = interactive REPL

Registry indexes

help, agent, chat, resume, run, models, agents, auth, github, vault, workflow, memory, skills, capabilities, image, video, output, pc, audit, receipt, support-bundle, mcp, config, exec, setup, local, preview, doctor, sessions, review, ship, settings, voice

help, auth, models, model, switch, agent, agents, tier, effort, audit, doctor, settings, voice, preview, clear, exit, mcp, autonomous-execution, subagent-driven-execution, self-review, recon, skill, plan, research, project-review, code-review, writing-skills, writing-plans, shell-profile, shell-result, shell-reset, terminal, terminal-attach, terminal-stop, terminal-status, queue, steer, btw, pin, drop, context, snapshot, limit, audit-receipt, rollback, logs-view, goal, goals, memory, workflow, workflow-templates, workflow-template, vault, vault-context, vault-search, vault-recent, vault-project, vault-tag, vault-tree, delegate, tree, broadcast, gather, scaffold, port, test-drive, bench, purge, stage-diff, review, ship, revert, photogen, frame, re-frame, videogen, sequence, animate, re-cut, output, storyboard, add, hud, agent-create, browser, ats

Runtime capability requirements

These identifiers are the public capability requirements referenced by command metadata. Their release treatment is recorded independently in the release notes.

  • aether.catalogue — live model and agent catalogue access.
  • aether.hosted — an authenticated hosted Aether runtime.
  • aether.hosted-or-local — either the hosted runtime or the packaged local fallback.
  • aether.local-child — local child-process brain authority; never a remote shell.
  • aether.headless.v1 — versioned aether.exec/1 JSONL events and controls.
  • aether.headless.v2 — durable, repository-bound headless sessions with acknowledged controls.
  • aether.local-preview — consent-gated local dev-server supervision and loopback opening.
  • ollama.local — a user-operated Ollama endpoint and optional local CLI binary.

Global flags

These apply to any command (parsed anywhere on the line).

Flag Type Meaning
--model <id> string Force a model for this run (e.g. --model opus).
--agent <id> string Force an orchestrator (neo, kronus).
--cwd <dir> string Workspace directory for file context + edits (default: current dir).
--json bool Emit raw stream frames as JSON lines (machine mode).
--audit bool Print the chain-of-custody id inline after a turn.
-y, --yes bool Auto-confirm prompts (non-interactive).
-h, --help bool Print help and exit.
-v, --version bool Print version and exit.

Commands

aether — interactive REPL

Opens a session. Type a prompt to chat; type / commands to control it (see Slash commands). Up-arrow recalls submitted prompts from this workspace (stored under ~/.aether-agent/history.d/). Ctrl-C mid-answer cancels the turn and keeps the session; Ctrl-C at an empty prompt (or /exit) leaves.

In a raw TTY, Enter (CR) submits and Ctrl+J (LF) inserts a newline into the same draft. The composer stays on one row: ⏎ marks each newline and [nL] shows the line count. Ctrl+_ undoes recent edits (adjacent typing groups into one step; a bracketed paste is one step). Ctrl+Y restores the last text killed with Ctrl+K, Ctrl+U, or Ctrl+W. Submitting or clearing a draft ends its undo and yank history. Non-TTY input stays line-oriented.

Ctrl+R searches this workspace's loaded prompt history. An empty query selects the newest entry; type to narrow the matches and press Ctrl+R again to move older without wrapping. The panel shows the query, selected prompt, and a no-match state. Enter inserts the complete stored prompt for editing without sending it; Escape restores the exact prior draft and cursor. Search examines at most 1,000 loaded entries, 16 KiB per entry and 1 MiB total per query update. Oversized or over-budget entries are skipped and counted; displayed matches are clipped to 512 characters and terminal width without clipping the prompt inserted on Enter. AETHER_NO_HISTORY=1 disables loading and saving history. Stored prompts are not automatically filtered for secrets. Shell commands, tool output, and approval feedback are not added to prompt history. Search is available only when the idle raw composer owns input.

Some terminals send LF for Enter as well as Ctrl+J, so those two keys cannot be distinguished there. Use aether config set lfSubmits true to make LF submit for compatibility; aether config set lfSubmits false restores Ctrl+J newline entry. This setting affects only the raw TTY composer.

Typing / at the start of an idle raw TTY draft opens a bounded command picker. Rows show canonical names, argument hints, and descriptions from the command manifest; commands owned by managed agent chat are omitted. Up/Down or Tab changes the selection. Enter inserts the selected command into the editable draft; press Enter again to run it. Escape restores the draft and cursor from before the picker opened. With no match, Enter dismisses the picker and keeps the literal slash text for a later explicit submission. Pasted text, ongoing turns, and non-TTY input do not open the picker. Tab can also open it for an existing leading slash draft with arguments, preserving the suffix and caret.

aether "<prompt>" — one-shot

Runs a single turn against your default (or --model) and streams the answer. aether chat "<prompt>" is the explicit form — it bypasses command matching, so a prompt that happens to look like a command still chats.

aether "explain what src/router.ts does"
aether --model opus "rewrite this function to be O(n)"

A lone near-miss token is treated as a typo, not a prompt. Expected typo example: aether auht suggests aether auth and exits 2 before any hosted request. Use aether chat auht to send that exact text as a prompt intentionally.

aether code "<task>" — autonomous coding agent

One host loop drives a pluggable brain: cloud (UVT-metered) by default, --local for the built-in Ollama brain. The host renders every event, executes every tool call locally, and verifies the result itself — the final status is derived from your test command's exit code, never the brain's self-report. Every run ends with a verdict line: ✓ ok · 4 files changed · tests green · 3m12s. The line is rendered from how the turn ended plus what the check actually did. Only a check that ran to completion and exited non-zero reads as failing (2 tests failing, or check failed (exit 2) when no count can be parsed). A run that is cancelled, times out, hits the model output limit, is refused, or loses its connection names that reason and says verification not run; a check that itself times out or is cancelled says so instead of reporting a red run. With --json, the final turn_outcome record carries the same reading under verification (state, exit_code, failing, reason), and so does the session manifest. In a git checkout, a completed check is also recorded for aether review, bound to the tree it ran against.

Flag Meaning
--local Use the built-in offline Ollama brain instead of the cloud.
--resume <id|file> Continue a prior session id, or a handoff file from another machine.
--pool <gb> Context pool size in GB (status-bar reach = pool × 233M tokens).
--effort <t> Effort tier: LOW | MED | HIGH | MAX | ULTRA | CODEPRO (overrides the saved /effort dial).
--test-cmd <c> Command the verification gate runs (unverified without it).
--prompt-file <path|-> Read one UTF-8 coding task from a file or stdin through EOF (maximum 256 KiB).
--quiet Plain output (strip the personality frames).
--interactive Pause at each stage boundary to type a steer (TTY only).
--no-log Disable the local session log (~/.aether-agent/logs).
--swarm <N> N-agent swarm (gated; local-only; refuses at runtime — see commands/code.ts).
--skill <id> Load this skill for the run (id, short name, or command alias) and apply its tool policy — the host refuses any tool the skill does not declare.
--no-skills Load no skill. The project's own AGENTS.md still applies — it is not a skill.

For a multiline specification, put the complete task in task.md and run:

aether agent --prompt-file task.md --test-cmd "npm test"
cat task.md | aether agent --prompt-file - --test-cmd "npm test"

PowerShell: Get-Content -Raw task.md | aether agent --prompt-file -. Input is read once, kept literal (including newlines, /, !, backticks, and $()), and sent as one coding task. The 256 KiB cap is measured in UTF-8 bytes; oversized, invalid UTF-8, missing, unreadable, or blank input exits before a model or session starts. A failed read never opens the line REPL. The session manifest and JSON prompt_input event record source and byte size, not the task body. Explicit session sharing continues to use its existing controls.

Combination with --prompt-file Result
Positional task or managed-agent verb Refused: one explicit source only.
--resume Refused: continuation and a new file task have different ownership.
--interactive Refused: stage steering may need stdin.
--with-token Refused: it also consumes stdin.
--test-cmd, --local, --skill, --no-skills, --worktree, --repo, --yes Supported; normal coding routing, permissions, and verification apply.

Before the run starts, the agent prints what it loaded and what it will enforce:

Project   my-service
Rules     src/AGENTS.md + AGENTS.md
Skills    aether/fix-ci@1.0.0 (explicit · builtin · trust builtin · sha256:8efbda8eb35b)
Context   706 tokens (measured, not estimated from a manifest)
Policy    read_file · run_tests · repo_search  — 3 of 8 host tools, enforced for every tool this host executes
Conflict  test command — effective "pytest -q" (nested src/AGENTS.md has higher precedence)
            also declared: "npm test" (AGENTS.md)

A skill can only ever narrow what a run may do; nothing in a skill manifest or an instruction file can grant authority the session did not already hold, and the operator permission gate still runs on everything the narrowing leaves. A skill matched automatically from a trigger phrase contributes its instructions but never its policy — only a skill you name with --skill narrows. Both flags work on aether chat and the REPL too.

aether exec "<task>" — headless packaged agent

Runs the packaged Ollama child by default, or an authenticated hosted Cloud text-model dev session with --exec-driver cloud. The cloud path keeps tool authority in this host and refuses any legacy server-executed downgrade; it requires explicit --model <id> so resumable authority cannot drift with a changed server default, plus --max-uvt <positive-integer> as a per-session hosted spend ceiling. Both bindings are persisted for v2 resume. Neo/Kronus aether-* orchestrator IDs are rejected because this endpoint cannot preserve their router identity. Stdout contains only versioned JSONL protocol frames; diagnostics use stderr. Protocol v1 remains the default. Select --exec-protocol 2 for repository-bound checkpoints, pause/resume/steer, bounded idempotent controls, and confined reusable agent definitions. The default tool envelope is read-only. Agent shell, Git, and network tools are disabled in both versions. A successful model completion exits non-zero unless the host-run --test-cmd also passes; v2 additionally requires the verification result to remain bound to the same commit and workspace bytes.

Flag Meaning
--exec-protocol <1|2> Select the headless protocol; v1 remains the compatibility default.
--exec-driver <ollama|cloud|selftest> Use the local model child, local-authority hosted text-model dev session (with explicit --model), or model-free installation selftest.
--max-uvt <positive-integer> Required cloud-driver per-session hosted spend ceiling; unavailable to local drivers and immutable on v2 resume.
--permission <deny|read-only|workspace-write> Set the host-enforced permission ceiling.
--allow-tool <name> Declare a safe file/search tool; repeat to declare more than one.
--capability-pack <id> Record a bounded capability-pack identifier; repeatable.
--agent-definition <path> Load an aether.exec.agent/1 definition confined to the workspace (v2 only).
--authority-ttl-ms <ms> Bound v2 checkpoint authority to 1 second–4 hours.
--resume <session-id> Resume a non-terminal v2 checkpoint without replacing its authority.
--timeout-ms <ms> Bound the run to 100 ms–1 hour.
--test-cmd <command> Run the authoritative final verification gate.

See docs/HEADLESS_PROTOCOL.md for framing, structured stdin controls, checkpoint and agent-definition contracts, payload bounds, and stable exit codes.

aether run <neo|kronus> "<task>" — orchestrator

Hands a multi-step task to an orchestrator, which plans, fans out sub-agents, and synthesizes. Streams task-level progress.

aether run neo "add pagination to the users endpoint and write tests"
aether run kronus "audit this service for race conditions and fix them"

Orchestrators are gated to paid tiers. Neo is available on Solo+; Kronus on Pro+.

aether setup --local and aether local — Ollama setup

aether setup --local and aether local doctor perform the same bounded, read-only diagnosis: Ollama binary, normalized endpoint, server response, installed tags, selected local model, backend setting, and hosted sign-in state. No token value is printed and no hosted API is called.

Command Effect
aether local doctor Diagnose Ollama without changing anything.
aether local models List installed tags as ollama:<tag> ids.
aether local use <model> Plan and, after confirmation or --yes, save a namespaced local default. Does not switch the backend.
aether local pull <model> Plan and, after confirmation or --yes, run ollama pull with argv-only process launch. Does not select it.

Stable local setup exit codes are 21 binary absent, 22 server down, 23 no installed models, 24 selected model missing, 25 timeout, 26 malformed host/response, 27 failed Ollama operation, and 28 failed configuration mutation. Usage remains 2; declining a shown plan is 20, and a cancelled pull follows the conventional 130. These values do not collide with the hosted routing-refusal code 3.

A bare --model <tag> is accepted for backward compatibility only when --local explicitly selects Ollama. Auto-local fallback requires the ollama:<tag> namespace, so a hosted model id cannot silently become an Ollama pull/chat tag. Conversely, an ollama: id is rejected before any hosted request.

aether preview <start|open|logs|status|stop> — managed local preview

preview start accepts an argv-only command (--command plus repeatable --arg) or the versioned project declaration .aether/preview.json. Before it starts anything it prints the exact argv, working directory, inherited permissions, and network implications, then requires confirmation or --yes. The supervisor accepts readiness only from reachable loopback HTTP(S) URLs. An explicitly declared readiness URL must be unreachable before launch and then become reachable while the child remains stable; this prevents an unrelated listener from authenticating the child. A URL discovered from child output is observational convenience, not proof that the child owns the port. The supervisor stores sanitized bounded logs under .aether/preview/ and owns the complete process tree. status, logs, and stop use an owner-private, one-use loopback challenge instead of trusting a PID file; an unverifiable stale PID is never signalled.

{
  "version": 1,
  "command": "npm",
  "args": ["run", "dev"],
  "cwd": ".",
  "readyUrl": "http://127.0.0.1:5173"
}

While an aether rc session is active for the project, preview start, status and stop publish the phases they observe (starting, ready, failed, stopping, stopped) to viewers under a session-scoped handle. They never publish the loopback URL, port, PIDs, argv or child error text. A viewer link appears only for the declared preview while it is ready, and only when the declaration carries an optional "publicUrl". That value must be a public https:// origin and path with no credentials, query, fragment, IP address, private or loopback-resolving host name (.local, .internal, .ts.net, .test, .onion, localtest.me, *.nip.io, a name spelling an IPv4 address, …) or token-shaped segment (long random runs, UUIDs, hex digests). The check is conservative: a name it cannot prove public is refused. While an RC session is active, a refused publicUrl stops preview start before anything starts; without one it is ignored with a warning. Publication is best-effort and never changes a preview's result or exit code.

Use --no-open in automation. A headless machine always receives the URL and an honest “not opened” result. /preview start|open|logs|status|stop uses the same project declaration and lifecycle inside the REPL. This local opener is separate from web fetching; it does not change the SSRF policy.

aether resume [id | export [id]] — replay or carry a session

Replays a prior local coding session's transcript from ~/.aether-agent/logs/. With no id, uses the most recent session in this workspace.

aether resume                          # replay the latest session
aether resume <session-id>             # replay a specific one
aether resume export                   # write ./aether-handoff.json
aether resume export <id> --out h.json # …from a specific session, to a path

export writes a handoff: one portable JSON file carrying the task, the model that ran it, the verify gate's verdict, the failing-test count, the files the run changed, the verification command, and the repository identity (origin remote, branch, HEAD). It carries no file contents, no shell commands, and no absolute paths, so it can be copied to another checkout, machine, or OS.

Continue from either form:

aether agent --resume <session-id> "<what to do next>"   # same machine
aether agent --resume ./handoff.json                     # anywhere else
aether agent --resume ./handoff.json --model <other>     # …on another model

With no new task, the run continues the original task. Either way the prior context is summarized into a continuation brief that the brain reads before its instruction — you never re-paste the conversation. See docs/demo/handoff.md for a runnable end-to-end proof.

Local-first: sessions are read from disk, so resume works offline. When you stop a coding run with Ctrl-C, the exact aether agent --resume <id> command is printed. A session id is workspace-scoped; a handoff file deliberately is not.

aether sessions [...] — the project session library

Everything the agent has done in this project, and what can still be done with it. Reads a small index beside the session logs, so listing costs one file read however long your history is — it never opens a transcript.

aether sessions                        # this project's sessions, newest first
aether sessions --all                  # every project on this machine
aether sessions --json                 # machine-readable rows + continuity state
aether sessions inspect <id>           # one session in full
aether sessions continue <id>          # what it was, and the exact next command
aether sessions export <id>            # write the portable handoff
aether sessions archive <id>           # hide it from the default list
aether sessions archive <id> --undo    # bring it back
aether sessions clean                  # drop index rows whose session is gone
aether resume list                     # the same listing, from the older command
aether resume <file.json>              # show an imported handoff, not a local session

On a terminal, aether sessions opens an arrow-key picker (/ filters, Enter inspects, Esc/q leaves); --no-select gives the flat table instead, and a pipe or --json always does. Piped output is tab-separated with a fixed field order (SESSION STARTED STATUS STATE BRAIN MODEL FILES_WRITTEN BRANCH TASK); a TTY gets a padded table.

Where a session can be continued is computed, not assumed. A session id is scoped to the absolute working directory it ran in, so the listing labels each row: ready, stale-branch (this checkout moved to another branch), moved (same repository, different checkout), elsewhere (another project), missing (the directory is not on this disk), archived. A session that cannot be continued here is refused with the reason and pointed at aether sessions export, which is the form that crosses machines.

Unknown is never rendered as zero. A file count nobody recorded prints as unknown, not 0. A run whose manifest never closed prints as never finished — running or interrupted, unknown which, because nothing on this machine can tell those apart. A branch the record does not name is not assumed to be the branch you are on now. Pull-request state is not recorded by this build at all, and says so rather than reading as "no PR".

Nothing here deletes your work. archive sets a flag; the session log, worktree and branch are untouched, and --undo reverses it. Archiving a session whose record never closed says so before asking. clean removes only index rows that point at sessions already gone from disk, after printing every row it will remove, and it is refusable. Neither command touches a worktree, a branch, or a file a run wrote.

aether models [use <id>] — list / pick a model

  • aether models — list every model and orchestrator visible to your tier. * = your current default, 🔒 = locked on your plan, cap N = monthly UVT ceiling for that model on your tier.
  • aether models use <id> — set your local default model/orchestrator.
aether models
aether models use sonnet

aether agents — list orchestrators

Lists only the orchestrators (Neo / Kronus), filtered from the same catalog.

aether auth <subcommand> — credentials

Modeled on GitHub's gh auth. One credential for the CLI, desktop, and web. aether login / aether logout are aliases for auth login / auth logout.

Subcommand Does
aether auth login Default: open aethersystems.net/platform, paste the CLI token.
aether auth logout Clear the stored credential (best-effort server notify).
aether auth status Show login state: token type (API token aek_ vs session), masked token, base URL, tier.
aether auth token Print the stored token (for scripts / CI).
aether auth refresh Refresh a session token (API tokens don't expire).

auth login flags:

Flag Meaning
(none) Browser OAuth: open the platform, paste the token.
--with-token Read the token from stdin (aether auth login --with-token < token.txt).
--token <t> Store a token directly.
--username <u> --password <p> Headless credential login.
--license-key <k> Supply a license key alongside credentials.
--no-browser Print the URL instead of opening a browser.

aether audit [limit] — recent receipts

Lists recent chain-of-custody entries for your account (default 50). Each row: timestamp · event · commitment_hash · order_id.

aether audit 20

aether receipt <order_id> — export proof

Exports the cryptographic proof package for one audit entry. Find ids with aether audit.

aether receipt chat_8f3a...

aether doctor [--live | --fix] — health, proof, and repair

Every check answers three questions separately, so "configured" is never mistaken for "working":

Agent transport
  configured     yes
  reachable      yes
  verified now   yes · 15:42:08

A check nobody exercised reports not checked — never a pass. A surface this build genuinely does not have reports n/a with the reason. Exits 1 if any check is an error, so it is safe to gate scripts on.

aether doctor — fast and strictly read-only. No network call, no model call, no session, no opener launch, no credential refresh, no write. Covers runtime, workspace, git, transport config, auth config, tools, memory, MCP registry, persistence, the media output index, the opener, GitHub, and Protocol-C receipt storage. Terminal Online readiness is listed as unverified until an authenticated live probe runs.

aether doctor --live — proves the paths end to end, right now: authenticated catalog fetch, a dev session, sequence-numbered frames, pause/resume/steer acknowledgement, a sandboxed tool write/read/compare/delete round trip, clean session close, a real browser open confirmed by a loopback callback, GitHub identity, branch freshness compared without fetching, the MCP broker, a Protocol-C receipt round trip, and terminal managed-agent registry, DM, and model/UVT readiness without sending a message. Billing is accounted across the run and reported as spend.none; the agent loop runs only when the server confirms a non-billable doctor session, and is reported as unproven otherwise. --no-ui skips the browser proof on a headless box (reported as skipped, not passed).

aether doctor --fix — a closed allowlist of local repairs, never a repair agent. Prints the exact scope, action, risk, reversibility and backup of every planned repair and changes nothing without --yes. It will not rotate credentials, spend UVT, invoke a model, edit source, mutate a git ref, dispatch Actions, run Predator, or call an MCP write tool.

aether doctor                      # fast, read-only
aether doctor --live               # end-to-end proof, no spend
aether doctor --live --no-ui       # same, on a headless box
aether doctor --fix --dry-run      # show the repair plan, change nothing
aether doctor --fix --yes          # apply the plan
aether doctor --fix --only media.rebuild --yes
aether doctor --json               # schema-versioned report for automation

--deep still means the read-only report it always meant; it now points at --live for the end-to-end proof.

aether skills <subcommand> — inspect, trust, and manage agent skills

Skills are packaged instructions the agent can load. Built-in skills ship with the package; user skills live under your config directory; project skills live in the repository you are working in.

aether skills list                 # every discovered skill, with scope and trust
aether skills show <id>            # one skill: manifest, declared tools, digest
aether skills check [--all]        # validate manifests and report index errors
aether skills trust <id>           # approve a project skill at its current digest
aether skills lock                 # pin discovered project skills to a lockfile

Project skills are untrusted until you approve them. Trust is bound to the skill's content digest, so editing a trusted skill revokes that trust until you approve the new digest. A skill declaration narrows what the agent may do — it never grants a tool the host would otherwise refuse.

In an idle interactive console using a local model, /skill <qualified-id> <task> loads an installed, enabled skill for just that task. For example, /skill user/fix-ci Investigate the failing unit test. The task suffix is sent literally, including extra spaces, newlines, quotes, /, and !; it is never dispatched as another console command. The run header shows the resolved skill ID, content digest, context size, and effective host tool limits. /context identifies the last admitted turn; /context next <task> previews normal next-turn defaults, or the current /skill command if one is supplied. History and the slash picker restore editable text, so submitting an old /skill line resolves its current digest and trust again.

/skill refuses busy, queued, line-input, --no-skills, and server-executed cloud chat use. Use aether agent --skill <id> <task> for a hosted host-executed run. A malformed or future-version local skill settings or trust store is never treated as an empty store; incompatible data is reported and left untouched until repaired. Normal skill defaults resume after this turn.

aether capabilities [--available] — what this build can actually do

Prints the capability contract: tools, their side-effect class, and the permission each requires. --available additionally reports what is usable in your current session rather than what exists in principle.

The command prefers the server manifest and falls back to a packaged snapshot when the server cannot be reached. It says which one it used, and why, rather than presenting stale data as live.

aether support-bundle — a redacted diagnostic archive

Writes a .tar of metadata-only diagnostics for troubleshooting: a fast doctor report, runtime facts, sanitized config, and skill and instruction inventories.

It carries counts, ids and digests — never prompts, file contents, tokens, environment values or raw command text. Every entry is scanned before the archive is finalized; if a secret is detected the bundle is refused rather than written, and an interrupted run leaves no partial file behind.

Like aether doctor, it makes no network call and spends nothing.

aether mcp [list|doctor|repair] — manage and diagnose MCP servers

With no subcommand (in a TTY), opens the same interactive MCP manager as the /mcp slash command: an arrow-key menu over backend connections (OAuth/PAT providers) and local custom servers (mcp.json), with authenticate / test / disconnect actions per entry.

Subcommand Does
aether mcp list Print a diagnostics report (providers, connections, tool counts).
aether mcp doctor Same report; exits 1 if any check fails (scriptable health gate).
aether mcp repair Back up and reset a corrupted local MCP registry (confirms first).
aether mcp drive login [--no-browser] Open GitHub sign-in on this computer, bind a separate Cloud session only after the staff route accepts it. Existing aek_ device API keys remain separate.
aether mcp drive logout Revoke and clear the dedicated Drive staff session.
aether mcp drive preview <intake.json> Read-only Cloud staff preflight. At G0, returns blockers and creates no mission or spend.
aether mcp drive status <lane-id> Read shared C1 mission metadata visible to the bound staff session.
aether mcp drive events <lane-id> [after-cursor] [limit] Page shared C1 control events visible to the bound staff session.

Drive reads require an existing bound Cloud staff session (for example a desktop-injected session). The ordinary aether auth login device flow issues an aek_ API key, which the Drive client refuses before sending a staff request. The Cloud independently checks staff role and lane visibility. These read commands do not start or control a mission.

aether config [show|get|set] — local settings

Local settings, stored at ~/.config/aether/config.json.

aether config                       # show all
aether config get defaultModel
aether config set defaultModel opus
aether config set permissionMode ask   # ask | auto | skip
aether config set autoApply true
Key Type Meaning
baseUrl string Aether API base URL.
defaultModel string Model used when --model is omitted.
defaultEffort string Effort tier for aether code when --effort is omitted (LOW|MED|HIGH|MAX|ULTRA|CODEPRO, "" = server default). Same dial as /effort.
permissionMode ask|auto|skip Gate edits/commands: prompt every time, auto with confirm, or fully autonomous.
autoApply bool Apply streamed edits without a per-edit prompt.
telemetry bool Anonymous usage telemetry opt-in.

When an interactive coding run asks to execute a tool, answering no opens a separate optional instruction field for that one declined call. Type a note such as Use the offline unit suite., then press Enter; an empty Enter skips it, and Escape or Ctrl+C cancels the note. The note is limited to 512 UTF-8 bytes and reaches the model once inside that call's failed tool result. It never approves or runs the tool. The main draft, prompt history, queued tasks, and reviewed shell attachment are untouched. Non-TTY decisions and --yes retain their existing behavior and do not produce an instruction.

Slash commands (inside the REPL)

Type a prompt to chat; type / to drive the session. /help renders this same set, grouped, inside the REPL. This table is the single source of truth — it mirrors the live registry in src/commands/slash_registry.ts.

Session

Command Action
/help Show the grouped command menu.
/models List chat models (numbered; › current, 🔒 locked).
/model <n|id> Choose a hosted model or ollama:<tag>; no arg opens the picker. The console shows a continuation brief before switching.
/switch <subcommand> Review the pending brief (brief), revise goal, constraints, or outstanding (edit), then continue, fresh, or cancel. The saved draft stays unsent.
/agents View active agent sessions (name, status, time, UVT, task).
/agent <n|id> Switch orchestrator (Neo / Kronus) — opens the picker with no arg.
/tier Show your plan tier, default, and available counts.
/effort [tier|1-6] Show or set the effort dial (LOW→CODEPRO). The dial moves phases, sub-agent fan-out, repair passes and the UVT ceiling; CODEPRO additionally enables System-2 review and unlimited context, and gets the banner. Persists to your Aether config and drives aether code.
/audit [n] Recent chain-of-custody receipts.
/doctor [deep] Run ordered diagnostics; deep adds bounded checks.
/clear Clear the screen.
`/mcp [list doctor
/exit, /quit Leave the REPL.

Typos get a nudge: /modle answers did you mean /model?. The raw TTY picker shows descriptions while typing a leading slash command.

Agent modes

Each starts an agent loop in the REPL.

Command Action
/autonomous-execution <task> Execute a task end-to-end without per-step prompts.
/subagent-driven-execution <task> Decompose a task and delegate to sub-agents.
/self-review Review your own recent work.
/recon <topic> Deep reconnaissance pass over the codebase.
/plan <topic> Write an implementation plan.
/skill <qualified-id> <task> Use a trusted skill for one idle local task.
/writing-plans <topic> Write a plan to .hermes/plans/.
/research <topic> Research → gather → summarize.
/project-review Full project review + summary. (Was /review; that name is now the change-review rail below.)
/code-review Sweep: clean up + simplify.
/writing-skills Author reusable skills.

Steering

Command Action
/queue <task> Queue a task to run when the current one finishes.
/steer <guidance> Steer the running local turn; reported as accepted, applied (with the boundary reached and any tool calls withheld), or refused. A hosted chat turn cannot acknowledge live steering, so the note is deferred to the next turn and says so. Never changes tool permissions.
/btw <note> Contextual side note (accumulates into context).

Context & limits

Command Action
/pin <path> [reason] Select a file for bounded, fresh inclusion at coding-turn admission.
/pin list List pinned files.
/drop <path> Stop automatic inclusion on future turns; explicit file-reading tools remain available.
/context Inspect the last admitted turn's rules, skills, file digests, bytes, bindings, and omissions without showing file bodies.
/context next <task> Preview the context for a draft task in the current workspace without sending it.
/context content <path> Explicitly preview up to 4096 bytes of a file included in the last admitted local turn.
/snapshot Save session state to disk.
/snapshot resume [id] Reload a snapshot (cloud first, else local; lists with no id).
/snapshot list List saved snapshots.
/limit <uvt> Cap UVT spend for the session (/limit off to remove).
/audit-receipt [n] Verified log of tool calls + UVT (local custody + server).
/rollback Discard uncommitted changes to tracked files (git-backed). Restores from the index, so files with staged changes come back to their staged state, not to the last commit. Untracked files are never touched.
/logs-view, /logs Interactive session log browser.

Pins are bound by project-relative path to the checkout where the task runs. The host reads each file once at admission and includes complete UTF-8 files only, up to 64 KiB per file, 32 pins, and the 512 KiB aggregate composed-context ceiling shared with rules and skills. Missing, binary, unsafe, and over-budget files are reported as omissions. /context next is a new preview; /context shows the frozen last admission, so a later file edit does not rewrite its digest. Server-executed cloud chat reports selected-file admission as unsupported because the local host cannot inspect its server-side context.

Goals & workflows

Command Action
/goal <desc> Create a goal; the agent plans phases.
/goal view [id] Show the goal chain + detail.
/goal start|pause|resume|cancel|complete|note Drive a goal's lifecycle.
/goals [id] List goals, or view one by id.
`/memory [status inspect
/workflow Workflow status.
/workflow-templates List workflow templates.
/workflow-template <n> Load a template.

Vault

Command Action
/vault Vault status (note count).
/vault-context Load vault context into the next agent turn.
/vault-search <q> Search notes.
/vault-recent [n] Most recent notes.
/vault-project <name> Notes for a project.
/vault-tag <tag> Notes by tag.
/vault-tree Vault folder tree.

Orchestra

Requires an active orchestrator — switch with /agent neo or /agent kronus first.

Command Action
/delegate <model> <task> Delegate a sub-task to a worker model.
/tree Live orchestration hierarchy (workers, step, tokens, UVT).
/broadcast "<msg>" Inject a directive to all sub-agents.
/gather <id|all> Merge completed sub-agent work to staging.

UVT Tools

Command Action
/scaffold <type> <name> Generate boilerplate: component, route, or module.
/port <file|dir> <lang> Translate code to another language.
/test-drive "<target>" Generate a test matrix for a route/function, run it, and iterate until green (requires an active orchestrator).
/bench <target> Profile a function/endpoint and suggest optimizations (requires an active orchestrator).
/purge Flush pinned files, temp files, and the UVT cap back to a lean baseline.
/stage-diff Unified diff of uncommitted changes + a suggested commit message.
`/review [stage unstage
/ship Publish the reviewed branch and open a pull request.
/revert <file|step> Surgical rollback of a single file (git-backed).

Media

Command Action
/photogen <prompt> [--model --aspect --count --4k --vector] Generate image(s).
/frame <prompt> Generate a single styled frame.
/re-frame <edit> Re-run the last image with an edit description.
/videogen <prompt> [--model --duration --1080p --audio] Generate video.
/sequence <prompt> Cinematic multi-shot video (routes to a cinematic model by default).
/animate <image_url|file|#n> [motion] Animate a still image into video.
/re-cut <edit> Re-edit the last generated video.
/output [open <ref>|clean] List, open, or clear recent generations. <ref> is a sequence number, a full artifact ID, or a unique ID prefix; an ambiguous reference lists its candidates instead of guessing.
/storyboard <prompt|file> [--scenes --style] Multi-scene storyboard: parse → preview → --generate/--animate/--render.

HUD

Command Action
/add <element>, /add list Add a HUD overlay element (context-bar, timer, tools, help, health, status), or list what's available.
/hud remove <element> Remove one active HUD element.
/hud list, /hud List active HUD elements.
/hud clear Remove all active HUD elements.

Environment variables

Var Default Meaning
AETHER_BASE_URL https://api.aethersystems.net/cloud Overrides the config baseUrl.
AETHER_LOGIN_URL https://aethersystems.net/platform Page aether auth login opens.
AETHER_TOKEN (unset) Inject a session token (CI / headless / embedding).
AETHER_CONFIG_DIR ~/.config/aether Config + token + REPL-history directory.
AETHER_LOG_DIR ~/.aether-agent/logs Where session logs (and therefore aether resume) live.
AETHER_BACKEND auto local | cloud | auto — overrides the config backend.
AETHER_LOCAL_BRAIN (unset) python runs the separately-installed Unlimited-Context brain instead of the built-in Ollama one.
OLLAMA_HOST http://localhost:11434 Where the offline brain looks for Ollama. Accepts Ollama's own scheme-less form (127.0.0.1:11434) as well as a full URL — see below.
AETHER_STREAM_TIMEOUT_MS 120000 Stream open/idle timeout (ms). 0 disables it.
AETHER_NO_ANIM (unset) 1 disables all animated status lines and the thinking pulse.
AETHER_NO_HISTORY (unset) 1 disables workspace prompt-history loading and saving, including Ctrl+R search.
NO_COLOR (unset) Any value disables ANSI colors (https://no-color.org).

See .env.example.

OLLAMA_HOST accepted forms

ollama serve prints and binds a scheme-less host:port, and that is what most people paste into OLLAMA_HOST. Every accepted form below is normalized to a full base URL before any request is built:

You set Aether uses Note
(unset or empty) http://localhost:11434 The default.
127.0.0.1:11434 http://127.0.0.1:11434 Scheme-less — http:// is added.
localhost:11434 http://localhost:11434 Scheme-less.
0.0.0.0:11434 http://127.0.0.1:11434 0.0.0.0 is a bind address, not a connect address.
http://localhost:11434/ http://localhost:11434 Trailing slashes are stripped.
https://ollama.example.com https://ollama.example.com A remote/proxied Ollama.

Anything that still will not parse as an http/https URL is rejected up front with an error naming the bad value, instead of failing later as "cannot reach Ollama".

Exit codes

Code Meaning
0 Success.
1 Runtime error (network, server error, etc.).
2 Usage error (bad/missing arguments).
3 Routing refused. aether agent needs a transport with local authority (the dev-session protocol, where tools run in this checkout). When the server refuses it — 403 agent dev sessions disabled, or 404 on an older server — the run prints a ROUTING_DRIFT line and stops rather than degrading to the one-way chat stream, whose tools run server-side and would change nothing on disk. Ask the operator to set AETHER_AGENT_DEV_ENABLED=1, or run aether agent --local.

Embedding (library API)

import { createClient } from "aether-agents";
const aether = createClient({ baseUrl, token });

aether.chatStream(prompt, { model?, agent?, manualModel? })  // AsyncIterable<StreamFrame>
aether.catalog()                                             // { models, tier, default }
aether.login(username, password, licenseKey?)
aether.http                                                  // raw authed HTTP on the same route

Stream frames: open · ping · reasoning · delta · usage · done · error, plus orchestrator frames task_start · task_progress · task_done · task_failed · task_blocked · project_done. Unknown frame types are ignored.