Skip to main content
Create a task and watch the agent’s progress. This is the primary CLI workflow — equivalent to aether task create followed by aether task watch.

​
Usage

The prompt is required unless you pass --stdin. Multiple arguments are joined into one prompt. The task runs against your default project, or the one you pass with -p.

​
Flags

aether run accepts every task-create option flag plus --no-watch and the canonical environment-bootstrap prompt flag. Global flags are also available. See the CLI Overview. Every task carries an explicit VM size. If you omit --size, the size is resolved server-side — the project’s default task size, else small — and the CLI prints size: project default (use --size to override). A task starts warm only when its project has a ready machine at the requested size. See VM sizes and warm starts. With --json, the size is still resolved server-side the same way; the CLI only suppresses the notice so stdout remains valid JSON.

​
Examples

​
Run a quick task

The CLI creates the task and watches its progress, polling the API every ~3 seconds for status updates (workspace startup, pull-request creation) and printing the agent’s summary when it finishes its turn. The watch exits when the task completes, fails, or stops. For a live stream of the agent’s text, reasoning, and tool calls, open the task in the web or mobile app.

​
Create a task without watching

Reattach later with aether task watch.

​
Bootstrap a repository’s Aether environment

This uses the same embedded environment-bootstrap prompt as the guided first-task flow. The prompt has one canonical source in the CLI; callers select it with the flag rather than copying it into scripts or documentation.

​
Target a specific project

​
Read the prompt from stdin with context

--context-file references a path inside the workspace; --attach uploads a local image file (PNG, JPEG, GIF, WebP, or AVIF, up to 5 MiB each).

​
Branch from a specific base

​
Interactive Watch

When attached, the watch is interactive on a TTY. The agent can pause to ask a question or propose a plan, and you answer inline. See interactive watch for the full key bindings and behavior.