tasks family runs the operations of the Gateway tasks extension from the command line. Agents usually use the MCP server; 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 owns the lifecycle, the scheduler, and every Gateway rule that these commands reach.
Commands
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 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 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 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 sizes the group’s VM by these declarations at the claim and prepares the nodes nested in it.
Select a task or subtask
Agroup 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.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 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 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 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 includesassistance_kind and assistance_question on each task.
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.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 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 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 defines these fields.
orbit tasks:create
Create a task. It starts inbacklog unless you ask for todo.
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.
orbit tasks:update
Change a task’s title, brief, or status. Title and brief change only while the task is inbacklog. The status moves between backlog and todo. A move to todo asks the scheduler to claim the task.
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.
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 taskcancelled. Subtasks, comments, and agent thread records stay as history. Cancellation does not stop the external agent conversation.
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 describes.
orbit tasks:complete
Complete asettling 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 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.
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 describes.
orbit tasks:subtask:create
Append one subtask to a task at the next position, with statustodo. 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 owns that transition.
--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.
orbit tasks:subtask:update
Change a subtask’s title, brief, position, or deliverables while its task is inbacklog. 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.
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 inbacklog. The later subtasks move up to close the gap.
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 atodo 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 owns these effects.
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.
orbit tasks:comment:create
Post a typed comment on a subtask. Anassistance_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 owns these effects.
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.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.
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 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 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 stayedescalated, or when a later subtask made the question moot.
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 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.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 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.
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.
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 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.
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.
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.
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
projectlists the Projects that a task can belong to.instanceshows the task workspace Instance of a running task.- The tasks reference explains task definitions, Backlog preparation, the scheduler, turn receipts, review, and pull requests.