opschain runs create workflow

Included from Basic tier

opschain runs create workflow <code | file | project/code> [flags]

Runs a workflow. The lane is selected by the target, never by a mode flag: --local forces the local repository, --server <url> (or OPSCHAIN_SERVER, or the active opschain context) targets a server, and with none of those set the run executes locally.

• Locally the positional argument is the workflow CODE (resolved under .opschain/workflows) or a workflow FILE path, and --env names the target environment. The run EXECUTES attached: live step tree, streamed logs, terminal wait prompts, and the process exit code is the run's outcome. --follow changes nothing locally — attached is the only local mode.
• Against a server the positional argument is <project>/<code> naming the project's stored workflow. The command calls the typed v2 WorkflowRunService.CreateWorkflowRun RPC, prints the created run and returns without waiting; --version pins a stored version (the latest published version runs when omitted) and --follow opts into polling the run to its terminal status.

Each lane refuses the other lane's flags by name (see Named errors), so a mis-targeted invocation fails loudly instead of half-working.

Flags — server lane

Flag	Meaning
--version <n>	Pin a stored workflow version; the latest published version runs when omitted.
-f, --file <payload.yaml>	The full creation payload from a strict YAML file — every attribute in it is sent. Keys: version, property_overrides, inputs, metadata, notify, skip_steps, override_maintenance, rationale, recommendation_id. An unknown key is refused by name with the accepted set. override_maintenance: true pushes the create through an active maintenance window — honoured only with update on every covering window's maintenance rule path, stamped and audited (see opschain docs cli/maintenance).
--override k=v	Property override (repeatable). Dots in k set nested keys; v parses as JSON when it is valid JSON (3, true, ["a"]), else as a string. Merged OVER the -f payload's property_overrides.
--metadata k=v	Run metadata (repeatable), same k=v rules, merged over the -f payload's metadata. The runner key demands placement — see opschain docs fleet-queue.
--rationale <why>	Why the run is raised — stored under the server-owned opschain.rationale metadata key and shown to its approvers as the approval context (opschain approvals show); overlays the -f payloads rationale`. Optional for a person (an agent principal must state one).
--skip-step <path>	Step path to skip (repeatable, both lanes). On a server this REPLACES the -f payload's skip_steps wholesale, it does not merge.
-i, --input k=v	A typed run input (repeatable, BOTH lanes), validated against the workflow's inputs: declarations before the run exists. Values travel as strings and coerce to the declared type (number, boolean, enum, secret, list<string>); a repeated key builds a list, and a list<string> input also accepts one comma-separated value. A secret input takes a vault reference (secret-vault://…) only. Merged OVER the -f payload's inputs. Unknown names, missing required inputs and type/enum violations are named 422s.
--follow	Poll the created run (every 2 s) until it finishes, printing each status transition; the terminal status maps onto the attached-run exit codes. When the server reports the run waiting on runner capacity (steps queued with no online, non-draining runner serving their queue/group), it prints queued — no online runner currently serves this run once. Without it the command returns as soon as the run is created.
--plan	Resolve and print the step tree without running anything (both lanes). Locally the tree comes from the local compile; against a server the create payload rides the typed v2 WorkflowRunService.PlanWorkflowRun RPC and the tree carries will-run (✔) / will-skip (−) verdicts with their evaluated evidence and symbolic (?) markers for output-dependent values (tiers 1–2). No run is created; the plan is advisory — conditions re-evaluate at step entry. Refused together with --follow.

Flag overlay order: the -f file is read first, then --version, --override, --metadata, --input and --skip-step overlay it.

Flags — local lane

Flag	Meaning
--env <code>	Target environment code. Required for a local run.
--asset <code>	Target asset code within the environment.
--ref <git-ref>	Run a clean snapshot of this git ref instead of the working copy.
--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 = engine default).
--step-timeout <d>	Override the default per-step timeout; a step's own timeout still wins.
--starting-step <path>	Skip every step before this step path; its ancestors pass through. Local only for workflows — a server workflow run refuses it.

Global flags that matter here: --server <url> / --local select the lane; -o, --output json|yaml prints the created run (or, with --follow, the terminal summary) as a machine document; -q, --quiet prints only the run id. During a local attached run, the first Ctrl-C cancels the run gracefully; a second exits immediately.

Exit codes

Code	Meaning
0	Run succeeded (local / --follow), or the run was created (server without --follow).
1	Run failed (error, system_error, aborted), or the command itself failed.
2	Usage error — bad flags, lane refusals, malformed k=v.
3	Run cancelled.
4	Run timed out.

Named errors

• --plan and --follow are mutually exclusive — a plan creates no run to follow.

• expected <project>/<workflow-code>, got "…" — a server-lane target without the project prefix.

• --env is required — local run without a target environment.

• <flag> applies to server targets only — a local run names its target in the positional argument and the local flags (pass --server <url> or 'opschain context use <name>' to target a server) — a server-lane flag (--version, --file, --override, --metadata) on a local run.

• <flag> applies to local execution only — pass --local to run in the repository instead of creating on the server — a local-lane flag (including --starting-step) on a server target.

• --override wants k=v (nested keys via dots, e.g. opschain.env.A=1) — a malformed k=v pair (same for --metadata).

• --input wants key=value (repeat the flag for lists, e.g. -i env=dev -i env=test) — a malformed --input pair.

• invalid step path "…": no leading or trailing / — a malformed --starting-step or --follow-logs on a local run.

• <path>: unknown payload attribute(s) <keys> (accepted: …) — a -f key outside the vocabulary above.

All of the above exit 2.

Examples

Run a repository workflow locally, attached:

opschain runs create workflow nightly --env dev

Run a stored workflow on a server, pinning a version and overriding a property:

opschain runs create workflow demo/nightly --version 3 --override opschain.env.REGION=ap-southeast-2

Supply typed inputs (validated against the workflow's declarations; defaults fill the rest):

opschain runs create workflow demo/patch_fleet -i environment=production -i batch_size=3 -i dry_run=false

Create and follow to the terminal status (exit code = outcome):

opschain runs create workflow demo/nightly --follow

Related settings

• The settings runner block on the nodes the workflow's changes target supplies default placement; --metadata runner.… overrides it per field. Resolution and the verdict ladder: opschain docs fleet-queue.

See also

• opschain docs cli/runs-create — the creation verb's overview.
• opschain docs cli/runs-create-change — the change lane of the same verb.
• opschain learn 4.1 — the guided workflow walkthrough.