Skip to main content
Version: v5.8.0

opschain changes create

Included from Basic tier

opschain changes create --title <text> --scope <path|path/**>... [--owner /|/projects/<code>]
[--code <code>] [--class standard|normal|emergency] [--description <text>]
[--window <from>/<to>|<duration>] [--owner-principal <id>] [--reference system:record_type:id]...

Opens a pending change record. Nothing joins it until it is approved (opschain changes approve). The code is generated — CHG-<year>-<sequence> under the owner — unless --code names one.

opschain changes create --owner /projects/hosted_ops --title "hosted 1.3.1" \
--scope /projects/hosted_ops/environments/prod/** --reference JSM:change:CHG-7
change record CHG-2026-001 opened (pending) under /projects/hosted_ops (id 019b…)

A record opened with --window prints the window it was given back on a second line, resolved and in UTC, so you see exactly what was sent:

opschain changes create --owner /projects/hosted_ops --title "hosted 1.3.1" \
--scope /projects/hosted_ops/environments/prod/** --window +10m/+2h
change record CHG-2026-002 opened (pending) under /projects/hosted_ops (id 019b…)
window 2026-11-20T07:40:00Z/2026-11-20T09:30:00Z (UTC)

Relative windows​

--window takes <from>/<to>, where each side is an RFC3339 time with a zone (2026-11-21T22:00Z, 2026-11-22T09:00+11:00), now, or an offset from now (+10m, +2h, -30m — a Go duration with its sign), in any mix; or a bare duration (2h), which means from now for that long. So now/+2h, +10m/+2h and 2h all work. Relative times are resolved on this machine's clock and sent as UTC. A time without a zone (2026-11-21T22:00) is refused — add Z or an offset, or use a relative form — and so is a window that ends at or before it starts.

Opening a record needs update on the owner's change_records rule path. An agent may open one; only a person may approve or close it.

Flags​

FlagMeaning
--title <text>What the change is. Required, at most 200 bytes.
--scope <pattern>A node the change may touch: a node path, or a node path followed by /** for the node and everything under it. Repeatable; at least one; every one under the owner.
--owner <path>/ (the organisation, the default) or /projects/<code>. A project's record never reaches another project.
--code <code>The record's code, unique under the owner; generated when omitted.
--class <class>standard, normal (default) or emergency.
--description <text>Why, in free text.
--window <from>/<to>|<duration>The planned window: each side RFC3339 with a zone, now or an offset such as +2h, or a bare duration from now (see Relative windows). A record with a window captures runs by scope only from its start up to its end — a scheduled run outside it stays off the record — while naming the record on a run's creation and changes link are never window-bound; "in progress" reads it too.
--owner-principal <id>The principal id the change is assigned to (default: you).
--reference <ref>An external reference, system:record_type:id (e.g. JSM:change:CHG-7). Repeatable.

Exit codes​

CodeMeaning
0Opened.
1Refused — a scope outside the owner, a code already taken, an unreadable owner.
2Usage error — no title, no scope, a malformed window or reference, a time without a zone, a window that ends at or before it starts.