Skip to main content
Schedule, extend, and cancel maintenance windows from the command line. Use these around deploys, migrations, and scheduled provider downtime so on-call doesn’t get paged for known-expected failures. Maintenance windows are an imperative state operation — they intentionally do not appear in devhelm.yml or the Terraform provider. Schedule them from your deploy script, an SDK, or an MCP-enabled agent.

​
Commands

CommandDescription
devhelm maintenance-windows listList maintenance windows (filter by status or monitor)
devhelm maintenance-windows get <id>Show a single window
devhelm maintenance-windows createSchedule a new window
devhelm maintenance-windows update <id>Extend or modify an existing window
devhelm maintenance-windows cancel <id>Cancel a window (alerts resume immediately)

​
maintenance-windows list

devhelm maintenance-windows list
devhelm maintenance-windows list --status active
devhelm maintenance-windows list --status upcoming
devhelm maintenance-windows list --monitor <monitor-id>
FlagTypeDescription
--statusstringactive (currently open) or upcoming (scheduled). Omit for both.
--monitorUUIDOnly windows attached to this monitor (org-wide windows excluded).

​
maintenance-windows get

devhelm maintenance-windows get <window-id>
devhelm maintenance-windows get <window-id> -o json

​
maintenance-windows create

Schedule a new window. Both --start and --end are required. 
devhelm maintenance-windows create \
  --start "2026-05-15T14:00:00Z" \
  --end "2026-05-15T14:30:00Z" \
  --reason "Quarterly DB upgrade" \
  --monitor <monitor-id>
FlagTypeRequiredDescription
--startdatetimeYesWhen the window opens. ISO 8601 with explicit timezone (UTC preferred).
--enddatetimeYesWhen the window closes. Must be strictly after --start.
--monitorUUID list—Comma-separated monitor IDs. Omit for an org-wide window. Multiple IDs schedule one window per monitor (the API stores one monitor per window).
--reasonstring—Human-readable description. Surfaces in the dashboard and audit log.
--repeat-rulestring—iCal RRULE for recurring windows (max 100 chars). Omit for one-time.
--no-suppress-alertsboolean—Record the window for audit without silencing notifications. Default behaviour is to suppress.
Always quote ISO 8601 timestamps. Many shells treat the : characters as field separators in unquoted strings and will mangle the value before the CLI sees it.

​
Examples

devhelm maintenance-windows create \
  --start "2026-05-15T14:00:00Z" \
  --end   "2026-05-15T14:30:00Z" \
  --reason "Quarterly DB upgrade" \
  --monitor 9f4a-1234-...

devhelm maintenance-windows create \
  --start "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  --end   "$(date -u -d '+30 minutes' +%Y-%m-%dT%H:%M:%SZ)" \
  --reason "Production deploy $(git rev-parse --short HEAD)" \
  --monitor 9f4a-...,8b21-...,7c33-...

devhelm maintenance-windows create \
  --start "2026-05-15T02:00:00Z" \
  --end   "2026-05-15T04:00:00Z" \
  --reason "Cluster upgrade — every monitor affected"

devhelm maintenance-windows create \
  --start "2026-05-19T02:00:00Z" \
  --end   "2026-05-19T04:00:00Z" \
  --repeat-rule "FREQ=WEEKLY;BYDAY=TU" \
  --reason "Weekly infra maintenance"

​
maintenance-windows update

Extend or modify an existing window. The update is a full replacement — pass --start and --end even if you only want to change one of them. 
devhelm maintenance-windows update <window-id> \
  --start "2026-05-15T14:00:00Z" \
  --end   "2026-05-15T15:00:00Z" \
  --reason "Migration still running"
The most common use is extending an in-flight window when a deploy runs longer than expected — call this with the new --end to keep alerts suppressed past the original deadline. Letting the window lapse and then opening a fresh one creates a notification gap.

​
maintenance-windows cancel

Cancel a window. Alerting resumes on the next failed check — there is no “uncancel.” Pass --yes to skip the confirmation prompt in scripts. 
devhelm maintenance-windows cancel <window-id>
If the window had not yet started, this prevents it from ever opening. If it was active, it ends immediately.

​
Deploy-script pattern

The full create-deploy-cancel cycle, suitable for a deploy script: 
set -euo pipefail

# Open a 30-minute window
WINDOW=$(devhelm maintenance-windows create \
  --start "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  --end   "$(date -u -d '+30 minutes' +%Y-%m-%dT%H:%M:%SZ)" \
  --reason "Deploy $(git rev-parse --short HEAD)" \
  --monitor "$MONITOR_ID" \
  -o json | jq -r '.id')

# ... run your deploy ...

# Close the window so alerting resumes
devhelm maintenance-windows cancel "$WINDOW" --yes
If the deploy fails partway, leave the window open so subsequent retries don’t page on-call — but make sure your script eventually cancels it (or reduce the --end budget) so it can’t accidentally suppress the next real outage.

​
Next steps

Maintenance windows reference

Concepts, fields, and full surface support matrix.

Maintenance windows guide

Walkthrough for deploy-time and recurring windows.

MCP server tools

Let an AI agent schedule the window before running a deploy.