Thread CLI reference

Resolve, read, message, steer, answer, and act on a Workspace Thread.

Use this page to inspect every public atoi thread command, its accepted flags, and one runnable example.

atoi threadResolve, read, message, steer, answer, and act on a Workspace Thread.

Command	What it does
`atoi thread resolve`	Resolve a Workspace to the one Thread it drives.
`atoi thread list`	List governed Threads, optionally within one Project.
`atoi thread get`	Read one Thread and a bounded message page.
`atoi thread send`	Send a message and wait for its receipt-backed result.
`atoi thread reply`	Answer one message in a Thread and wait for its receipt.
`atoi thread steer`	Stop the reply that is running and send new direction in its place.
`atoi thread retry`	Retry the last failed or stopped reply in a Thread.
`atoi thread stop`	Stop the active reply in a Thread.
`atoi thread react`	React to one message with an emoji.
`atoi thread answer`	Answer one open question in a Thread, the same way the app card does. thread get lists them under asks.
`atoi thread approve`	Approve one Ask waiting in a Thread, after you read what it will do.
`atoi thread deny`	Deny one Ask waiting in a Thread, after you read what it will do.
`atoi thread launch`	Launch a Task from a Thread and choose where it runs.
`atoi thread pin`	Pin a Thread and read back the app-visible state.
`atoi thread unpin`	Unpin a Thread and read back the app-visible state.

#`thread resolve`

Resolve a Workspace to the one Thread it drives.

atoi thread resolve [<workspace-id>] [--workspace <workspace-id>]

Flag	Type	Default	Values	What it does
`--workspace`	`string`			Select the Workspace whose one Thread to act on, instead of a Thread 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 `thread resolve`

atoi thread resolve wsp_3f8a --json

{
  "tool": "atoi_threads",
  "arguments": {
    "action": "resolve",
    "workspace_id": "wsp_3f8a"
  }
}

#`thread list`

List governed Threads, optionally within one Project.

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

Flag	Type	Default	Values	What it does
`--project`	`string`			Select a Project by id.
`--limit`	`number`			Return between 1 and 200 Threads.
`--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 `thread list`

atoi thread list --project prj_8k2v --json

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

#`thread get`

Read one Thread and a bounded message page.

atoi thread get <thread-id> [--thread <thread-id>] [--workspace <workspace-id>] [--limit <n>]

Flag	Type	Default	Values	What it does
`--thread`	`string`			Select a Thread by id instead of a positional id.
`--workspace`	`string`			Select the Workspace whose one Thread to act on, instead of a Thread id.
`--limit`	`number`			Return between 1 and 200 messages.
`--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 `thread get`

atoi thread get thr_9c4k --json

{
  "tool": "atoi_threads",
  "arguments": {
    "action": "get",
    "thread_id": "thr_9c4k"
  }
}

#`thread answer`

Answer the Thread's open question from the terminal. thread get lists each pending question under asks with its request id and lettered options. thread answer resolves one through the same path the app card uses, so an interview that creates an Automation lands exactly as it would from the app. Pick by letter, option id, or label, and add a note with --text.

atoi thread answer <thread-id> --request <request-id> [--pick <letter|option-id>[,…]] [--text <answer>] [--question <question-id>] [--thread <thread-id>] [--workspace <workspace-id>]

