opschain runs create

Included from Basic tier

One creation verb, two subcommands, two lanes:

opschain runs create change   <action | node-path>       [flags]
opschain runs create workflow <code | file | project/code> [flags]

The lane is selected by the target, never by a mode flag on this command: --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 run EXECUTES in the repository, 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 command calls the typed v2 create RPCs (ChangeService.CreateChange / WorkflowRunService.CreateWorkflowRun), prints the created run and returns without waiting; --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.

The positional argument

Lane	change	workflow
local	the ACTION to execute (e.g. web:deploy); --env names the target environment	the workflow CODE (resolved under .opschain/workflows) or a workflow FILE path
server	the NODE PATH the change is created on (e.g. demo/environments/dev/assets/web); --action names the action	<project>/<code> naming the project's stored workflow

Flags — server lane

Flag	Applies to	Meaning
--action <action>	change	The action to run. Required on a server target unless the -f payload carries action.
--version <n>	workflow	Pin a stored workflow version; the latest published version runs when omitted.
-f, --file <payload.yaml>	both	The full creation payload from a strict YAML file — every attribute in it is sent. Change keys: action, git_remote_name, git_rev, build_without_cache, auto_continue_wait_steps, starting_step, notify, property_overrides, settings_overrides, metadata, skip_steps, inputs, override_maintenance, rationale, recommendation_id. Workflow keys: version, property_overrides, inputs, metadata, notify, skip_steps, override_maintenance, rationale, recommendation_id. Unknown keys are refused by name.
--override k=v	both	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	both	Run metadata (repeatable), same k=v rules, merged over the -f payload's metadata. The runner key demands placement — see the fleet-queue page.
--rationale <why>	both	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 payload's rationale.
--skip-step <path>	both	Step path to skip (repeatable). On a server this REPLACES the -f payload's skip_steps wholesale, it does not merge.
-i, --input k=v	both (both lanes)	A typed run input, validated against the workflow's or action's inputs: declarations before the run exists. Repeatable; a repeated key builds a list; values travel as strings and coerce to the declared type; secret inputs take secret references only (secret-vault://…, or secret-env://<NAME> on a local run — refused by name on a server), and an empty value (-i token=) means "not supplied" — the default applies, or the secret binds the empty string. Merged OVER the -f payload's inputs.
--starting-step <path>	change (server + local); workflow (local only)	Skip every step before this step path; its ancestors pass through.
--follow	both	Poll the created run 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 (the show payload's 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.

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

Flags — both lanes

Flag

Meaning

--plan

Resolve and print the step tree without running anything. Against a server, the plan endpoint answers will-run/will-skip verdicts and symbolic spans for output-dependent values; a concrete fan-out expansion prints one row per element with its resolved name, target path and action (✔ sap → /projects/p/environments/dev/assets/sap · sap:stop). No run is created and the plan is advisory. Refused together with --follow.

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 = 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 (HOME, TMPDIR, locale, USER, the proxy variables — opschain docs runner-executors). The same semantics as opschain runner --env-passthrough: OPSCHAIN_VAULT_* names are dropped. Nothing else of your shell reaches a step. A retried run (runs retry) uses the default allowlist.

--skip-step and --starting-step work in both lanes (for workflow, --starting-step is local-only).

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.

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

• --action is required (or set action in the -f payload) — server-lane change with no action anywhere.
• --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 (--action/--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 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).
• A payload file carrying a key outside the lane's vocabulary is refused naming the key and the accepted set.

All of the above exit 2.

Examples

Run an action locally, attached:

opschain runs create change web:deploy --env dev

Create a change on a server node and return immediately:

opschain runs create change demo/environments/dev/assets/web --action web:deploy
created change 01999a7e-… (web:deploy on demo/environments/dev/assets/web) — pending

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

opschain runs create change demo/environments/dev/assets/web --action web:deploy --follow

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

Demand placement for the change's steps:

opschain runs create change demo/environments/dev/assets/web --action web:deploy \
  --metadata runner.group=secure

Related settings

• The target node's settings runner block supplies default placement for the created run's steps; --metadata runner.… overrides it per field. Resolution and the verdict ladder: opschain docs fleet-queue.
• auto_continue_wait_steps (a -f payload key) pre-answers the change's wait steps.

See also

• opschain docs cli/run — opschain run <action> and opschain run workflow <code>, the local lane's aliases of this verb's --local forms.
• opschain docs fleet-queue — where created server runs queue and why they might not dispatch.
• opschain learn 3.1 (changes on a server) and opschain learn 4.1 (workflows) — the guided versions of both lanes.