maintenance-windows

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

Command	Description
`devhelm maintenance-windows list`	List maintenance windows (filter by status or monitor)
`devhelm maintenance-windows get <id>`	Show a single window
`devhelm maintenance-windows create`	Schedule 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>

Flag	Type	Description
`--status`	string	`active` (currently open) or `upcoming` (scheduled). Omit for both.
`--monitor`	UUID	Only 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>

Flag	Type	Required	Description
`--start`	datetime	Yes	When the window opens. ISO 8601 with explicit timezone (UTC preferred).
`--end`	datetime	Yes	When the window closes. Must be strictly after `--start`.
`--monitor`	UUID 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).
`--reason`	string	—	Human-readable description. Surfaces in the dashboard and audit log.
`--repeat-rule`	string	—	iCal RRULE for recurring windows (max 100 chars). Omit for one-time.
`--no-suppress-alerts`	boolean	—	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.

​Commands

​maintenance-windows list

​maintenance-windows get

​maintenance-windows create

​Examples

​maintenance-windows update

​maintenance-windows cancel

​Deploy-script pattern

​Next steps

Maintenance windows reference

Maintenance windows guide

MCP server tools

Commands

maintenance-windows list

maintenance-windows get

maintenance-windows create

Examples

maintenance-windows update

maintenance-windows cancel

Deploy-script pattern

Next steps