opschain maintenance start
maintenance
opschain maintenance start <path> --reason <text> [--until <rfc3339>]
[--allow-workflow w]... [--allow-action a]... [--allow-user u]...
Starts a manual maintenance window on a node, immediately. The path names
a project, environment or asset — bare <project>[/environments/<e>[/assets/<a>]]
forms are accepted and prefixed for you, so acme/environments/dev and
/projects/acme/environments/dev are the same node.
From that moment the node's subtree is quiesced: non-allowlisted creates
answer a named 422 and matching trigger firings are held back, while every
other node operates normally. The allow lists declare the window's own
maintenance work. --until is declared intent only — a manual window
never auto-closes; only opschain maintenance end closes it (a deferral
parked past the declared intent expires as suppressed at release). For a
window the server opens and closes by itself, use
opschain maintenance schedule instead.
Prints started maintenance on <path> (window <id>); -o json / -o yaml
emit the created window document.
Flags
| Flag | Meaning |
|---|---|
--reason <text> | Why the subtree is quiesced. Required; it is the text the 422 names to blocked callers. |
--until <rfc3339> | Declared end intent (e.g. 2026-10-12T22:00:00Z). Advisory only. |
--allow-workflow <code> | Workflow code admitted through the window (repeatable). |
--allow-action <action> | Change action admitted through the window (repeatable). |
--allow-user <username> | Username admitted through the window (repeatable). |
Exit codes
| Code | Meaning |
|---|---|
| 0 | Window started. |
| 1 | The server refused — e.g. a window (active or scheduled) already exists on the node, or the caller lacks the node's maintenance update right. |
| 2 | Usage error. |
Named errors
required flag(s) "reason" not set— exit 2.--until wants an RFC3339 timestamp like 2026-10-12T22:00:00Z: <parse error>— exit 2.expected a node path like demo/environments/dev, got ""— an empty path; exit 2.
Examples
opschain maintenance start acme/environments/dev \
--reason "db engine upgrade" \
--until 2026-10-12T22:00:00Z \
--allow-workflow db_upgrade --allow-user dba_bot
started maintenance on /projects/acme/environments/dev (window 01999a7e-…)
See also
opschain docs cli/maintenance-schedule— the self-starting, self-ending variant.opschain docs cli/maintenance-status,opschain docs cli/maintenance-end.opschain learn 5.6— what quiesces, what defers, and the escape hatches.