Flag	Type	Default	Values	What it does
`--thread`	`string`			Select a Thread by id instead of a positional id.
`--workspace`	`string`			Select the Workspace whose one Thread to act on, instead of a Thread id.
`--request` required	`string`			Name the question to answer.
`--pick`	`string`			Choose options by letter, id, or label; separate several with commas.
`--text`	`string`			Add a written answer or a note next to the pick.
`--question`	`string`			Name the question inside the request when it holds more than one.
`--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 `thread answer`

atoi thread answer thr_9c4k --request ask_6m2d --pick B --text "Only on weekdays" --json

#`thread send`

Send a message and wait for its receipt-backed result.

atoi thread send <thread-id> --prompt <text> [--thread <thread-id>] [--workspace <workspace-id>] [--model <model-id>] [--reasoning <strength>] [--context-ref <json> ...] [--context-refs <json-array>] [--reply-to <message-id>] [--delivery-id <key>] [--idempotency-key <key>]

Flag	Type	Default	Values	What it does
`--thread`	`string`			Select a Thread by id instead of a positional id.
`--workspace`	`string`			Select the Workspace whose one Thread to act on, instead of a Thread id.
`--prompt` required	`string`			Set the message text.
`--model`	`string`			Select a model id.
`--reasoning`	`string`		`default`, `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`	Select the model reasoning strength.
`--context-ref`	`json`			Attach one context reference as JSON. Repeat the flag for more.
`--context-refs`	`json`			Attach an array of context references as JSON.
`--reply-to`	`string`			Answer one message by id.
`--delivery-id`	`string`			Set the exact delivery identity.
`--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 `thread send`

atoi thread send thr_9c4k --prompt "Summarize the release blockers." --delivery-id msg_release_1 --json

{
  "tool": "atoi_threads",
  "arguments": {
    "action": "send",
    "thread_id": "thr_9c4k",
    "prompt": "Summarize the release blockers.",
    "delivery_id": "msg_release_1"
  }
}

#`thread reply`

Answer one message in a Thread and wait for its receipt. Name the message with --reply-to.

atoi thread reply <thread-id> --prompt <text> --reply-to <message-id> [--thread <thread-id>] [--workspace <workspace-id>] [--model <model-id>] [--reasoning <strength>] [--context-ref <json> ...] [--context-refs <json-array>] [--delivery-id <key>] [--idempotency-key <key>]

Flag	Type	Default	Values	What it does
`--thread`	`string`			Select a Thread by id instead of a positional id.
`--workspace`	`string`			Select the Workspace whose one Thread to act on, instead of a Thread id.
`--prompt` required	`string`			Set the reply text.
`--reply-to` required	`string`			Name the message you are answering.
`--model`	`string`			Select a model id.
`--reasoning`	`string`		`default`, `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`	Select the model reasoning strength.
`--context-ref`	`json`			Attach one context reference as JSON. Repeat the flag for more.
`--context-refs`	`json`			Attach an array of context references as JSON.
`--delivery-id`	`string`			Set the exact delivery identity.
`--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 `thread reply`

atoi thread reply thr_9c4k --reply-to msg_2v7b --prompt "Use the staging database." --json

{
  "tool": "atoi_threads",
  "arguments": {
    "action": "reply",
    "thread_id": "thr_9c4k",
    "reply_to_message_id": "msg_2v7b",
    "prompt": "Use the staging database.",
    "delivery_id": "msg_reply_1"
  }
}

#`thread steer`

Stop the reply that is running and send new direction in its place. Use this when Atoi is working on the wrong thing and you do not want to wait for it to finish.

atoi thread steer <thread-id> --prompt <text> [--thread <thread-id>] [--workspace <workspace-id>] [--model <model-id>] [--reasoning <strength>] [--context-ref <json> ...] [--context-refs <json-array>] [--reply-to <message-id>] [--delivery-id <key>] [--idempotency-key <key>]

Flag	Type	Default	Values	What it does
`--thread`	`string`			Select a Thread by id instead of a positional id.
`--workspace`	`string`			Select the Workspace whose one Thread to act on, instead of a Thread id.
`--prompt` required	`string`			Set the new direction.
`--model`	`string`			Select a model id.
`--reasoning`	`string`		`default`, `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`	Select the model reasoning strength.
`--context-ref`	`json`			Attach one context reference as JSON. Repeat the flag for more.
`--context-refs`	`json`			Attach an array of context references as JSON.
`--reply-to`	`string`			Answer one message by id.
`--delivery-id`	`string`			Set the exact delivery identity.
`--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 `thread steer`

atoi thread steer thr_9c4k --prompt "Stop and start from the failing test instead." --json

