# Scripting recipes

> Recipes for scripting the LangAlpha CLI. Start a thread and wait for the answer, follow a turn as JSON events, create a cron automation, answer an approval, and retry a failed turn.

Source: https://docs.langalpha.ai/cli/scripting/

These recipes run on a machine where you have signed in with [`langalpha login`](https://docs.langalpha.ai/cli/signing-in/), or against a self-hosted server that asks for no sign-in. They use `--json` and the CLI's [exit codes](https://docs.langalpha.ai/cli/overview/#exit-codes), which are part of the CLI's contract. The examples use `jq` to read JSON. Commands that start a turn are covered in [Thread commands](https://docs.langalpha.ai/cli/threads/).

## Start a thread and wait for the answer

`--wait` prints only the agent's reply once the turn ends:

```sh
langalpha threads new "Summarize the risk factors in AAPL's latest 10-Q" -w AAPL --wait > summary.md
```

With `--json` you also get the thread id and how the turn ended, whatever the outcome:

```sh
langalpha threads new "Summarize the risk factors in AAPL's latest 10-Q" -w AAPL --wait --json > turn.json
code=$?
thread=$(jq -r .thread_id turn.json)
case $code in
  0) jq -r .text turn.json ;;
  6) echo "Waiting for an answer in thread $thread" ;;
  7) echo "Failed: $(jq -r .error turn.json)" ;;
  *) echo "Exit code $code" ;;
esac
```

## Start now, follow later

`--detach` returns as soon as the turn has started:

```sh
thread=$(langalpha threads new "Build a DCF for MSFT" -w MSFT --detach --json | jq -r .thread_id)
# ... later, or from another machine:
langalpha threads follow "$thread"
```

The turn runs on the server whether or not anything is following it.

## Follow a turn as JSON events

`--json` without `--wait` prints every event of the turn's stream as one JSON line, with the event's name in `event`:

```sh
langalpha threads follow "$thread" --json | jq -c 'select(.event == "tool_calls" or .event == "run_end")'
```

Events you will see include `metadata` (names the thread and run), `message_chunk` (a piece of the reply, or of the agent's reasoning when `content_type` says so), `tool_calls` and `tool_call_result`. The stream ends on exactly one of `interrupt` (waiting for you), `error` or `retry` (failed), or `run_end` (the run's own ending, with an `outcome`). If the connection drops before then, the command exits with code 1 and prints the command to follow the thread again.

## Create a cron automation

```sh
langalpha automations create --name "Morning brief" \
  --prompt "Summarize overnight moves and news for my watchlist" \
  --cron "30 8 * * 1-5" --timezone America/New_York -w home --json | jq -r .automation_id
```

The cron expression has five fields, and seconds are refused. `-w home` runs it as the Chief of Staff; name a workspace to run it there. To try it at once, then pause it until you are ready:

```sh
langalpha automations trigger <automation_id>
langalpha automations pause <automation_id>
```

For a single run at a set time, pass `--at 2026-11-03T13:30:00Z` instead of `--cron`.

## Answer an approval or a question

A turn that stops to ask you exits with code 6 and prints what it is waiting on, with the command that answers it:

```text
The agent asks: Which filing should I use?
  options: 10-K | 10-Q
Answer with: langalpha threads approve 3f2a... --message "<answer>"  (langalpha threads reject 3f2a... skips it)
```

Answer from any machine signed in as you:

```sh
langalpha threads approve "$thread" --message "10-K" --wait     # answer the question
langalpha threads approve "$thread" --wait                      # approve an action
langalpha threads reject "$thread" --message "Use the newer filing" --wait
```

When a thread waits on several requests, `--interrupt` picks one by id; the `interrupt.interrupt_id` field of a `--json` result names it. An order at a brokerage is the one thing the CLI cannot answer: approve or reject it in the LangAlpha app.

## Retry a failed turn

A failed turn exits with code 7 and says how to run it again. When the server kept the failed run:

```sh
langalpha threads retry "$thread" --wait
```

When the turn never started, there is nothing to retry; send the message again with `threads send`.

## Related

- [Thread commands](https://docs.langalpha.ai/cli/threads/)
- [Automation commands](https://docs.langalpha.ai/cli/automations/)
- [Signing in](https://docs.langalpha.ai/cli/signing-in/)