Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.devhelm.io/llms.txt

Use this file to discover all available pages before exploring further.

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 delete <id>Cancel a window (alerts resume immediately)

​
maintenance-windows list

devhelm maintenance-windows list
devhelm maintenance-windows list --filter active
devhelm maintenance-windows list --filter upcoming
devhelm maintenance-windows list --monitor <monitor-id>
FlagTypeDescription
--filterstringactive (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-...

​
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 delete

Cancel a window. Alerting resumes on the next failed check — there is no “uncancel.” 
devhelm maintenance-windows delete <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 delete "$WINDOW"
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.