{
  "tool": "atoi_threads",
  "arguments": {
    "action": "steer",
    "thread_id": "thr_9c4k",
    "prompt": "Stop and start from the failing test instead.",
    "delivery_id": "msg_steer_1"
  }
}

#`thread retry`

Retry the last failed or stopped reply in a Thread.

atoi thread retry <thread-id> [--thread <thread-id>] [--workspace <workspace-id>] [--model <model-id>] [--reasoning <strength>]

Flag	Type	Default	Values	What it does
`--thread`	`string`			Select a Thread by id instead of a positional id.
`--workspace`	`string`			Select the Workspace whose one Thread to act on, instead of a Thread id.
`--model`	`string`			Select a model id.
`--reasoning`	`string`		`default`, `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`	Select the model reasoning strength.
`--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 `thread retry`

atoi thread retry thr_9c4k --reasoning high --json

{
  "tool": "atoi_threads",
  "arguments": {
    "action": "retry",
    "thread_id": "thr_9c4k",
    "delivery_id": "msg_release_2"
  }
}

#`thread stop`

Stop the active reply in a Thread.

atoi thread stop <thread-id> [--thread <thread-id>] [--workspace <workspace-id>]

Flag	Type	Default	Values	What it does
`--thread`	`string`			Select a Thread by id instead of a positional id.
`--workspace`	`string`			Select the Workspace whose one Thread to act on, instead of a Thread 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 `thread stop`

atoi thread stop thr_9c4k --json

{
  "tool": "atoi_threads",
  "arguments": {
    "action": "stop",
    "thread_id": "thr_9c4k"
  }
}

#`thread react`

React to one message with an emoji. Pass --reaction to say whether the emoji is added, removed, or toggled.

atoi thread react <thread-id> --message <message-id> --emoji <emoji> [--thread <thread-id>] [--workspace <workspace-id>] [--reaction <intent>] [--idempotency-key <key>]

Flag	Type	Default	Values	What it does
`--thread`	`string`			Select a Thread by id instead of a positional id.
`--workspace`	`string`			Select the Workspace whose one Thread to act on, instead of a Thread id.
`--message` required	`string`			Name the message to react to.
`--emoji` required	`string`			Set the emoji to apply.
`--reaction`	`string`		`add`, `remove`, `toggle`	Choose what the reaction does.
`--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 `thread react`

atoi thread react thr_9c4k --message msg_2v7b --emoji check --json

{
  "tool": "atoi_threads",
  "arguments": {
    "action": "react",
    "thread_id": "thr_9c4k",
    "message_id": "msg_2v7b",
    "emoji": "check",
    "reaction": "toggle",
    "idempotency_key": "react_msg_2v7b_1"
  }
}

#`thread approve`

Approve one Ask waiting in a Thread. Read what the Ask will do before you answer it, then pass --confirm. Add --always to approve that kind of action from now on.

atoi thread approve <thread-id> --request <request-id> --confirm [--thread <thread-id>] [--workspace <workspace-id>] [--always]

Flag	Type	Default	Values	What it does
`--thread`	`string`			Select a Thread by id instead of a positional id.
`--workspace`	`string`			Select the Workspace whose one Thread to act on, instead of a Thread id.
`--request` required	`string`			Name the Ask to answer.
`--always`	`boolean`			Approve this kind of action from now on.
`--confirm` required	`boolean`			Confirm the exact consequential action after you inspect its target.
`--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 `thread approve`

atoi thread approve thr_9c4k --request ask_6m2d --confirm --json

{
  "tool": "atoi_threads",
  "arguments": {
    "action": "approve",
    "thread_id": "thr_9c4k",
    "request_id": "ask_6m2d",
    "confirmation": true
  }
}

#`thread deny`

Deny one Ask waiting in a Thread. Denying stops that action and leaves the Thread where it was.

atoi thread deny <thread-id> --request <request-id> --confirm [--thread <thread-id>] [--workspace <workspace-id>]

Flag	Type	Default	Values	What it does
`--thread`	`string`			Select a Thread by id instead of a positional id.
`--workspace`	`string`			Select the Workspace whose one Thread to act on, instead of a Thread id.
`--request` required	`string`			Name the Ask to answer.
`--confirm` required	`boolean`			Confirm the exact consequential action after you inspect its target.
`--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 `thread deny`

