opschain runs create change

Included from Basic tier

opschain runs create change <action | node-path> [flags]

Runs a change — one action on one target. 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 ACTION to execute (e.g. web:deploy) and --env names the target environment in the repository. 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 the NODE PATH the change is created on — demo/environments/dev/assets/web, a bare project code, or the full /projects/... form — and --action names the action. The command calls the typed v2 ChangeService.CreateChange RPC, prints the created change 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.

Flags — server lane

Flag	Meaning
--action <action>	The action to run. Required unless the -f payload carries action.
-f, --file <payload.yaml>	The full creation payload from a strict YAML file — every attribute in it is sent. 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. 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	Change 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 change 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).
--follow	Poll the created change (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 change 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 change is created.

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

Flags — both lanes

Flag	Meaning
--plan	Resolve and print the step tree without running anything. Locally the tree comes from the local compile; against a server the create payload rides the typed v2 ChangeService.PlanChange 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.
--skip-step <path>	Step path to skip (repeatable). On a server this REPLACES the -f payload's skip_steps wholesale, it does not merge.
--starting-step <path>	Skip every step before this step path; its ancestors pass through.
-i, --input k=v	A typed run input (repeatable), validated against the action's inputs: declarations before the run exists; a run-supplied value overrides a declared default in the action's root scope. Values travel as strings and coerce to the declared type; a repeated key builds a list; a secret input takes a secret reference only — secret-vault://…, or secret-env://<NAME> on a local run (the invoking process's environment variable; refused by name on a server). Merged OVER the -f payload's inputs. Refused for actions with no declarative action file.

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.

Global flags that matter here: --server <url> / --local select the lane; -o, --output json|yaml prints the created change (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 change 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 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, --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.
• --plan and --follow are mutually exclusive — a plan creates no run to follow.
• --override wants k=v (nested keys via dots, e.g. opschain.env.A=1) — a malformed k=v pair (same for --metadata).
• expected a node path like demo, demo/environments/dev, /projects/demo/environments/dev/assets/web or demo/entities/rack_1, got "…" — a malformed server-lane target.
• <path> is an entity — an entity has no template and nothing runs against it, so it cannot be the target of a change — an entity path as the server-lane target.
• 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 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

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 change'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/runs-create — the creation verb's overview.
• opschain docs cli/runs-create-workflow — the workflow lane of the same verb.
• opschain docs fleet-queue — where created server changes queue and why they might not dispatch.
• opschain docs ci — the unattended contract of the local lane for a pipeline (exit codes, the -o json document, the published action and template).
• opschain learn 3.1 — the guided version of the server lane.