Thread and Result Commands

Last validated: 2026-05-14

This page covers execution commands for creating, monitoring, and extracting thread outputs.

1) thread create <script>

Use case:

• Start execution and return thread metadata immediately.

Flags:

• --input: inline JSON or @file
• --version: script version (0 = active)
• --mode: local or cloud
• --timeout: duration string, for example 5m
• --env: load environment variables

Example:

dodil scriptum thread create invoice-parser \
  --input @./prod_input.json \
  --version 3 \
  --env \
  -o json

2) thread run <script>

Use case:

• Create thread and follow execution to terminal state in one command.

Flags:

• Inherits create flags: --input, --version, --mode, --timeout, --env
• --result: fetch and print result after completion
• --save: save output and step files to directory

Examples:

dodil scriptum thread run invoice-parser --input @./input.json --result
dodil scriptum thread run invoice-parser --input @./input.json --result --save ./out/run-001

Runtime behavior:

• Attempts WatchThread stream first.
• Falls back to polling (thread get) if stream setup fails.

3) thread watch <thread-id>

Use case:

• Follow an existing thread created elsewhere.

Example:

dodil scriptum thread watch thr_abc123

Behavior:

• Stream-first, polling fallback.
• Stops on terminal status (completed, failed, cancelled).

4) thread get and thread list

thread get <thread-id>

Use case:

• Query current status and step progress.

Example:

dodil scriptum thread get thr_abc123 -o yaml

thread list

Use case:

• Find recent runs by script or status.

Flags:

• --script: script name filter
• --status: thread status filter
• --page-size: max results

Example:

dodil scriptum thread list --script invoice-parser --status failed --page-size 100

5) Result Retrieval Commands

thread result <thread-id>

Use case:

• Fetch final output and summary details.

Flags:

• --save: write output and step files to disk

Examples:

dodil scriptum thread result thr_abc123
dodil scriptum thread result thr_abc123 --save ./out/thr_abc123

If output_truncated=true:

• CLI automatically streams full output when using --save.

thread steps <thread-id>

Use cases:

• View step summary table.
• Inspect one step by path.
• Stream full per-step details.

Flags:

• --step: exact step path (for example 1.2.0)
• --detail: stream detailed input/output for all steps

Examples:

dodil scriptum thread steps thr_abc123
dodil scriptum thread steps thr_abc123 --step 1.2.0
dodil scriptum thread steps thr_abc123 --detail

6) End-to-End Thread Example

# Start and watch
dodil scriptum thread run invoice-parser \
  --input @./invoice_42.json \
  --env \
  --result \
  --save ./out/invoice-42
 
# Investigate failed run
dodil scriptum thread get thr_failed_01
dodil scriptum thread steps thr_failed_01 --detail

7) Important Caveats

• --mode and --timeout map to API fields, but current backend does not fully enforce them in scheduling.
• No CLI command exists for ResumeThread yet; use gRPC/HTTP workaround in gaps guide.
• No CLI command exists for CancelThread; server API is currently unimplemented.