CLI Reference

The CLI uses human-readable colored output by default. Commands offering --json expose stable machine output. Relative input paths resolve from the current directory, and durable state defaults to .woml/state.sqlite.

Author and execute

Command	Purpose
`woml check <inputs...> [--config <path>] [--json]`	Parse, validate, compile, resolve deployment dependencies, and refresh types without execution.
`woml run <inputs...> [options]`	Activate one deployment as a long-lived foreground or background runtime.
`woml test <file> [options]`	Execute one manual occurrence and exit.
`woml types <inputs...> [--output <path>]`	Generate declarations at an explicit path.

Inputs can be explicit .woml files or directories. Direct .woml files in a directory are loaded non-recursively.

Terminal

woml check workflows/ --config woml.runtime.json
woml run parent.woml child.woml
woml test examples/hello.woml

Important run options:

Option	Meaning
`--config <path>`	Load runtime configuration.
`--host`, `--port`	Override the public trigger listener.
`--state <path>`	Select the durable SQLite authority.
`--trigger <id>`	Select a manual trigger when required.
`--resume <runId>`	Continue a recoverable run against its pinned definition.
`--approval-port <port>`	Override the local approval listener.
`--background`, `-d`	Detach after genuine readiness.
`--verbose`	Print additional safe diagnostics.
`--color=auto\|always\|never`	Control ANSI color.

Observe and manage runs

Command	Purpose
`woml inspect [--state <path>] [--no-color]`	Open the live terminal operations view.
`woml list [filters]`	List recent runs by workflow, status, and limit.
`woml get <runId>`	Read one redacted durable run projection.
`woml cancel <runId>`	Record a durable cooperative cancellation request.
`woml stop`	Gracefully stop the background runtime for a state boundary.
`woml <runId-or-workflowId> --logs`	Print matching history and follow new output.

Terminal

woml list --workflow orders --status failed --limit 50
woml get run_abc123 --json
woml run_abc123 --logs
woml cancel run_abc123

get intentionally omits payloads, full context, output values, credentials, idempotency keys, and stack traces. Ctrl+C exits inspect or log following without stopping the runtime.

Publish internal events

Terminal

woml emit order.created \
  --id publisher-event-42 \
  --data @order.json \
  --server http://127.0.0.1:3000 \
  --token-secret EVENT_CONTROL_TOKEN

--id is the publisher's stable occurrence identity. Repeating the same ID and data deduplicates; reusing the ID with changed data conflicts. Applications can call the authenticated HTTP endpoint directly—emit is an operator convenience, not the only integration path.

Manage secrets

Terminal

woml secrets set PAYMENTS_API_TOKEN
woml secrets list
woml secrets delete PAYMENTS_API_TOKEN

set prompts securely. list shows names only. Run these commands from the project whose local secret store you intend to manage.

Diagnose providers

Terminal

woml telegram doctor --destination <chatId>
woml discord doctor --destination <channelId>
woml whatsapp doctor --phone-number-id <id>

Doctor commands verify identity, permissions, and optional destinations or callbacks without creating workflow runs or sending messages. Slack currently reports actionable startup diagnostics instead of a public doctor command.

Maintain durable state

Command	Purpose
`woml backup <directory>`	Create a coherent SQLite snapshot, manifest, and checksums.
`woml restore <directory> --replace`	Verify and restore while the target runtime is offline.
`woml prune --before <duration>`	Remove eligible old terminal history while preserving protected data.

Terminal

woml backup ./backups/2026-08-24
woml prune --before 90d --dry-run
woml prune --before 90d --compact

Use --help on a command for its current options. Most operational commands accept --state; many read commands accept --json.