atoi thread deny thr_9c4k --request ask_6m2d --confirm --json

{
  "tool": "atoi_threads",
  "arguments": {
    "action": "deny",
    "thread_id": "thr_9c4k",
    "request_id": "ask_6m2d",
    "confirmation": true
  }
}

#`thread launch`

Launch a Task from a Thread. Atoi asks where the Task should run unless you name a place, and the answer comes back as a placement request you can rerun with --place and --confirm.

atoi thread launch <thread-id> --prompt <text> [--thread <thread-id>] [--workspace <workspace-id>] [--project <project-id>] [--title <title>] [--model <model-id>] [--profile <profile>] [--place <where>] [--computer <computer-id>] [--confirm]

Flag	Type	Default	Values	What it does
`--thread`	`string`			Select a Thread by id instead of a positional id.
`--workspace`	`string`			Select the Workspace whose one Thread to act on, instead of a Thread id.
`--prompt` required	`string`			State the outcome the Task should reach.
`--brief`	`string`			Give the prompt under its older name.
`--project`	`string`			Select a Project by id.
`--title`	`string`			Name the Task.
`--model`	`string`			Select a model id.
`--profile`	`string`			Select the safety profile the Task runs under.
`--place`	`string`			Choose where the Task runs: none, cloud, host, or a computer name.
`--computer`	`string`			Name the computer when the place is host.
`--confirm`	`boolean`			Confirm the chosen place.
`--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 `thread launch`

atoi thread launch thr_9c4k --prompt "Ship the release notes." --place cloud --confirm --json

{
  "tool": "atoi_threads",
  "arguments": {
    "action": "launch",
    "thread_id": "thr_9c4k",
    "prompt": "Ship the release notes.",
    "place": "cloud",
    "confirmation": true
  }
}

#`thread pin`

Pin a Thread and read back the app-visible state.

atoi thread pin <thread-id> [--thread <thread-id>] [--workspace <workspace-id>] [--idempotency-key <key>]

Flag	Type	Default	Values	What it does
`--thread`	`string`			Select a Thread by id instead of a positional id.
`--workspace`	`string`			Select the Workspace whose one Thread to act on, instead of a Thread id.
`--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 `thread pin`

atoi thread pin thr_9c4k --json

{
  "tool": "atoi_threads",
  "arguments": {
    "action": "pin",
    "thread_id": "thr_9c4k",
    "idempotency_key": "thread_pin_1"
  }
}

#`thread unpin`

Unpin a Thread and read back the app-visible state.

atoi thread unpin <thread-id> [--thread <thread-id>] [--workspace <workspace-id>] [--idempotency-key <key>]

Flag	Type	Default	Values	What it does
`--thread`	`string`			Select a Thread by id instead of a positional id.
`--workspace`	`string`			Select the Workspace whose one Thread to act on, instead of a Thread id.
`--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 `thread unpin`

atoi thread unpin thr_9c4k --json

{
  "tool": "atoi_threads",
  "arguments": {
    "action": "unpin",
    "thread_id": "thr_9c4k",
    "idempotency_key": "thread_unpin_1"
  }
}

Read Run work from the terminal for the rest of this group, or the CLI reference index for every command.

Was this useful?

#thread resolve

#Run thread resolve

#thread list

#Run thread list

#thread get

#Run thread get

#thread answer

#Run thread answer

#thread send

#Run thread send

#thread reply

#Run thread reply

#thread steer

#Run thread steer

#thread retry

#Run thread retry

#thread stop

#Run thread stop

#thread react

#Run thread react

#thread approve

#Run thread approve

#thread deny

#Run thread deny

#thread launch

#Run thread launch

#thread pin

#Run thread pin

#thread unpin

#Run thread unpin