opschain breakglass record
Included from Basic tier
opschain breakglass record (--run <id> --after-step <step> | --node <path>)
--reason <text> [--window <from>/<to>|<duration>] [--change <id|code>]
[--activity <text>] [--command <text>] [--statement <text>]
[--evidence name=file]... [--reference name=system:id]...
[--check name=command --check-output name=file [--check-expect name=pattern]]...
[--maintenance-window <id>] [--change-ref system:record_type:id]
Declares a change made by hand outside any run. Two forms:
- On the run it rescued —
--run <id> --after-step <step>: the fix found during a change. The record's node is the run's node and its events land on the run's chain at the step it followed (by step name or full path). - On the node it changed —
--node <path>: a retroactive change outside any run. Any node path spelling the CLI accepts works (demo/environments/prod,/projects/demo/environments/prod/assets/web).
--reason is required, and so is --window unless --change names a
change record with a window (the act then takes it, cut at now). The window is the act's own span,
<from>/<to> in RFC3339 with a zone (minute precision such as
2026-11-17T22:40Z is accepted), and must not end in the future — a record
is declared after the act.
Relative windows. Each side of --window may also be now or an
offset from now — a Go duration with its sign, -30m, +5m — in any mix
with RFC3339, resolved on this machine's clock and sent as UTC: -30m/now
is "the last half hour", -2h/-1h "the hour before last". A bare duration
(2h) means from now for that long, which ends in the future and so is
refused here; it suits a planned window (opschain changes create,
opschain maintenance schedule). A time without a zone is refused (add
Z or an offset, or use a relative form), and so is a window that ends at
or before it starts.
Correlation, strongest first: a change record (--change, or the
record of the run it rescued — opschain docs resources/change_record),
then its run; otherwise --maintenance-window or --change-ref correlates
it. A record nothing
correlates is still accepted but flagged (uncorrelated) and its window
may span at most 24 hours.
Evidence takes four kinds, and the record's evidence class is the strongest present:
--reference name=system:id— an identifier the external system minted (an operation id, a ticket number): the strongest.--check name=commandwith--check-output name=fileand an optional--check-expect name=pattern— a read-only check and its captured output; the output must contain the pattern (or match it, written/like this/), else the record is refused.--evidence name=file(or a bare path, named by its file name) — a screenshot or an export, uploaded as an artifact on the record's node first and digest-sealed on the record. The CLI checks each file before anything is uploaded: at most 10 MB, a png, jpeg, pdf, json or plain-text file by its extension, and content that agrees with that type (an executable or an HTML page named.txtis refused); the target's own budget and accepted types are then the final word. Files bypass the log maskers: redact secrets from screenshots before attaching them.- the statement —
--statement, else the activity, else the reason; always recorded.
Prints recorded break-glass record <id> on <node> (unreconciled, evidence class <kind>), then the recorded window in UTC — window 2026-11-20T07:00:00Z/2026-11-20T07:30:00Z (UTC) — plus a line when the
record is uncorrelated; -o json /
-o yaml emit the record. In the local lane a notice on stderr says the
record is in the local store only.
Flags
| Flag | Meaning |
|---|---|
--run <id> | The run the act rescued (with --after-step). |
--after-step <step> | The step of --run the act followed, by name or full path. |
--node <path> | The node the act changed, outside any run. Exclusive with --run. |
--reason <text> | Why the act could not wait for a run. Required. |
--window <from>/<to>|<duration> | The act's own window: each side RFC3339 with a zone, now or an offset such as -30m (see Relative windows). Required, unless --change names a change record with a window. |
--activity <text> | What was done, in free text. |
--command <text> | The command that was run, when the act was a command. |
--statement <text> | Your statement; defaults to the activity, else the reason. |
--evidence name=file | An evidence file (repeatable). |
--reference name=system:id | An external system's identifier (repeatable). |
--check name=command | A read-only check that was run (repeatable; needs --check-output). |
--check-output name=file | The check's captured output (repeatable). |
--check-expect name=pattern | What the output must contain, or /regex/ (repeatable). |
--maintenance-window <id> | The maintenance window the act happened under (server only). |
--change-ref system:record_type:id | The external change the act belongs to, e.g. JSM:change:CHG-7. |
--change <id|code> | The change record the act belongs to — the first correlation. The record must not be pending; attaching needs update on its change_records rule path. A record on a run under a change record takes that record without the flag, and naming a different one is refused. With --change, --window may be omitted: the act takes the change record's window, cut at now. |
Exit codes
| Code | Meaning |
|---|---|
| 0 | Recorded. |
| 1 | Refused — e.g. a check whose output does not satisfy its expect, an evidence file over the budget, an uncorrelated window over 24 hours, a pending or unknown --change record, or the caller lacks the node's break-glass record right (the run or node then reads as not found). |
| 2 | Usage error. |
Named errors
name the run the act rescued (--run with --after-step) or the node it changed (--node)— exit 2.--run and --node are mutually exclusive: …— exit 2.--run needs --after-step: the step the act followed— exit 2.--window wants <from>/<to> (each RFC3339 with a zone, now, or an offset like +2h) or a bare duration, …— exit 2.--window start: "…" has no time zone: add Z or an offset (…), or use a relative form like now/+2h(same shape for--window end) — exit 2.--window ends at or before it starts (…): a window must be longer than zero— exit 2.window: a break-glass record is declared after the act: the window cannot end in the future— exit 1.--reference wants name=system:id (…)— exit 2.--check <name> needs its captured output: --check-output <name>=<file>— exit 2.change_record_id: change record … is pending: nothing joins a change before it is approved— exit 1.change_record_id: run … is under change record …; a record on it belongs to that change— exit 1.window: an uncorrelated record's window spans at most 24h0m0s; …— exit 1.--evidence <name>: … bytes is over the evidence budget of … bytes,--evidence <name>: "…" is not an accepted evidence typeand--evidence <name>.content_type: the file's content reads as "…", not the declared "…"— the CLI's own checks before upload; exit 1.evidence[N].size_bytes: … is over the evidence budget of … bytes,evidence[N].content_type: "…" is not an accepted evidence typeandevidence[N].content_type: the file's content reads as "…", not the declared "…"— the target's checks; exit 1.break-glass records are a human verb: …— an agent, a service account or a step's credential; exit 1.
Examples
opschain breakglass record --run 01a1e7c3-… --after-step upgrade \
--reason "secrets unit deadlocked after the swap; licensing down" \
--window 2026-11-17T22:40Z/2026-11-17T22:46Z \
--activity "killed the blocked start on the primary; started the daemons" \
--command "az vm run-command invoke …" \
--evidence units-after.txt --reference operation=azure:6f1c…
recorded break-glass record 019a…-7c2e on /projects/hosted_ops (unreconciled, evidence class reference)
window 2026-11-17T22:40:00Z/2026-11-17T22:46:00Z (UTC)
opschain breakglass record --node hosted_ops/environments/prod/assets/hosted \
--reason "role condition blocked the upgrade; owner PIM session" \
--window 2026-11-15T00:18Z/2026-11-15T00:24Z \
--activity "widened the runner principal's condition in the portal" --evidence after.png
recorded break-glass record 019a…-81d0 on /projects/hosted_ops/environments/prod/assets/hosted (unreconciled, evidence class file)
window 2026-11-15T00:18:00Z/2026-11-15T00:24:00Z (UTC)
uncorrelated: the record is flagged for review — correlate the next one with --run, --maintenance-window or --change-ref
opschain breakglass record --node hosted_ops/environments/prod \
--reason "slot wedged mid-swap" --window -30m/now --change-ref JSM:change:CHG-7
recorded break-glass record 019a…-92b4 on /projects/hosted_ops/environments/prod (unreconciled, evidence class statement)
window 2026-11-20T07:00:00Z/2026-11-20T07:30:00Z (UTC)
See also
opschain docs cli/breakglass-close— closing the reconciliation.opschain docs resources/breakglass_record— the record and its evidence.