> ## 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. # maintenance-windows > DevHelm CLI maintenance-windows commands — schedule, list, extend, and cancel alert-suppression 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](/incidents/maintenance-windows#surface-support-v1) — 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 ` | Show a single window | | `devhelm maintenance-windows create` | Schedule a new window | | `devhelm maintenance-windows update ` | Extend or modify an existing window | | `devhelm maintenance-windows cancel ` | Cancel a window (alerts resume immediately) | ## maintenance-windows list ```bash theme={null} devhelm maintenance-windows list devhelm maintenance-windows list --status active devhelm maintenance-windows list --status upcoming devhelm maintenance-windows list --monitor ``` | 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 ```bash theme={null} devhelm maintenance-windows get devhelm maintenance-windows get -o json ``` ## maintenance-windows create Schedule a new window. Both `--start` and `--end` are required. ```bash theme={null} devhelm maintenance-windows create \ --start "2026-05-15T14:00:00Z" \ --end "2026-05-15T14:30:00Z" \ --reason "Quarterly DB upgrade" \ --monitor ``` | 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 ```bash One monitor, 30 minutes theme={null} devhelm maintenance-windows create \ --start "2026-05-15T14:00:00Z" \ --end "2026-05-15T14:30:00Z" \ --reason "Quarterly DB upgrade" \ --monitor 9f4a-1234-... ``` ```bash Multiple monitors theme={null} 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-... ``` ```bash Org-wide theme={null} devhelm maintenance-windows create \ --start "2026-05-15T02:00:00Z" \ --end "2026-05-15T04:00:00Z" \ --reason "Cluster upgrade — every monitor affected" ``` ```bash Recurring (weekly Tuesday) theme={null} 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. ```bash theme={null} devhelm maintenance-windows update \ --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. ```bash theme={null} devhelm maintenance-windows cancel ``` 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: ```bash theme={null} 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 Concepts, fields, and full surface support matrix. Walkthrough for deploy-time and recurring windows. Let an AI agent schedule the window before running a deploy.