# Thread commands > Reference for langalpha threads, the CLI commands that start, follow, answer, retry, cancel, archive and delete LangAlpha threads and their turns. Source: https://docs.langalpha.ai/cli/threads/ A [thread](https://docs.langalpha.ai/concepts/threads-and-turns/) is one conversation in a workspace, and a turn is one run of the agent answering it. Each command also takes the [global options](https://docs.langalpha.ai/cli/overview/#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](https://docs.langalpha.ai/cli/scripting/#follow-a-turn-as-json-events). `--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. ```sh 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. ```sh langalpha threads show ``` 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. ```sh langalpha threads new -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](https://docs.langalpha.ai/concepts/chief-of-staff-and-analysts/). | | `-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. | ```sh 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. ```sh langalpha threads send [-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](https://docs.langalpha.ai/concepts/threads-and-turns/#sending-a-message-while-the-agent-works) that turn instead of starting a second one. ## threads follow Stream the turn a thread is running. ```sh langalpha threads follow ``` 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. ```sh langalpha threads retry [-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`. ```sh langalpha threads approve [--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](https://docs.langalpha.ai/concepts/brokerages-and-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. ```sh langalpha threads reject [--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. ```sh langalpha threads cancel ``` 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. ```sh langalpha threads archive ``` An archived thread leaves the default list. `threads list -w WS --archived` shows it. ## threads delete Delete a thread and its conversation. ```sh langalpha threads delete [-y] ``` | Option | What it does | | --- | --- | | `-y`, `--yes` | Skip the confirmation. Required when no terminal is attached. | ## Related - [Threads and turns](https://docs.langalpha.ai/concepts/threads-and-turns/) - [Scripting recipes](https://docs.langalpha.ai/cli/scripting/) - [Workspace commands](https://docs.langalpha.ai/cli/workspaces/)