CLI Overview

The woml command is the single interface for the complete workflow lifecycle: authoring, validation, execution, observation, recovery, and maintenance. You do not need a separate development server or browser application.

Start with the three everyday commands

Terminal

woml check workflows/
woml run workflows/
woml inspect

check proves that a deployment can compile without starting it. run activates the workflows and remains alive for future triggers. inspect opens the live terminal operations view.

Use woml --help to see the installed command surface and woml --version or woml -v to confirm the release.

Finite commands and long-lived commands

Some commands do one job and exit:

check, test, and types support authoring and CI.
list, get, and cancel manage runs.
backup, restore, and prune maintain durable state.
Provider doctor commands diagnose credentials and destinations.

Other commands stay active:

run hosts triggers and executes new occurrences.
inspect refreshes the terminal operations view.
<runId-or-workflowId> --logs follows new log records.

Long-lived commands normally end with Ctrl+C. In foreground run, WOML performs a graceful shutdown rather than abandoning admitted work without explanation.

Human and machine output

Colored, readable terminal output is the default. It shows workflow identity, trigger instructions, run IDs, named steps, durations, safe results, and actionable diagnostics. Commands that support --json expose stable machine-readable output for scripts and CI:

Terminal

woml check workflows/ --json
woml list --status failed --json
woml get run_abc123 --json

Match automation against diagnostic codes and JSON fields, not colored prose.

The state boundary

Local durable state defaults to .woml/state.sqlite. This database is the authority for runs, events, waits, definitions, policy queues, and operational projections. Commands addressing the same runtime must select the same state path:

Terminal

woml run workflows/ --state ./data/workflow-history.sqlite
woml inspect --state ./data/workflow-history.sqlite
woml list --state ./data/workflow-history.sqlite

Relative paths resolve from the current directory unless a configuration field explicitly resolves relative to its configuration file.

A practical daily workflow

During development, keep one terminal running woml run workflow.woml. Edit the file, stop and restart the runtime to activate the new immutable definition, then trigger it again. Before deployment, run woml check workflows/ --config woml.runtime.json. In production, run WOML in the foreground under your process supervisor and use inspect, list, get, and log following from another terminal.

A non-zero exit means a finite command failed. Continue with Validate and Test for the authoring loop or Run Workflows to activate automation.