CLI Guide
Scriptum is part of the dodil CLI. Every command is invoked as:
dodil scriptum <group> <subcommand> [args] [flags]Scripts are authored once, run as durable threads, and managed entirely through this command group. Threads run in the cloud — there is nothing to host or schedule yourself.
Install and authenticate
Install and authenticate the dodil CLI — see
Install the CLI (macOS, Linux, Windows). It covers
dodil login, the shared config file, and the value-resolution order, all
single-sourced there. Scriptum is the dodil scriptum group.
Scriptum-specific notes:
- Endpoint default is
rpc.dev.dodil.io:443(gRPC, TLS on for:443). - Environment prefix is
SCRIPTUM_—SCRIPTUM_API_ENDPOINT,SCRIPTUM_ORG_ID,SCRIPTUM_ORG_NAME, andSCRIPTUM_TOKEN. The sharedDODIL_TOKENalso applies. - Config keys live under a
scriptum.*section, with aglobal.*fallback.
After login you can drop the auth flags and just run short commands:
dodil scriptum health
dodil scriptum doctordoctor validates config, endpoint, token, organization, server reachability,
and a lightweight auth check before you run anything real.
Command map
| Group | Subcommands | What it does |
|---|---|---|
script | create, get, list, delete | Script metadata and lifecycle |
draft | save, compile, test, publish, validate, fmt | Author and validate draft source |
version | list, get, rollback | Published version history and rollback |
thread | create, run, get, list, result, watch, steps | Execute and observe threads |
env | set, get, list, delete, import | Tenant environment variables |
tool | list | Browse the tool catalog |
config | init, view, set | Manage CLI configuration |
health | — | Server status, version, uptime |
doctor | — | Diagnose config, connectivity, and auth |
Detailed pages:
- Scripts & Drafts —
script,draft,version(authoring and release lifecycle). - Threads & Results —
thread(run, watch, retrieve results, inspect steps). - Env, Tools & Diagnostics —
env,tool,config,health,doctor. - API Gaps & Workarounds — what the CLI does not yet cover and how to reach those RPCs through the API.
Global flags
These work on every command, before or after the subcommand:
| Flag | Meaning | Example |
|---|---|---|
-o, --output | Output format: table, json, yaml, wide | -o json |
--api-endpoint | API endpoint (host:port) | --api-endpoint rpc.dev.dodil.io:443 |
--token | Auth token override | --token "$DODIL_TOKEN" |
--org | Organization ID override | --org org_abc |
--org-name | Organization name override | --org-name finance |
--debug | Enable debug output | --debug |
--timeout | Request timeout (duration) | --timeout 45s |
Use -o json for automation and parse responses deterministically; the default
table output is for humans.
Conventions used across the CLI
--inputaccepts inline JSON ('{"k":"v"}') or a file with the@prefix (@./input.json).--inputfiles ending in.scriptumare sent as DSL; other extensions are sent as compiled IR (.yaml).--envondraft test,thread create, andthread runloads the effective merged environment (tenant + script overlay) into the run.- Version
0means “the active version” wherever a--versionor rollback target is accepted.
See also
- Recipes — runnable end-to-end scenarios using these commands.
- API Reference — the full gRPC/HTTP surface.
- Scriptum Language — the
.scriptumsyntax you author. - Core Concepts — script / draft / version / thread vocabulary.