Thread commands

A thread is one conversation in a workspace, and a turn is one run of the agent answering it. Each command also takes the global options. Ids are the THREAD_ID column of threads list.

How a turn prints

threads new, send, retry, approve, reject and follow all run or watch a turn, and print it the same way:

By default the agent’s reply streams to your terminal as it is written. Its reasoning and tool calls are not shown.
--wait prints nothing until the turn ends, then only the reply. With --json it prints one object: thread_id, run_id, status, text, and when they apply interrupt, error and recovery.
--detach returns as soon as the server has started the turn and named its thread and run, and leaves the turn running. With --json it prints {"thread_id", "run_id", "status": "detached"}. Follow it later with threads follow.
--json alone prints every event of the stream as one JSON line, {"event": ..., ...}, which is what a script reading the live turn wants. See Scripting recipes.

--wait and --detach cannot be combined. Without --json or --detach, the thread id is printed to standard error at the end, so you can pick it up for the next command.

How the turn ended decides the exit code:

Ending	Exit code	What is printed
Finished	`0`	The reply.
Waiting for you	`6`	What the agent is waiting on, and the command that answers it.
Failed	`7`	The error, and how to run it again: `threads retry` when the server kept the failed run, or “send the message again” when it never started.
Cancelled	`7`	“Turn cancelled.”
Stream closed early	`1`	The turn may still be running; the command to follow it.

Closing the CLI, or losing the connection, does not stop a turn. It keeps running on the server, and threads follow picks it up again.

threads list

Your threads, newest first.

langalpha threads list [-w WS] [--archived] [--limit N]

Option	What it does
`-w`, `--workspace WS`	Only threads in this workspace: an id, its exact name, or `home`.
`--archived`	Archived threads instead. Needs `--workspace`.
`--limit N`	List at most this many. Defaults to 20.

Prints each thread’s id, title, status, workspace and last update.

threads show

A thread’s details.

langalpha threads show <id>

Prints the thread’s fields one per line; --json prints all of them, nested ones included.

threads new

Start a thread in a workspace with a message, and run its turn.

langalpha threads new <message...> -w WS [-m MODEL] [--wait] [--detach]

Option	What it does
`-w`, `--workspace WS`	Required. The workspace to start the thread in: an id, its exact name, or `home` to ask the Chief of Staff.
`-m`, `--model MODEL`	The model to run the turn on, as `models list` names it. Defaults to your default model.
`--wait`	Print only the reply, once the turn ends.
`--detach`	Return once the turn has started, with its thread and run.

langalpha threads new What changed in NVDA guidance this quarter -w NVDA --wait

threads send

Send a message to a thread, and run its turn.

langalpha threads send <id> <message...> [-m MODEL] [--wait] [--detach]

Option	What it does
`-m`, `--model MODEL`	The model to run the turn on.
`--wait`	Print only the reply, once the turn ends.
`--detach`	Return once the turn has started, with its thread and run.

If the thread is already running a turn, the message steers that turn instead of starting a second one.

threads follow

Stream the turn a thread is running.

langalpha threads follow <id>

Attaches to the thread’s latest turn and prints it from the start, then live until it ends, the same way threads new prints. Use it after --detach, after a dropped connection, or from another machine.

threads retry

Run a thread’s failed turn again.

langalpha threads retry <id> [-m MODEL] [--wait] [--detach]

Option	What it does
`-m`, `--model MODEL`	Run the retry on this model instead.
`--wait`	Print only the reply, once the turn ends.
`--detach`	Return once the turn has started, with its thread and run.

A failed turn says when retry applies. A turn that never started has nothing to retry: send the message again with threads send.

threads approve

Approve what the agent is waiting on, or answer its question with --message.

langalpha threads approve <id> [--message M] [--interrupt I] [--wait] [--detach]

Option	What it does
`--message M`	The answer to the agent’s question.
`--interrupt I`	Which request to answer, when the thread waits on several. Defaults to the latest.
`--wait`	Print only the reply, once the resumed turn ends.
`--detach`	Return once the resumed turn has started.

The CLI asks the server what the thread is waiting on now, so you can answer from any machine, not only the one that started the turn. An approval approves every action in the request. A thread that is not waiting for an answer exits with code 5.

Brokerage orders are the exception: an order is approved or rejected only in the LangAlpha app, and the command exits with code 3 when the thread waits on one.

threads reject

Reject what the agent is waiting on, or skip its question.

langalpha threads reject <id> [--message M] [--interrupt I] [--wait] [--detach]

Option	What it does
`--message M`	Why, for the agent.
`--interrupt I`	Which request to answer, when the thread waits on several. Defaults to the latest.
`--wait`	Print only the reply, once the resumed turn ends.
`--detach`	Return once the resumed turn has started.

A rejected question reaches the agent as skipped.

threads cancel

Stop the turn a thread is running.

langalpha threads cancel <id>

Asks the server to stop the turn, as Stop does in the app. The work saved so far stays in the thread.

threads archive

Archive a thread.

langalpha threads archive <id>

An archived thread leaves the default list. threads list -w WS --archived shows it.

threads delete

Delete a thread and its conversation.

langalpha threads delete <id> [-y]

Option	What it does
`-y`, `--yes`	Skip the confirmation. Required when no terminal is attached.