opschain run

Included from Basic tier

opschain run <action> [flags]
opschain run workflow <code | file> [flags]

The local lane's short verb: opschain run <action> is exactly opschain runs create change <action> --local, and opschain run workflow <code> is opschain runs create workflow <code> --local (opschain docs cli/run-workflow). The same flags, the same attached execution — live step tree, streamed logs, terminal wait prompts, the process exit code as the run's outcome — and the same exit codes. The alias never targets a server: --server is refused by name and the active opschain context is ignored, so a shell with a server context still runs locally here. To create a run on a server use opschain runs create change|workflow.

The positional argument is the ACTION to execute (web:deploy, mypack:banner) and --env names the target environment declared in the repository's .opschain/config.yaml. An action literally named workflow cannot be run through the alias — runs create change workflow --local runs it.

Flags

Flag	Meaning
--env <code>	Target environment code. Required.
--asset <code>	Target asset code within the environment.
--ref <git-ref>	Run a clean snapshot of this git ref instead of the working copy.
--plan	Resolve and print the step tree without running anything.
-i, --input k=v	A typed run input (repeatable), validated against the action's inputs: declarations; a repeated key builds a list; a secret input takes secret-vault://… or secret-env://<NAME>.
--skip-step <path>	Step path or glob to skip (repeatable; an entry skips its whole subtree).
--starting-step <path>	Skip every step before this step path; its ancestors pass through.
--approve-all	Auto-answer wait and approval steps with their defaults.
--max-parallel <n>	Maximum concurrently running steps (0 = engine default).
--keep-workspace	Keep step and run workspaces for debugging or artifact collection instead of cleaning up.
--follow-logs <path>	Show log output for this step path (and its descendants) only.
--timeout <d>	Override the run timeout (e.g. 30m, 2h; 0 = action file / engine default).
--step-timeout <d>	Override the default per-step timeout; a step's own timeout still wins.
--env-passthrough <names>	Comma-separated extra environment variable names handed from the invoking process's environment to every step, on top of the host executor's default allowlist (OPSCHAIN_VAULT_* names are dropped).

Global flags that matter here: -o, --output json|yaml prints the terminal run summary as a machine document; -q, --quiet prints only the run id. The first Ctrl-C cancels the run gracefully; a second exits immediately.

Exit codes

Code	Meaning
0	Run succeeded.
1	Run failed (error, system_error, aborted), or the command itself failed.
2	Usage error — a missing --env, a server target, bad flags.
3	Run cancelled.
4	Run timed out.

Named errors

• --env is required — no target environment.
• opschain run is the local lane and never targets a server — use opschain runs create change|workflow … --server to create a run on a server — --server given (exit 2).
• invalid step path "…": no leading or trailing / — a malformed --starting-step or --follow-logs.
• --input wants key=value (repeat the flag for lists, e.g. -i env=dev -i env=test) — a malformed --input pair.

Examples

opschain run web:deploy --env dev
opschain run web:deploy --env dev --ref main -i release=1.2.0 --approve-all
opschain run workflow nightly --env dev

See also

• opschain docs cli/run-workflow — the workflow form.
• opschain docs cli/runs-create-change, cli/runs-create-workflow — the full creation verb, both lanes.
• opschain learn 2.1 — your first action; opschain learn 2.6 — the local development loop.