Task CLI reference

Start, inspect, continue, cancel, apply, and publish proof-bearing Tasks.

On this page

Use this page to inspect every public atoi task command, its accepted flags, and one runnable example. Return to the CLI reference index to choose another command group.

atoi taskStart, inspect, continue, cancel, apply, and publish proof-bearing Tasks.

Command	What it does
`atoi task list`	List Tasks, optionally within one Project.
`atoi task start`	Start durable implementation work in a Project.
`atoi task get`	Read Task state, result, changes, checks, asks, and proof.
`atoi task changes`	Inspect the materialized, proof-linked Task change set.
`atoi task apply`	Apply a verified change set to the matching local repository.
`atoi task draft-pr`	Publish a verified change set to a proof-backed draft pull request.
`atoi task wait`	Poll until a Task needs you, completes, or fails.
`atoi task cancel`	Cancel a Task that is still active.
`atoi task continue`	Continue completed or interrupted work with a new objective.

#`task list`

List Tasks, optionally within one Project.

atoi task list [--project <project-id>] [--limit <n>]

Flag	Type	Default	Values	What it does
`--project`	`string`			Select a Project by id.
`--limit`	`number`			Limit the number of returned records.
`--json`	`boolean`	`false`		Emit the canonical JSON envelope.
`--ndjson`	`boolean`	`false`		Emit one canonical JSON envelope per line.
`--format`	`string`	`text`	`text`, `json`	Choose human text or the JSON envelope.
`--help` `-h`	`boolean`			Show command help.

#Run `task list`

atoi task list --project prj_8k2v --json

{
  "tool": "atoi_tasks",
  "arguments": {
    "action": "list",
    "project_id": "prj_8k2v",
    "limit": 10
  }
}

#`task start`

Start durable implementation work in a Project.

atoi task start --project <project-id> (--prompt <text> | --brief <text>) [--title <title>] [--model <model-id>] [--profile <profile>] [--place <place>] [--computer <computer-id>] [--confirm]

Flag	Type	Default	Values	What it does
`--project` required	`string`			Select the Project that owns the Task.
`--prompt`	`string`			State the Task objective.
`--brief`	`string`			State the Task objective with the compatibility flag.
`--title`	`string`			Set a Task title.
`--model`	`string`			Select a model id.
`--profile`	`string`			Select the Task safety profile.
`--place`	`string`			Choose cloud, none, host, or a Computer name.
`--computer`	`string`			Select an exact Computer id for host placement.
`--confirm`	`boolean`			Confirm a placement choice when Atoi requires it.
`--json`	`boolean`	`false`		Emit the canonical JSON envelope.
`--ndjson`	`boolean`	`false`		Emit one canonical JSON envelope per line.
`--format`	`string`	`text`	`text`, `json`	Choose human text or the JSON envelope.
`--help` `-h`	`boolean`			Show command help.

#Run `task start`

atoi task start --project prj_8k2v --prompt "Audit the release state and return evidence." --profile safe --place cloud --json

{
  "tool": "atoi_tasks",
  "arguments": {
    "action": "start",
    "project_id": "prj_8k2v",
    "prompt": "Audit the release state and return evidence.",
    "safety_profile": "safe",
    "idempotency_key": "task_release_1"
  }
}

#`task get`

Read Task state, result, changes, checks, asks, and proof.

atoi task get <task-id> [--task <task-id>]

Flag	Type	Default	Values	What it does
`--task`	`string`			Select a Task by id instead of a positional id.
`--json`	`boolean`	`false`		Emit the canonical JSON envelope.
`--ndjson`	`boolean`	`false`		Emit one canonical JSON envelope per line.
`--format`	`string`	`text`	`text`, `json`	Choose human text or the JSON envelope.
`--help` `-h`	`boolean`			Show command help.

#Run `task get`

atoi task get tsk_3m9q --json

{
  "tool": "atoi_tasks",
  "arguments": {
    "action": "get",
    "task_id": "tsk_7m3q"
  }
}

