> ## Documentation Index
> Fetch the complete documentation index at: https://orbit.nckrtl.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# tasks

> Create, prepare, inspect, cancel, and complete tasks, and read or replace a Project's task definitions, through the Gateway tasks extension.

The `tasks` family runs the operations of the Gateway [tasks extension](/docs/reference/tasks) from the command line. Agents usually use the [MCP server](/docs/reference/mcp); the CLI offers the same operations when MCP is unavailable. Each command name equals its Gateway route name, and its MCP tool name uses hyphens instead of colons, so `tasks:subtask:create` is the MCP tool `tasks-subtask-create`. Two operations have no CLI command. Use the MCP tool `tasks-check-cancel` to stop a running task check. The agent thread stream, `GET /api/v1/task-groups/{group}/agents/{session}/stream`, serves the web app.

A task is one feature. A subtask is one ordered child of that task, and a subtask has no children. The [tasks reference](/docs/reference/tasks) owns the lifecycle, the scheduler, and every Gateway rule that these commands reach.

## Commands

| Command | Result |
| - | - |
| [`tasks:status`](#orbit-tasksstatus) | Show whether the tasks extension is on, list tasks asking for assistance, and list open review-and-merge tasks. |
| [`tasks:list`](#orbit-taskslist) | List tasks, optionally for one Project or status. |
| [`tasks:show`](#orbit-tasksshow) | Show one task with its brief and subtasks. |
| [`tasks:create`](#orbit-taskscreate) | Create a task in Backlog or Todo. |
| [`tasks:update`](#orbit-tasksupdate) | Change a task's title, brief, or status. |
| [`tasks:cancel`](#orbit-taskscancel) | Cancel a task and remove its Instance. |
| [`tasks:complete`](#orbit-taskscomplete) | Complete a settling task, or a running or reviewing task whose watched pull request ended, and remove its Instance. |
| [`tasks:subtask:create`](#orbit-taskssubtaskcreate) | Append a subtask to a task. |
| [`tasks:subtask:update`](#orbit-taskssubtaskupdate) | Change a subtask's title, brief, position, or deliverables. |
| [`tasks:subtask:destroy`](#orbit-taskssubtaskdestroy) | Delete a subtask. |
| [`tasks:subtask:cancel`](#orbit-taskssubtaskcancel) | Cancel a Todo or running subtask. |
| [`tasks:comment:create`](#orbit-taskscommentcreate) | Ask for assistance on a subtask or resolve a request. |
| [`tasks:comment:list`](#orbit-taskscommentlist) | List a subtask's comments. |
| [`tasks:question:list`](#orbit-tasksquestionlist) | List the questions agents asked, across tasks. |
| [`tasks:question:close`](#orbit-tasksquestionclose) | Close an open or escalated question as answered or superseded. |
| [`tasks:agents`](#orbit-tasksagents) | List a task's agent threads. |
| [`tasks:definition:list`](#orbit-tasksdefinitionlist) | List task definitions. This command does not start a task. |
| [`tasks:definition:show`](#orbit-tasksdefinitionshow) | Show one task definition. This command does not start a task. |
| [`tasks:definition:create`](#orbit-tasksdefinitioncreate) | Create a task definition from a JSON file. This command does not start a task. |
| [`tasks:definition:update`](#orbit-tasksdefinitionupdate) | Replace a task definition from a JSON file. This command does not start a task. |
| [`tasks:definition:destroy`](#orbit-tasksdefinitiondestroy) | Delete a task definition. This command does not delete tasks. |

Every command accepts `--json`. JSON output is the Gateway record with `request_id` beside its fields. A list holds its records under `task_groups`, `comments`, `questions`, `agents`, or `task_definitions`. The [PHP SDK](/docs/api/php-sdk) task responses return those same records, including `assistance_kind` and `assistance_question` on a task and a subtask.

`tasks:list`, `tasks:show`, `tasks:question:list`, `tasks:definition:list`, and `tasks:definition:show` accept any authorized peer. `tasks:update` and the `tasks:subtask:*` commands need access to the Node that holds the task's Instance, or to the Gateway for a task without one. `tasks:definition:create`, `tasks:definition:update`, and `tasks:definition:destroy` need Gateway access. The remaining commands need Gateway access too: run them on the Gateway, or on a Node with an access grant to the Gateway. Other callers receive `node_access.required`. While the extension is off, every command except enable, disable, and status fails with `extension.disabled`.

[Trusted GitHub requested changes](/docs/reference/tasks#trusted-github-feedback) can append a normal fixup subtask. `tasks:show --json` exposes its source review and findings in the existing `brief`. The Gateway API's `fixup_problem` is `review:{reviewer_id}`; the CLI keeps its existing brief and deliverable fields without adding an identity field. Use the existing cancel or operator-subtask commands when that scope needs intervention. No command configures reviewer trust, submits a GitHub review, requests external re-review, or merges a pull request. In a Project with [review and merge](/docs/reference/tasks#review-and-merge) on, the Gateway itself reviews and merges; the CLI only shows that state. The Gateway's automatic findings packet has its own 64 KiB bound; the CLI's 8,000-character input limit remains unchanged.

Subtask creation and update accept `--topology='["app-dev","app-prod+ingress"]'`. Each entry names a node, `app-dev`, `app-prod`, or `app-prod-2`, once, and may add the role `ingress` after `+`. The CLI checks only that the value is a JSON array of distinct strings, and refuses anything else with `tasks.invalid_topology`. The Gateway validates the entries and how many a topology may have. On update, omit the option to keep the declaration or pass `--topology='[]'` to clear it. Each object in a `--subtasks` JSON file can carry the same `topology` array. A started subtask cannot change its declaration. The [compute driver](/docs/reference/compute-drivers#declare-a-topology) sizes the group's VM by these declarations at the claim and prepares the nodes nested in it.

## Select a task or subtask

A `group` argument is a numeric task ID, and a `subtask` argument is a numeric subtask ID. When you omit either in a terminal, the CLI lists the candidates and you select one. The task list shows the ID, title, Project, and status. The subtask list shows the position, ID, title, and status of the task's subtasks. An empty list stops the command with `No matching records were found.`

With `--json` or `-n`, an omitted task fails with `tasks.group_required` and an omitted subtask fails with `tasks.subtask_required`. A value that is not a positive integer fails with `tasks.group_invalid` or `tasks.subtask_invalid`.

Human output names a task by its Project code and ID, such as `ORB-13`, as the web task board does. The CLI accepts only the numeric ID. Human output shows times to the minute in the Gateway's time zone; JSON keeps the full timestamps.

The CLI checks prompted text when you submit it. A title holds 1 to 160 characters, and a brief holds 1 to 8,000 characters. The brief prompt is a multiline text area. Pressing Ctrl-C or reaching the end of input at a prompt stops the command before any change.

## orbit tasks:status

Show whether the tasks extension is on, then list every task currently asking for assistance and every open review-and-merge task.

```bash theme={"dark"}
orbit tasks:status [--json]
```

JSON returns `enabled` as `true` or `false`, `last_tick_at`, and `assistance` as a list in ascending task id order. `last_tick_at` is the time the latest `tasks:tick` took the tick lock and started its work, or `null` when the Gateway remembers no tick. The human output shows it as `Last tick`, or `not recorded`. The [scheduler](/docs/reference/tasks#scheduler) explains the record. Each entry has the task's `id`, `project_id`, `project`, `project_code`, `title`, `status`, `assistance_kind`, `assistance_question`, and `assistance_reason`. The list is empty when no task is asking, and it is present while the extension is off. The human output shows direction requests first, under `Needs your direction`, with the task reference, title, status, and question. Failures follow under `Failures`, with the task reference, title, status, and reason. An empty list says `No groups are asking for assistance.` The [tasks reference](/docs/reference/tasks#direction-requests) defines the two kinds.

JSON also returns `merges`: each open task of a review-and-merge Project, or with an incoming pull request, in ascending task id order. Each entry has `id`, `project_id`, `project`, `project_code`, `title`, `status`, `pr_url`, `pr_branch`, `merge_status`, and `merge_reason`. The human output lists them under `Review and merge` with the task reference, title, status, merge status, and reason, and omits the section when the list is empty. [Merge on green](/docs/reference/tasks#merge-on-green) defines the merge status.

## orbit tasks:list

List tasks with their title, Project, status, and number of completed subtasks. The list shows each task's assistance kind. A task that asks for direction shows its question. A task that asks because of a failure shows its reason. A task that is not asking shows an em dash for both, even when an old value is still stored. JSON includes `assistance_kind` and `assistance_question` on each task.

```bash theme={"dark"}
orbit tasks:list [--project=ID] [--status=STATUS] [--json]
```

| Option | Meaning |
| - | - |
| `--project=ID` | Only tasks of this numeric Project ID. |
| `--status=STATUS` | Only tasks in this status: `backlog`, `todo`, `reserved`, `running`, `reviewing`, `settling`, `waiting_for_review`, `completed`, `failed`, or `cancelled`. |

An invalid filter fails with `tasks.project_invalid` or `tasks.status_invalid` before the request. The CLI does not prompt for a filter.

## orbit tasks:show

Show one task as a detail tree, followed by its brief and a table of its subtasks in position order.

```bash theme={"dark"}
orbit tasks:show [group] [--json]
```

The tree shows the ID, title, Project, status, whether the task is asking for assistance, the assistance kind, the question, the reason, Instance, pull request, Coder notification, models, tokens, line diff, and duration. The subtask table shows the position, ID, title, status, deliverables, tokens, line diff, duration, assistance kind, and the question or reason of each subtask. A direction request shows its question in that last column. A failure shows its reason. A subtask or task that is not asking shows an em dash in the kind, question, and reason columns, even when an old value is still stored. JSON includes `assistance_requested`, `assistance_kind`, `assistance_question`, and `assistance_reason` on the task and each subtask, and `fails_on_base` on every command deliverable. When that value is true, the detail names the deliverable under Fails on the start commit. Showing an active task refreshes its metrics, as the [tasks reference](/docs/reference/tasks#tokens-and-line-diff) describes.

The tree shows **VM power** when the task's `vm_power` is not `null`. JSON includes `vm_power` when power is known: `running`, `stopped`, or `destroyed`; it omits the field when the API reports `null`. [VM power](/docs/reference/compute-drivers#vm-power) describes how those values map to the task VM's state, separately from task status.

On the task, `watched_pr_url`, `watched_pr_number`, and `watched_pr_state` report the pull request found on `task-{id}` while subtasks are open. Those fields do not change `pr_url`, which remains the reviewed pull request Orbit opened.

A task of a review-and-merge Project, or one that reviews an incoming pull request, also has `review_and_merge` in JSON: `enabled`, `pr_branch`, `merge_status`, `merge_reason`, `merged_sha`, and `reviewed_commits`. Each reviewed commit has `sha`, `source`, `review_task_id`, `pushed_at`, `github_review_id`, and `recorded_at`. Other tasks return `null`. The tree adds `Review and merge`, `Pull request branch`, `Merge`, and `Merged commit`, and a table lists the reviewed commits. A final review subtask has `type` `final_review`. [Review and merge](/docs/reference/tasks#review-and-merge) defines these fields.

## orbit tasks:create

Create a task. It starts in `backlog` unless you ask for `todo`.

```bash theme={"dark"}
orbit tasks:create [title] [--project=ID] [--brief=TEXT] [--status=STATUS] [--subtasks=FILE] [--notify-coder] [--preview] [--json]
```

| Input | Default | Meaning |
| - | - | - |
| `title` | prompt | Short name of the feature. |
| `--project=ID` | prompt | Numeric Project ID. In a terminal, the CLI lists Projects to select from. |
| `--brief=TEXT` | prompt | Goal and acceptance. Pass a file with `--brief="$(cat brief.md)"`. |
| `--status=STATUS` | `backlog` | `backlog` or `todo`. `todo` needs at least one subtask, each with deliverables, and asks the scheduler to claim the task. |
| `--subtasks=FILE` | none | JSON file with an ordered array of at most 50 objects, each with a string `title` and `brief` and an optional `deliverables` array. |
| `--notify-coder` | off | Post the Coder settle webhook when the task settles. |
| `--preview` | off | Keep the task's sandbox running during review. See [Request a preview](/docs/reference/compute-drivers#request-a-preview). |

```bash theme={"dark"}
orbit tasks:create "Add tasks CLI" --project=1 --brief="$(cat brief.md)"
orbit tasks:create "Add tasks CLI" --project=1 --brief="$(cat brief.md)" --subtasks=subtasks.json --status=todo
```

The CLI does not prompt for the status, the subtasks, or the notification. After the Gateway answers, the CLI shows the task as `tasks:show` does. A task created in `todo` can already be `failed` when its first agent could not start. The tree then reports that status.

| Error code | Meaning |
| - | - |
| `tasks.project_required`, `tasks.title_required`, `tasks.brief_required` | A `--json` or `-n` call omits a required input. |
| `tasks.project_invalid`, `tasks.title_invalid`, `tasks.brief_invalid`, `tasks.status_invalid` | A supplied value is outside the accepted form. |
| `tasks.subtasks_invalid` | The CLI cannot read the subtasks file, or its content is not an array of at most 50 entries with a valid title and brief and, when present, a `deliverables` array. |
| `tasks.no_subtasks` | `--status=todo` without subtasks. |
| `tasks.subtask_deliverables_missing` | `--status=todo` while a subtask has no deliverables. |
| `tasks.agent_driver_unavailable` | The Gateway's configured agent driver is unknown. The Gateway stores no task. |

## orbit tasks:update

Change a task's title, brief, or status. Title and brief change only while the task is in `backlog`. The status moves between `backlog` and `todo`. A move to `todo` asks the scheduler to claim the task.

```bash theme={"dark"}
orbit tasks:update [group] [--title=TEXT] [--brief=TEXT] [--status=STATUS] [--preview | --no-preview] [--json]
```

| Option | Meaning |
| - | - |
| `--title=TEXT` | New title. |
| `--brief=TEXT` | New brief. |
| `--status=STATUS` | `backlog` or `todo`. |
| `--preview` | Keep the sandbox running during review. It can change while the task is in `backlog`, waiting, or active. |
| `--no-preview` | Let the sandbox park during review. Do not combine it with `--preview`. |

```bash theme={"dark"}
orbit tasks:update 13 --status=todo
```

In a terminal, the task list shows `backlog` and `todo` tasks. Without a change option, the CLI asks which fields to change and prompts for each one with its current value. A `--json` or `-n` call without a change option fails with `tasks.update_required`.

| Error code | Meaning |
| - | - |
| `tasks.not_in_backlog` | A title or brief change outside `backlog`. |
| `tasks.no_subtasks` | A move to `todo` for a task without subtasks. |
| `tasks.subtask_deliverables_missing` | A move to `todo` while a subtask has no deliverables. The error details name the subtasks. |
| `tasks.already_claimed` | The scheduler claimed the task before the status change. |

## orbit tasks:cancel

Cancel a task that is stuck or that you do not want to run. The Gateway removes the task's workspace and task VM when it has them and marks the task `cancelled`. Subtasks, comments, and agent thread records stay as history. Cancellation does not stop the external agent conversation.

```bash theme={"dark"}
orbit tasks:cancel [group] [--yes] [--json]
```

| Option | Meaning |
| - | - |
| `--yes` | Confirm without a prompt. Required for `--json` and `-n` calls. |

In a terminal, the task list leaves out `settling`, `waiting_for_review`, and `completed` tasks. Before it asks, the CLI reads the task and names it and its Instance in the question. The question defaults to No. A `--json` or `-n` call without `--yes` fails with `input.confirmation_required`. Declining fails with `input.cancelled`. Neither changes the task. A `completed` task, or a `settling` task with a pull request, fails with `tasks.not_cancellable`; complete a settling task instead. Pass the task ID to cancel a `settling` task without a pull request. When its Node answers, the Gateway first pushes the latest approved commit to the task branch; a failed push fails with `tasks.push_failed` and keeps the task. When the Node is unreachable, the task is still marked `cancelled`, the Instance stays attached, and the scheduler retries removal, as the [tasks reference](/docs/reference/tasks#cancel-a-stuck-task) describes.

## orbit tasks:complete

Complete a `settling` or `waiting_for_review` task after its pull request is reviewed and merged. Also complete a `running` or `reviewing` task whose watched pull request has merged or closed. The Gateway marks the task `completed` and removes its shared Instance.

On the `running` or `reviewing` path it stores the ended state, stops the running implementer or reviewer and any running check, then cancels each open subtask and marks the task `completed` in one transaction. A failed stop returns `tasks.subtask_interrupt_failed`, keeps the task and its subtasks open, and leaves the stored completion for retry. The [tasks reference](/docs/reference/tasks#complete-and-cleanup) defines how a crash resumes without another GitHub read. Completing a completed task whose checkout is already gone succeeds and changes nothing. Completing a completed task that still has its Instance retries removal. There is no `tasks:continue` command.

```bash theme={"dark"}
orbit tasks:complete [group] [--yes] [--json]
```

| Option | Meaning |
| - | - |
| `--yes` | Confirm without a prompt. Required for `--json` and `-n` calls. |

In a terminal, the task list shows only `settling` tasks. Pass the task id to complete a `running` or `reviewing` task whose watched pull request has ended. The question names the task and its Instance and defaults to No. Consent failures match `tasks:cancel`. A task that is not one of those ready cases fails with `tasks.not_settling`. That includes a `running` or `reviewing` task whose watched pull request is missing, open, or unreadable, unless completion was already recorded. When removal fails, the task is still marked `completed`, the Instance stays attached, and the scheduler retries removal, as the [tasks reference](/docs/reference/tasks#complete-and-cleanup) describes.

## orbit tasks:subtask:create

Append one subtask to a task at the next position, with status `todo`. This works in every task status except `completed` and `cancelled`. Outside `backlog`, the subtask needs deliverables. When the task is `settling` or `waiting_for_review` with an open pull request, or with no pull request, the next tick returns the task to `running` and starts this subtask. Another assistance cause keeps the task `settling`. The [tasks reference](/docs/reference/tasks#fix-a-settling-pull-request) owns that transition.

```bash theme={"dark"}
orbit tasks:subtask:create [group] [title] [--brief=TEXT] [--deliverables=FILE] [--topology=JSON] [--json]
```

| Input | Default | Meaning |
| - | - | - |
| `title` | prompt | Short name of the step. |
| `--brief=TEXT` | prompt | Goal and acceptance of the step. |
| `--deliverables=FILE` | none | JSON file with an array of at most five [deliverables](/docs/reference/tasks#deliverables), of type `file`, `command`, or `review`. Only a command deliverable may set `fails_on_base` to `true` or `false` and supply `paths`. When `fails_on_base` is `true`, `paths` must list at least one workspace-relative file for the base run. The CLI refuses these fields on any other type. |
| `--topology=JSON` | none | JSON array of the test nodes the subtask needs, such as `["app-dev","app-prod+ingress"]`. See [Declare a topology](/docs/reference/compute-drivers#declare-a-topology). |

```bash theme={"dark"}
orbit tasks:subtask:create 13 "Document the export" --brief="$(cat step.md)" --deliverables=deliverables.json
```

A `--json` or `-n` call fails with `tasks.title_required` or `tasks.brief_required` when a value is missing. The CLI does not prompt for deliverables. It shows the created subtask as a detail tree followed by its brief and a table of its deliverables.

| Error code | Meaning |
| - | - |
| `tasks.deliverables_invalid` | The CLI cannot read the deliverables file, or its content is not an array of at most five objects. |
| `tasks.group_closed` | The task is completed or cancelled and cannot accept a new subtask. |
| `validation.failed` | The Gateway refuses a deliverable. The error details name each field, such as `deliverables.0.path`. |
| `tasks.subtask_deliverables_missing` | A subtask without deliverables for a task outside `backlog`. |

## orbit tasks:subtask:update

Change a subtask's title, brief, position, or deliverables while its task is in `backlog`. In `todo`, `running`, `reviewing`, `settling`, or `waiting_for_review` tasks, change any of those fields only while the subtask is `todo`. Deliverables cannot be empty. A new position moves only among `todo` subtasks; it cannot put one before a started or finished subtask. Positions stay gapless. Started subtasks keep their existing restrictions, and tasks in `completed` or `cancelled` are read-only.

```bash theme={"dark"}
orbit tasks:subtask:update [group] [subtask] [--title=TEXT] [--brief=TEXT] [--position=N] [--deliverables=FILE] [--topology=JSON] [--json]
```

| Option | Meaning |
| - | - |
| `--title=TEXT` | New title. |
| `--brief=TEXT` | New brief. |
| `--position=N` | New position, starting at 1. |
| `--deliverables=FILE` | JSON file with an array of at most five [deliverables](/docs/reference/tasks#deliverables). It replaces the whole list. |
| `--topology=JSON` | JSON array of the test nodes the subtask needs. `[]` removes the declaration. Only a subtask that has not started can change it. |

```bash theme={"dark"}
orbit tasks:subtask:update 58 88 --deliverables=deliverables.json
```

In a terminal, the task list shows `backlog` tasks and tasks where a `todo` subtask can be edited. Without a change option, the CLI asks which fields to change and prompts for each one with its current value. It does not prompt for deliverables. A `--json` or `-n` call without a change option fails with `tasks.update_required`. A position that is not a positive integer fails with `tasks.position_invalid`. A title, brief, or position change where the task and subtask statuses do not permit it fails with `tasks.not_in_backlog`. A deliverables change for a subtask that has started fails with `tasks.deliverables_locked` and leaves the stored list unchanged. The command never reports success while ignoring that list. An unreadable or malformed file fails with `tasks.deliverables_invalid`.

## orbit tasks:subtask:destroy

Delete a subtask while its task is in `backlog`. The later subtasks move up to close the gap.

```bash theme={"dark"}
orbit tasks:subtask:destroy [group] [subtask] [--yes] [--json]
```

| Option | Meaning |
| - | - |
| `--yes` | Confirm without a prompt. Required for `--json` and `-n` calls. |

In a terminal, the task list shows only `backlog` tasks. The question names the subtask and its task and defaults to No. Consent failures match `tasks:cancel`. JSON returns the deleted subtask.

## orbit tasks:subtask:cancel

Cancel a `todo` or `running` subtask. A `todo` subtask can be cancelled in a `todo`, `running`, `reviewing`, `settling`, or `waiting_for_review` task; cancellation marks it `cancelled`, starts nothing, and does not ask for assistance. If it was the last open subtask, the task settles as after a completed subtask. Cancelling a running subtask stops its implementer and running check, keeps the task and its Instance, and starts the next `todo` subtask. The task settles only when no open subtask remains. The [tasks reference](/docs/reference/tasks#cancel-a-subtask) owns these effects.

```bash theme={"dark"}
orbit tasks:subtask:cancel [group] [subtask] [--yes] [--json]
```

| Option | Meaning |
| - | - |
| `--yes` | Confirm without a prompt. Required for `--json` and `-n` calls. |

In a terminal, the task list shows tasks with a cancellable `todo` or `running` subtask, and the subtask list shows those subtasks. The question names the subtask and its task and defaults to No. Consent failures match `tasks:cancel`. The CLI shows the cancelled subtask. JSON returns it.

| Error code | Meaning |
| - | - |
| `tasks.subtask_not_running` | The subtask is neither a cancellable `todo` subtask nor a `running` subtask, or it moved on while Orbit stopped it. |
| `tasks.subtask_interrupt_failed` | Orbit could not stop the implementer or the check. The subtask stays `running`. Retry, or cancel the task. |

## orbit tasks:comment:create

Post a typed comment on a subtask. An `assistance_requested` comment flags the subtask and its task as a direction request and notifies Coder once. A `resolution` comment clears the flag. It goes to the subtask's reviewer on a direction request, and to the blocked agent thread on a failure. The [tasks reference](/docs/reference/tasks#assistance-and-resolution) owns these effects.

```bash theme={"dark"}
orbit tasks:comment:create [group] [subtask] [--type=TYPE] [--body=TEXT] [--author=NAME] [--agent-thread=ID] [--json]
```

| Input | Default | Meaning |
| - | - | - |
| `--type=TYPE` | prompt | `assistance_requested` or `resolution`. |
| `--body=TEXT` | prompt | Comment text, at most 100,000 characters. |
| `--author=NAME` | prompt, with your local user name | Who wrote the comment, at most 255 characters. |
| `--agent-thread=ID` | none | Numeric Orbit agent thread ID that the comment concerns. |

A `--json` or `-n` call fails with `tasks.comment_type_required`, `tasks.comment_body_required`, or `tasks.comment_author_required` when a value is missing. An unknown type fails with `tasks.comment_type_invalid`. An agent thread ID that is not a positive integer fails with `tasks.agent_thread_invalid`.

## orbit tasks:comment:list

List a subtask's comments, newest first. The list includes the turn receipts that its agents stored.

```bash theme={"dark"}
orbit tasks:comment:list [group] [subtask] [--json]
```

Human output prints one header line for each comment, with its time, type, author, review attempt, and commit when present. The full body follows, indented by two spaces.

## orbit tasks:question:list

List the questions that implementers and reviewers asked, newest first, across every task you can read. Each question marks a subtask that its brief did not fully decide.

```bash theme={"dark"}
orbit tasks:question:list [--project=ID] [--cause=CAUSE] [--status=STATUS] [--since=DATE] [--json]
```

| Option | Default | Effect |
| - | - | - |
| `--project=ID` | every Project | Only questions from this Project's tasks. |
| `--cause=CAUSE` | every cause | `brief_unclear`, `contract_gap`, `scope`, `environment`, or `missed_contract`. |
| `--status=STATUS` | every status | `open`, `escalated`, `answered`, or `superseded`. |
| `--since=DATE` | no limit | Only questions asked on or after this ISO 8601 date or time. |

An invalid filter fails with `tasks.project_invalid`, `tasks.cause_invalid`, `tasks.status_invalid`, or `tasks.since_invalid` before the request.

Human output prints one header line for each question, with its time, task and subtask reference, asker, status, and cause. The question and the answer follow, each indented by two spaces. An empty list says `No questions match.` JSON holds the records under `questions`. The [tasks reference](/docs/reference/tasks#questions) defines each field, the relay routes, and the consult limit. The limit counts the consult records of the current implementer attempt, and a relay does not count. A direction resolution does not start a new implementer attempt. [Migrate open requests](/docs/reference/tasks#migrate-open-requests) names `2026_10_07_000000_create_task_questions` before `2026_10_07_000001_add_assistance_kind_to_tasks`.

## orbit tasks:question:close

Close a stale question that no one still has to answer. Use it when a resolution already answered the question but the record stayed `escalated`, or when a later subtask made the question moot.

```bash theme={"dark"}
orbit tasks:question:close [question] [--status=STATUS] [--reason=TEXT] [--json]
```

| Argument or option | Prompt | Effect |
| - | - | - |
| `question` | a list of open and escalated questions | The numeric question ID. |
| `--status=STATUS` | `superseded` or `answered` | `superseded` when nobody has to answer the question, `answered` when the reason is its answer. |
| `--reason=TEXT` | multiline text | Why the question is closed, at most 2,000 characters. It becomes the question's answer. |

In a terminal the command prompts for each omitted input. A noninteractive call fails before the request with `tasks.question_required`, `tasks.status_required`, or `tasks.reason_required`, and an invalid value fails with `tasks.question_invalid`, `tasks.status_invalid`, or `tasks.reason_invalid`. A question that is already `answered` or `superseded` fails with `tasks.question_closed`, unless the status and the reason are the same as before. Then the command returns the question unchanged. The command needs Gateway access.

Human output prints the closed question as `tasks:question:list` does. JSON returns the question record. [Close a question](/docs/reference/tasks#close-a-question) describes what closing changes and what it leaves alone.

## orbit tasks:agents

List a task's agent threads: each subtask's reviewer and implementer, including finished threads.

```bash theme={"dark"}
orbit tasks:agents [group] [--json]
```

The table shows the thread ID, role, subtask ID, driver, model, state, tokens, uncached input, cached input, output, model calls, peak context, line diff, and observation time. An unknown token field is a blank cell. JSON output includes `input_tokens`, `cached_input_tokens`, `output_tokens`, `model_calls`, and `peak_context_tokens`, each null when the driver did not report it. The [thread token metrics](/docs/reference/tasks#thread-token-metrics) define the fields. The latest error of each thread follows the table. The Gateway's conversation stream for a thread has no CLI command; the web task board shows the cumulative total.

## orbit tasks:definition:list

List task definitions. The command does not start a task. Any authorized peer can run it.

```bash theme={"dark"}
orbit tasks:definition:list [--project=ID] [--json]
```

| Option | Meaning |
| - | - |
| `--project=ID` | Only definitions of this numeric Project ID. |

The CLI does not prompt for the filter. An invalid Project ID fails with `tasks.project_invalid` before the request. Human output is a table of Project, name, title, and status. An empty table says `No task definitions were found.` JSON returns the records under `task_definitions`. While the extension is off, the command fails with `extension.disabled`.

## orbit tasks:definition:show

Show one task definition. The command does not start a task. Any authorized peer can run it.

```bash theme={"dark"}
orbit tasks:definition:show [--project=ID] [name] [--json]
```

| Input | Default | Meaning |
| - | - | - |
| `--project=ID` | prompt | Numeric Project ID. In a terminal, the CLI lists Projects to select from. |
| `name` | prompt | Definition name. In a terminal, the CLI lists that Project's definitions to select from. |

With `--json` or `-n`, an omitted Project fails with `tasks.project_required` and an omitted name fails with `tasks.definition_name_required`. A Project ID that is not a positive integer fails with `tasks.project_invalid`. A name outside the [definition name rules](/docs/reference/tasks#fields) fails with `tasks.definition_name_invalid` before the request. An empty definition list stops with `No matching records were found.`

Human output is a detail tree of the definition fields. JSON is the definition record. A missing definition fails with `http.404`. While the extension is off, the command fails with `extension.disabled`.

## orbit tasks:definition:create

Create a task definition from a JSON file. The command does not start a task. It needs Gateway access.

```bash theme={"dark"}
orbit tasks:definition:create [--project=ID] [--definition=FILE] [--json]
```

| Input | Default | Meaning |
| - | - | - |
| `--project=ID` | prompt | Numeric Project ID. In a terminal, the CLI lists Projects to select from. |
| `--definition=FILE` | prompt | JSON file of the whole definition. The file's `name` is the definition name. |

With `--json` or `-n`, an omitted Project fails with `tasks.project_required` and an omitted file fails with `tasks.definition_file_required`. An unreadable file, or a file that is not a JSON object, fails with `tasks.definition_file_invalid`. The Gateway returns `tasks.definition_invalid` when the definition breaks a validation rule, and `tasks.definition_exists` when the Project already uses the name. Another caller receives `node_access.required`. While the extension is off, the command fails with `extension.disabled`. After success, human output matches `tasks:definition:show`. JSON is the stored definition.

## orbit tasks:definition:update

Replace one task definition from a JSON file. The command does not start a task. It needs Gateway access. Update replaces the whole definition.

```bash theme={"dark"}
orbit tasks:definition:update [--project=ID] [name] [--definition=FILE] [--json]
```

| Input | Default | Meaning |
| - | - | - |
| `--project=ID` | prompt | Numeric Project ID. In a terminal, the CLI lists Projects to select from. |
| `name` | prompt | Definition name, selected as in `tasks:definition:show`. |
| `--definition=FILE` | prompt | JSON file that replaces the whole definition. If the file includes `name`, it must equal the argument. |

A file `name` that differs from the argument fails with `tasks.definition_name_mismatch` before the request. With `--json` or `-n`, an omitted Project, name, or file fails with `tasks.project_required`, `tasks.definition_name_required`, or `tasks.definition_file_required`. An unreadable file, or a file that is not a JSON object, fails with `tasks.definition_file_invalid`. The Gateway returns `tasks.definition_invalid` when the replacement breaks a validation rule, and `http.404` when that name is missing. Another caller receives `node_access.required`. While the extension is off, the command fails with `extension.disabled`. Human output and JSON match create.

## orbit tasks:definition:destroy

Delete one task definition. The command does not start a task, and it does not delete a task. It needs Gateway access.

```bash theme={"dark"}
orbit tasks:definition:destroy [--project=ID] [name] [--yes] [--json]
```

| Input | Default | Meaning |
| - | - | - |
| `--project=ID` | prompt | Numeric Project ID. In a terminal, the CLI lists Projects to select from. |
| `name` | prompt | Definition name, selected as in `tasks:definition:show`. |
| `--yes` | prompt | Confirm without a prompt. Required for `--json` and `-n` calls. |

In a terminal, the question names the definition and its Project and defaults to No. A `--json` or `-n` call without `--yes` fails with `input.confirmation_required`. Declining fails with `input.cancelled`. Neither sends a request. A missing definition fails with `http.404`. Another caller receives `node_access.required`. While the extension is off, the command fails with `extension.disabled`. JSON returns the deleted definition.

## Related

* [`project`](/docs/cli/project) lists the Projects that a task can belong to.
* [`instance`](/docs/cli/instance) shows the task workspace Instance of a running task.
* The [tasks reference](/docs/reference/tasks) explains task definitions, Backlog preparation, the scheduler, turn receipts, review, and pull requests.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.