aether task

Manage agent tasks. A task is one agent run that reads files, executes commands, and writes code in an isolated workspace. See tasks and lifecycle for concepts.

Usage

aether task <subcommand> [flags]

tasks is an alias for task. Most <id> arguments accept a short prefix.

Subcommands

Subcommand	Description
`list`	List tasks for the current project
`create`	Create a new task
`get <id>`	Show task details and the event timeline
`status <id>`	Show compact task status
`update <id>`	Update the task’s agent settings
`respond <id>`	Send a follow-up message or answer the agent inline
`stop <id>`	Stop a running task and park it in `awaiting_input`
`archive <id>`	Archive a task
`unarchive <id>`	Unarchive a task
`remove-from-queue <id> <message-id>`	Remove one queued follow-up message
`watch <id>`	Watch the agent’s progress live

aether task list

List tasks in the current project.

aether task list [flags]

Flag	Description
`--status`	Filter by display status, comma-separated (see below)
`--needs-you`	Only tasks waiting on you — mutually exclusive with `--status`
`--started-at-op`	Started-at operator: `before`, `after`, or `equal`
`--started-at-date`	Started-at date (`YYYY-MM-DD`)
`--ended-at-op`	Ended-at operator: `before`, `after`, or `equal`
`--ended-at-date`	Ended-at date (`YYYY-MM-DD`)
`--order`	Order: `created_at` or `agent_sidebar`
`--limit`	Maximum tasks to return
`--page`	Page number

--status takes one or more display statuses, comma-joined: running, awaiting_input, awaiting_ci, merged, unmerged, errored, archived. It also takes review_attention — a virtual filter token, not a display status, that matches a task whose pull-request review needs your judgment. Pass all to clear the filter. --needs-you is the shorthand for the same set the web app’s “Needs you” filter sends: --status awaiting_input,review_attention,errored.

aether task list

ID          STATUS            PR                CREATED    NAME
a1b2c3d4    running                             2m ago     Fix the login bug
e5f6g7h8    awaiting_input                      1h ago     Add dark mode
i9j0k1l2    errored                             3h ago     Deploy to production
q7r8s9t0    done              #131 awaiting_ci  5h ago     Add rate limiting
m3n4o5p6    done              #128 merged       2d ago     Ship the API docs

The STATUS column is the task’s own state — running, awaiting_input, errored, done, or archived. Pull-request lifecycle lives in the PR column, so --status merged returns rows whose STATUS reads done with the merge shown under PR. The PR cell names the same bucket --status filters on: merged, or awaiting_ci for an open PR whose checks are still running. unmerged is a catch-all over open and closed PRs, so those rows show the pull request’s own state (open, closed) instead. --json is unaffected: it prints the server’s envelope, including the raw display_status.

# Multiple statuses
aether task list --status running,awaiting_input

# Everything that blocks on you
aether task list --needs-you

aether task create

Create a task with a prompt. If --prompt is omitted (and not reading --stdin), you are prompted for it interactively.

aether task create [flags]

Flag	Description
`--prompt`	The task description
`--stdin`	Read the prompt from standard input
`--size`	VM size: `small`, `medium`, or `large`
`--agent-type`	Override the project default agent type
`--model`	Override the project default model
`--interaction-mode`	Override the project default interaction mode
`--reasoning-effort`	Override reasoning effort, or `none` to clear
`--auto-fix-ci`	Auto-fix CI (`true` or `false`)
`--auto-fix-pr-comments`	Auto-fix PR comments (`true` or `false`)
`--auto-rebase`	Auto-rebase (`true` or `false`)
`--base-branch`	Base branch for the task branch and pull request
`--context-file`	Workspace file path to include in prompt context; repeatable
`--attach`	Local image file to attach; repeatable

aether task create --prompt "Add input validation to the signup form" --size medium

Task created: a1b2c3d4

  Run 'aether task watch a1b2c3d4' to watch progress.

aether run does create plus watch in one step and is usually what you want.

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

aether task get

Show task details, summary, and the event timeline.

aether task get a1b2c3d4

aether task status

Show a compact status line — runtime status, display status, workspace, PR/CI, and tokens.

aether task status a1b2c3d4

aether task update

Replace the task’s agent settings. Provide at least one flag.

aether task update <id> [flags]

Flag	Description
`--agent-type`	Agent type
`--model`	Model
`--interaction-mode`	Interaction mode
`--reasoning-effort`	Reasoning effort, or `none`
`--auto-fix-ci`	Auto-fix CI (`true` or `false`)
`--auto-fix-pr-comments`	Auto-fix PR comments (`true` or `false`)
`--auto-rebase`	Auto-rebase (`true` or `false`)

