opschain maintenance schedule
maintenance
opschain maintenance schedule <path> --from <rfc3339> --to <rfc3339>
--reason <text> [--allow-workflow w]... [--allow-action a]...
[--allow-user u]... [--run <workflow>]... [--auto-extend 15m]
[--max-extension 2h] [--auto-end]
Creates a maintenance window the server starts and ends by itself: it
opens at --from and closes at --to — a hard end, unlike a manual
window's advisory intent. Only one window — active or scheduled — can
exist per node at a time, and a scheduled window that has not started yet
is removed with opschain maintenance cancel.
The window can carry its own work: each --run workflow is started at the
window's opening, as you, and counts as the window's own (allowlisted,
stamped) work. Two knobs tie the end to that work:
--auto-extend <d>keeps pushing the hard end out by<d>while the window's work is still running — up to--max-extension(2h unless set), after which the window ends anyway with a warning;--auto-endcloses the window as soon as all its work has finished, whatever the outcome, instead of waiting for the hard end.
Durations are passed to the server as whole seconds. Prints
scheduled maintenance on <path> from <from> to <to> (window <id>);
-o json / -o yaml emit the window document.
Flags
| Flag | Meaning |
|---|---|
--reason <text> | Why the subtree will be quiesced. Required. |
--from <rfc3339> | When the window starts. Required. |
--to <rfc3339> | When the window ends — the hard end the server enforces. Required. |
--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). |
--run <workflow> | Workflow to start when the window opens, run as you (repeatable). |
--auto-extend <d> | Keep extending the window by this much (e.g. 15m) while its work is unfinished. |
--max-extension <d> | Cap on the total automatic extension (e.g. 2h); 2h unless set. |
--auto-end | End the window as soon as all its work has finished, whatever the outcome. |
Exit codes
| Code | Meaning |
|---|---|
| 0 | Window scheduled. |
| 1 | The server refused — e.g. a window already exists on the node, or missing rights. |
| 2 | Usage error. |
Named errors
required flag(s) "from", "reason", "to" not set— whichever are missing; exit 2.--from wants an RFC3339 timestamp like 2026-10-12T22:00:00Z: <parse error>(same shape for--to) — exit 2.--auto-extend wants a positive duration like 15m or 1h(same shape for--max-extension) — exit 2.expected a node path like demo/environments/dev, got ""— exit 2.
Examples
A Saturday-night window that runs the upgrade itself and closes as soon as it finishes:
opschain maintenance schedule acme/environments/prod \
--from 2026-10-17T12:00:00Z --to 2026-10-17T14:00:00Z \
--reason "db engine upgrade" \
--run db_upgrade --auto-extend 15m --max-extension 1h --auto-end
scheduled maintenance on /projects/acme/environments/prod from 2026-10-17T12:00:00Z to 2026-10-17T14:00:00Z (window 01999a7e-…)
See also
opschain docs cli/maintenance-cancel— removing it before it starts.opschain docs cli/maintenance-extend— moving the hard end by hand.opschain learn 5.6— the full window lifecycle.