Threads & Results
A thread is one execution of a script version. Threads run in the cloud — you create one, the platform schedules and runs it as a durable, resumable unit, and you read status, events, results, and step detail back over the CLI. There is nothing to configure about where it runs.
thread create <script>
Start execution and return thread metadata immediately, without waiting for it to finish.
| Flag | Meaning |
|---|---|
--input | Inline JSON or @file |
--version | Script version (0 = active) |
--env | Load the effective merged environment into the run |
dodil scriptum thread create invoice-parser \
--input @./prod_input.json \
--version 3 \
--env \
-o jsonthread run <script>
Create a thread and follow it to a terminal state in one command. Inherits the
create flags and adds:
| Flag | Meaning |
|---|---|
--result | Print the final result after completion |
--save | Save output and step files to a directory |
dodil scriptum thread run invoice-parser --input @./input.json --result
dodil scriptum thread run invoice-parser --input @./input.json --result --save ./out/run-001run attempts a WatchThread stream first and falls back to polling
thread get if the stream cannot be established. It stops at a terminal status
(completed, failed, cancelled).
thread watch <thread-id>
Follow an existing thread created elsewhere. Stream-first with polling fallback; stops on a terminal status.
dodil scriptum thread watch thr_abc123thread get <thread-id>
Query current status and step progress.
dodil scriptum thread get thr_abc123 -o yamlthread list
Find recent runs by script or status.
| Flag | Meaning |
|---|---|
--script | Filter by script name |
--status | Filter by thread status |
--page-size | Max number of results |
dodil scriptum thread list --script invoice-parser --status failed --page-size 100thread result <thread-id>
Fetch the final output and a summary.
| Flag | Meaning |
|---|---|
--save | Write output and step files to a directory |
dodil scriptum thread result thr_abc123
dodil scriptum thread result thr_abc123 --save ./out/thr_abc123--save writes output.json, summary.json, and a steps/ directory. When
the output is flagged truncated, --save automatically streams the full
payload before writing it.
thread steps <thread-id>
Inspect step progress. The default is a summary table; flags narrow or expand it.
| Flag | Meaning |
|---|---|
--step | Show one step’s detail by path (e.g. 1.2.0) |
--detail | Stream full input/output for every step |
dodil scriptum thread steps thr_abc123
dodil scriptum thread steps thr_abc123 --step 1.2.0
dodil scriptum thread steps thr_abc123 --detailStep detail includes the primitive, tool, status, duration, input/output (truncated for display), and any execution ID or logs URL the runtime attaches.
End to end
# Start, watch, capture everything
dodil scriptum thread run invoice-parser \
--input @./invoice_42.json \
--env \
--result \
--save ./out/invoice-42
# Investigate a failed run
dodil scriptum thread get thr_failed_01
dodil scriptum thread steps thr_failed_01 --detailCaveats
- There is no
thread cancelorthread resumesubcommand in the CLI. Use the API for both — see API Gaps & Workarounds. - Large outputs may be returned truncated by the unary
resultcall; use--save, which streams the full payload.
See also
- Run, observe, retrieve — the full recipe.
- Human-in-the-loop resume — handling
askpauses. - Debugging a failed thread — triage playbook.
- API Reference — Threads & Results — the underlying RPCs.