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
| Flag | Meaning |
|---|---|
--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
| Code | Meaning |
|---|---|
| 0 | Opened. |
| 1 | Refused — a scope outside the owner, a code already taken, an unreadable owner. |
| 2 | Usage error — no title, no scope, a malformed window or reference, a time without a zone, a window that ends at or before it starts. |