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 in the Workspace the terminal is standing in, 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`	Send new direction to the reply that is running. Atoi drops its current course and answers from your words; a reply has no separate stop.
`atoi thread retry`	Retry the last failed or stopped reply in a Thread.
`atoi thread react`	React to one message with an emoji.
`atoi thread answer`	Answer an open question in a Thread, the same way the app card does. thread get lists them under asks. A card with more than one question takes every answer in one call: repeat --question, each followed by its own --pick or --text, or pass them all in --answers.
`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 objects`	Read a Thread's objects in one pass: its messages, pending decisions, and open asks.
`atoi thread timings`	Read where the wait after each send went: the stages of a turn, in milliseconds from the moment the send was claimed. A stage nobody measured reads as a dash, never as zero.
`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>] [--workspace <id>] [--personal] [--limit <n>]

Flag	Type	Default	Values	What it does
`--project`	`string`			Select a Project by id.
`--workspace`	`string`			Answer one Workspace by id for this call; without it, the Workspace the terminal is standing in.
`--personal`	`boolean`			Answer Personal for this call, whatever the terminal is standing in.
`--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>] [--answers <question=pick,question=text:words>] [--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. After a --question, it answers that question.
`--text`	`string`			Add a written answer or a note next to the pick. After a --question, it answers that question.
`--question`	`string`			Name a question inside the request. Repeat it, each with its own --pick or --text, to answer every question at once.
`--answers`	`string`			Answer every question of one request at once: question=pick or question=text:words separated by commas, or JSON such as {"time":"B","timeZone":{"text":"New York"}}.
`--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> [--attach <path> ...] [--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.
`--attach`	`path`			Send a file with the message. Repeat the flag for more. Images, text, PDF, and JSON, 25MB each.
`--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> [--attach <path> ...] [--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.
`--attach`	`path`			Send a file with the message. Repeat the flag for more. Images, text, PDF, and JSON, 25MB each.
`--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`

Send new direction to the reply that is running. Atoi drops its current course and answers from your words. Use this when Atoi is working on the wrong thing and you do not want to wait for it to finish. A reply has no separate stop: steering is how you change it. A Task keeps its own stop, atoi task cancel.

atoi thread steer <thread-id> --prompt <text> [--attach <path> ...] [--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.
`--attach`	`path`			Send a file with the message. Repeat the flag for more. Images, text, PDF, and JSON, 25MB each.
`--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 "Start from the failing test instead." --json

{
  "tool": "atoi_threads",
  "arguments": {
    "action": "steer",
    "thread_id": "thr_9c4k",
    "prompt": "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 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. A Computer set to Ask is allowed only by you, signed in to Atoi, so the request for one names where to allow it instead.

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>]

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.
`--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 --json

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

#`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"
  }
}

#`thread objects`

Read a Thread's objects in one pass: its messages, pending decisions, and open asks.

atoi thread objects [<thread-id> | --thread <thread-id>] [--limit <n>]

Flag	Type	Default	Values	What it does
`--thread`	`string`			Select a Thread by id instead of a positional id.
`--limit`	`number`			Read at most this many 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 objects`

The MCP tool reads a Thread through get; objects is the terminal's one-pass read.

atoi thread objects thr_9c4k --json

#`thread timings`

Read where a send's time went, stage by stage, for a Thread's recent turns.

atoi thread timings [<thread-id> | --thread <thread-id>] [--limit <n>]

Flag	Type	Default	Values	What it does
`--thread`	`string`			Select a Thread by id instead of a positional id.
`--limit`	`number`			Read at most this many sends.
`--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 timings`

Each stage prints the elapsed time from the claim and, in brackets, what that stage itself cost. The bracketed number is the one that names what to fix: a large elapsed time usually inherits from the stage before it, while a large own cost is the stage to look at.

atoi thread timings thr_9c4k --limit 5 --json

{
  "tool": "atoi_threads",
  "arguments": {
    "action": "timings",
    "thread_id": "thr_9c4k",
    "limit": 5
  }
}

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

#thread objects

#Run thread objects

#thread timings

#Run thread timings