Scripting recipes

These recipes run on a machine where you have signed in with langalpha login, or against a self-hosted server that asks for no sign-in. They use --json and the CLI’s 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.

Start a thread and wait for the answer

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

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:

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:

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:

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

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:

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:

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:

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:

langalpha threads retry "$thread" --wait

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