#`task changes`

Inspect the materialized, proof-linked Task change set.

atoi task changes <task-id> [--task <task-id>]

Flag	Type	Default	Values	What it does
`--task`	`string`			Select a Task by id instead of a positional id.
`--json`	`boolean`	`false`		Emit the canonical JSON envelope.
`--ndjson`	`boolean`	`false`		Emit one canonical JSON envelope per line.
`--format`	`string`	`text`	`text`, `json`	Choose human text or the JSON envelope.
`--help` `-h`	`boolean`			Show command help.

#Run `task changes`

atoi task changes tsk_3m9q --json

{
  "tool": "atoi_tasks",
  "arguments": {
    "action": "changes",
    "task_id": "tsk_7m3q"
  }
}

#`task apply`

Apply a verified change set to the matching local repository.

atoi task apply <task-id> --confirm --expected-change-set-id <id> --expected-change-set-fingerprint <fingerprint> [--directory <path>] [--idempotency-key <key>]

Flag	Type	Default	Values	What it does
`--task`	`string`			Select a Task by id instead of a positional id.
`--confirm` required	`boolean`			Confirm the exact consequential action after you inspect its target.
`--expected-change-set-id` required	`string`			Confirm the change set id returned by task changes.
`--expected-change-set-fingerprint` required	`string`			Confirm the change set fingerprint returned by task changes.
`--directory`	`string`	`current directory`		Apply inside this matching local repository.
`--idempotency-key`	`string`			Reuse a mutation identity when you safely retry the same action.
`--json`	`boolean`	`false`		Emit the canonical JSON envelope.
`--ndjson`	`boolean`	`false`		Emit one canonical JSON envelope per line.
`--format`	`string`	`text`	`text`, `json`	Choose human text or the JSON envelope.
`--help` `-h`	`boolean`			Show command help.

#Run `task apply`

atoi task apply tsk_3m9q --confirm --expected-change-set-id chg_7p4d --expected-change-set-fingerprint 0123456789abcdef --directory . --json

{
  "tool": "atoi_tasks",
  "arguments": {
    "action": "apply",
    "task_id": "tsk_7m3q",
    "confirmation": true,
    "change_set_id": "cset_4v8p",
    "change_set_fingerprint": "sha256:7a1c",
    "applied_revision": "6d41b2e",
    "idempotency_key": "task_apply_1"
  }
}

#`task draft-pr`

Publish a verified change set to a proof-backed draft pull request.

atoi task draft-pr <task-id> --confirm --expected-change-set-id <id> --expected-change-set-fingerprint <fingerprint> [--head <branch>] [--title <title>] [--body <body>] [--idempotency-key <key>]

Flag	Type	Default	Values	What it does
`--task`	`string`			Select a Task by id instead of a positional id.
`--confirm` required	`boolean`			Confirm the exact consequential action after you inspect its target.
`--expected-change-set-id` required	`string`			Confirm the change set id returned by task changes.
`--expected-change-set-fingerprint` required	`string`			Confirm the change set fingerprint returned by task changes.
`--head`	`string`			Choose the draft pull request branch.
`--title`	`string`			Set the draft pull request title.
`--body`	`string`			Set the draft pull request body.
`--idempotency-key`	`string`			Reuse a mutation identity when you safely retry the same action.
`--json`	`boolean`	`false`		Emit the canonical JSON envelope.
`--ndjson`	`boolean`	`false`		Emit one canonical JSON envelope per line.
`--format`	`string`	`text`	`text`, `json`	Choose human text or the JSON envelope.
`--help` `-h`	`boolean`			Show command help.

#Run `task draft-pr`

atoi task draft-pr tsk_3m9q --confirm --expected-change-set-id chg_7p4d --expected-change-set-fingerprint 0123456789abcdef --head task/release-audit --json