aether task respond

Continue a task: send a follow-up message, or answer the agent inline when it is waiting on you.

aether task respond <id> [flags]

Flag	Description
`--message`	Follow-up message text
`--stdin`	Read the message from standard input
`--answer`	Answer a structured question: `<question>:<option>` or `<question>:other:<text>`; repeatable
`--approve`	Approve the proposed plan
`--reject`	Reject the proposed plan
`--feedback`	Feedback to include with `--approve`/`--reject`
`--no-watch`	Send the response without streaming the reply
`--interaction-mode`	Override the follow-up interaction mode
`--reasoning-effort`	Override follow-up reasoning effort, or `none`
`--context-file`	Workspace file path to include in follow-up context; repeatable
`--attach`	Local image file to attach; repeatable

With --message, the text is sent directly:

aether task respond a1b2c3d4 --message "Use bcrypt instead of argon2"

respond streams the agent’s reply by default, the same way aether run does, and exits non-zero if the task fails. Pass --no-watch to send and return immediately. --json prints the message id without streaming:

aether task respond a1b2c3d4 --message "Use bcrypt instead of argon2" --no-watch
aether task respond a1b2c3d4 --message "Use bcrypt instead of argon2" --json

When you omit --message, respond is interactive. If the task is waiting on a question (ask_user) or a plan review (propose_plan), the CLI presents the prompt and submits your structured answer. Otherwise it asks you for a free-text message.

# Answer the agent's open question or review its plan
aether task respond a1b2c3d4

Structured input can also be answered non-interactively, so scripts and agents can drive tasks without a TTY. Read the pending question or plan from aether task get <id> --json (awaiting_input.kind plus the payload), then respond:

# Select option 1 of question 0
aether task respond a1b2c3d4 --answer 0:1

# Multi-select questions take repeated --answer flags for the same question;
# other:<text> gives a free-text answer
aether task respond a1b2c3d4 --answer 0:0 --answer 0:2 --answer 1:other:"use Redis"

# Approve or reject a proposed plan
aether task respond a1b2c3d4 --approve
aether task respond a1b2c3d4 --reject --feedback "Split the migration into two steps"

Every question must be answered, and each --answer is validated against the pending questions before anything is sent. --message composes with all three flags as the accompanying note on the task timeline. If the task is awaiting a structured answer, passing --message alone is rejected — pass --answer/--approve/--reject, or run respond without flags so the CLI can present the question or plan.

aether task stop

Stop a running task and park it in awaiting_input so you can respond and resume.

aether task stop a1b2c3d4

Task a1b2c3d4 stopped.

aether task archive / unarchive

Move a task into or out of the archive.

aether task archive a1b2c3d4
aether task unarchive a1b2c3d4

aether task remove-from-queue

Remove a single queued follow-up message from a task by its message ID.

aether task remove-from-queue <id> <message-id>

aether task remove-from-queue a1b2c3d4 msg_9f8e7d

aether task watch

Watch the agent’s progress live. The watch exits when the task completes, fails, or stops.

aether task watch a1b2c3d4

Watch polls the API every ~3 seconds for new status updates. A failed task exits non-zero and prints the failure, whether it failed while you were watching or before you attached — so watching an already-failed task is still how you read the error, and scripts can rely on the exit code either way. This is the same exit status aether run and aether task respond give you, since both watch through the same code.

Interactive Watch

On a TTY, watch is interactive. While watching you can:

Key	Action
`Enter`	Send a message to the agent (queued if the agent is still working)
`Esc`	Stop the task (parks it in `awaiting_input`) and exit
`Ctrl+C`	Detach from the watch without stopping the task

When the agent pauses to ask a question or propose a plan, watch presents it inline — answer it and watching continues automatically. After detaching, reattach any time:

aether task watch a1b2c3d4

CLI Reference

Core Commands

Account Commands

Workspace Commands

Integration Commands

Provider Auth

Configuration

Usage

Subcommands

aether task list

aether task create

aether task get

aether task status

aether task update

aether task respond

aether task stop

aether task archive / unarchive

aether task remove-from-queue

aether task watch

Interactive Watch

​Usage

​Subcommands

​aether task list

​aether task create

​aether task get

​aether task status

​aether task update

​aether task respond

​aether task stop

​aether task archive / unarchive

​aether task remove-from-queue

​aether task watch

​Interactive Watch

Usage

Subcommands

aether task list

aether task create

aether task get

aether task status

aether task update

aether task respond

aether task stop

aether task archive / unarchive

aether task remove-from-queue

aether task watch

Interactive Watch