Skip to main content
Version: v5.8.0

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=command with --check-output name=file and 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 .txt is 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​

FlagMeaning
--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=fileAn evidence file (repeatable).
--reference name=system:idAn external system's identifier (repeatable).
--check name=commandA read-only check that was run (repeatable; needs --check-output).
--check-output name=fileThe check's captured output (repeatable).
--check-expect name=patternWhat the output must contain, or /regex/ (repeatable).
--maintenance-window <id>The maintenance window the act happened under (server only).
--change-ref system:record_type:idThe 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​

CodeMeaning
0Recorded.
1Refused — 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).
2Usage 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 type and --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 type and evidence[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.