CLI overview

The CLI is the scriptable companion to the desktop app. Both run the same engine, share the same .overwire/ config, and write to the same run store.

overwire [options] [command]

Command	Purpose
init	Scaffold a flat .overwire/ config tree
doctor	Health-check Node, the container engine, and your config
parse	Parse a workflow YAML file and print its structure
list	List workflows with their triggers and jobs
lint	Lint a workflow file for common issues
explain	Explain how Overwire would support a workflow without running it
simulate	Print a simulated event payload
run	Execute a workflow locally, mock by default
chain	Run or inspect workflow-chain scenario sessions
resolve	Fetch and parse an action’s action.yml
seed-mocks	Write a mock contract for every uses: in a workflow
status	Show latest workflow and check status for a ref or SHA
history	List recent workflow runs for the current project
cache	Inspect or clear the action cache
validate	Validate every workflow and config file without running anything
schema	Print the JSON Schema for a .overwire/ config format
agents	Print the guide for AI agents driving Overwire
license	Manage the Overwire Pro license shared with the desktop app

Most commands accept --config-root <dir> to point at a .overwire/ directory outside the current working directory. When the config root is some/repo/.overwire, the project identity derives from some/repo.

JSON output

Every introspection and execution command has structured output: parse, list, lint, explain, status, history, chain, validate, doctor, doctor capabilities, init, seed-mocks, cache, and license status accept --json; simulate and schema always print JSON; run --json streams run events as JSON lines and ends with a single run:result envelope. Unhandled errors in --json invocations print one structured {"error":{"kind","label","message","guidance"}} object to stderr.

Exit codes

Code	Meaning
0	Success — including a run correctly skipped by trigger filters and validation that found only warnings.
1	The run (or lint/validate) concluded failure or cancelled, or an unhandled error occurred.
2	Parse, configuration, validation, usage, or licensing errors — nothing executed.
130 / 143	Interrupted by SIGINT / SIGTERM.