{
  "tool": "atoi_tasks",
  "arguments": {
    "action": "draft-pr",
    "task_id": "tsk_7m3q",
    "confirmation": true,
    "head_branch": "atoi/release-audit",
    "pull_request_title": "Audit release state",
    "pull_request_body": "Adds the verified release audit.",
    "idempotency_key": "task_pr_1"
  }
}

#`task wait`

Poll until a Task needs you, completes, or fails.

atoi task wait <task-id> [--task <task-id>] [--timeout-ms <ms>] [--interval-ms <ms>]

Flag	Type	Default	Values	What it does
`--task`	`string`			Select a Task by id instead of a positional id.
`--timeout-ms`	`number`	`900000`		Stop polling after this many milliseconds.
`--interval-ms`	`number`	`2000`		Wait this many milliseconds between reads.
`--json`	`boolean`	`false`		Emit the canonical JSON envelope.
`--ndjson`	`boolean`	`false`		Emit one canonical JSON envelope per line.
`--format`	`string`	`text`	`text`, `json`	Choose human text or the JSON envelope.
`--help` `-h`	`boolean`			Show command help.

#Run `task wait`

atoi task wait tsk_3m9q --timeout-ms 300000 --json

{
  "tool": "atoi_tasks",
  "arguments": {
    "action": "get",
    "task_id": "tsk_7m3q"
  }
}

#`task cancel`

Cancel a Task that is still active.

atoi task cancel <task-id> [--task <task-id>]

Flag	Type	Default	Values	What it does
`--task`	`string`			Select a Task by id instead of a positional id.
`--json`	`boolean`	`false`		Emit the canonical JSON envelope.
`--ndjson`	`boolean`	`false`		Emit one canonical JSON envelope per line.
`--format`	`string`	`text`	`text`, `json`	Choose human text or the JSON envelope.
`--help` `-h`	`boolean`			Show command help.

#Run `task cancel`

atoi task cancel tsk_3m9q --json

{
  "tool": "atoi_tasks",
  "arguments": {
    "action": "cancel",
    "task_id": "tsk_7m3q",
    "confirmation": true,
    "idempotency_key": "task_cancel_1"
  }
}

#`task continue`

Continue completed or interrupted work with a new objective.

atoi task continue <task-id> (--prompt <text> | --brief <text>) [--title <title>] [--model <model-id>] [--profile <profile>] [--place <place>] [--computer <computer-id>] [--confirm]

Flag	Type	Default	Values	What it does
`--task`	`string`			Select a Task by id instead of a positional id.
`--prompt`	`string`			State the continuation objective.
`--brief`	`string`			State the continuation objective with the compatibility flag.
`--title`	`string`			Replace the Task title.
`--model`	`string`			Select a model id.
`--profile`	`string`			Select the Task safety profile.
`--place`	`string`			Choose cloud, none, host, or a Computer name.
`--computer`	`string`			Select an exact Computer id for host placement.
`--confirm`	`boolean`			Confirm a placement choice when Atoi requires it.
`--json`	`boolean`	`false`		Emit the canonical JSON envelope.
`--ndjson`	`boolean`	`false`		Emit one canonical JSON envelope per line.
`--format`	`string`	`text`	`text`, `json`	Choose human text or the JSON envelope.
`--help` `-h`	`boolean`			Show command help.

#Run `task continue`

atoi task continue tsk_3m9q --prompt "Apply the review findings and rerun checks." --place cloud --json

{
  "tool": "atoi_tasks",
  "arguments": {
    "action": "continue",
    "task_id": "tsk_7m3q",
    "prompt": "Also check the candidate tag.",
    "idempotency_key": "task_continue_1"
  }
}

Was this useful?

#task list

#Run task list

#task start

#Run task start

#task get

#Run task get

#task changes

#Run task changes

#task apply

#Run task apply

#task draft-pr

#Run task draft-pr

#task wait

#Run task wait

#task cancel

#Run task cancel

#task continue

#Run task continue