> ## 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.

# status-pages

> DevHelm CLI status-pages commands — manage public status pages, components, incidents, maintenance, subscribers, and custom domains

Manage public status pages from the command line. The `status-pages` topic groups seven related command trees: the status page itself, plus its components, component groups, published incidents, scheduled maintenance, email subscribers, and custom domains.

<Tip>
  Status pages are workspace-scoped, identified by **slug** in URLs (`https://status.example.com/sp/{slug}`) but addressed by **UUID** in the CLI. Use `devhelm status-pages list` to look up IDs.
</Tip>

## Top-level commands

| Command | Description |
| - | - |
| `devhelm status-pages list` | List all status pages |
| `devhelm status-pages get <id>` | Get a status page |
| `devhelm status-pages create` | Create a new status page |
| `devhelm status-pages update <id>` | Update a status page |
| `devhelm status-pages delete <id>` | Delete a status page |

### status-pages list

```bash theme={null}
devhelm status-pages list
```

| Flag | Type | Default | Description |
| - | - | - | - |
| `--page-size` | integer | `200` | Number of items per API request (1–200) |

### status-pages create

```bash theme={null}
devhelm status-pages create \
  --name "Acme Status" \
  --slug acme \
  --visibility PUBLIC \
  --incident-mode AUTOMATIC
```

| Flag | Type | Required | Description |
| - | - | - | - |
| `--name` | string | Yes | Display name shown in the page header |
| `--slug` | string | Yes | URL-safe identifier used in the public URL |
| `--description` | string | — | Subheader text below the page name |
| `--visibility` | enum | — | `PUBLIC` (currently the only supported value; `PASSWORD`/`IP_RESTRICTED` are reserved) |
| `--incident-mode` | enum | — | `MANUAL` (operator creates and publishes incidents), `REVIEW` (auto-created incidents require operator review), or `AUTOMATIC` (incidents auto-publish) |
| `--branding-file` | string | — | Path to a JSON file containing branding fields (`logoUrl`, `brandColor`, `theme`, `customCss`, …) |

### status-pages update

Same flags as `create`, all optional.

```bash theme={null}
devhelm status-pages update <id> --description "Real-time service health for Acme APIs"
```

### status-pages delete

```bash theme={null}
devhelm status-pages delete <id>
```

<Warning>
  Deleting a status page also deletes its components, groups, published incidents, and subscriber list. Custom domains attached to the page are released. This is irreversible.
</Warning>

***

## Components

A **component** maps an underlying monitor or service catalog dependency to a row on the public page.

| Command | Description |
| - | - |
| `devhelm status-pages components list <page-id>` | List components on a page |
| `devhelm status-pages components create <page-id>` | Add a component |
| `devhelm status-pages components update <page-id> <component-id>` | Update a component |
| `devhelm status-pages components delete <page-id> <component-id>` | Remove a component |

```bash theme={null}
devhelm status-pages components create <page-id> \
  --name "API" \
  --monitor-id <monitor-uuid> \
  --display-order 0
```

***

## Component groups

Group related components into collapsible sections.

| Command | Description |
| - | - |
| `devhelm status-pages groups list <page-id>` | List component groups |
| `devhelm status-pages groups create <page-id>` | Create a group |
| `devhelm status-pages groups update <page-id> <group-id>` | Update a group |
| `devhelm status-pages groups delete <page-id> <group-id>` | Delete a group |

```bash theme={null}
devhelm status-pages groups create <page-id> \
  --name "Customer-facing APIs" \
  --description "Public REST endpoints" \
  --default-open
```

| Flag (update) | Description |
| - | - |
| `--name` | Group display name |
| `--description` | Subheader text |
| `--default-open` / `--no-default-open` | Initial expand/collapse state on first page load |
| `--display-order` | Position in the list (integer; lower = higher) |

***

## Incidents

Publish incidents to the page. Incidents created here are independent of platform incidents — `incident-mode=AUTOMATIC` on the page handles auto-publish from monitor failures.

| Command | Description |
| - | - |
| `devhelm status-pages incidents list <page-id>` | List published incidents |
| `devhelm status-pages incidents get <page-id> <incident-id>` | Get incident details |
| `devhelm status-pages incidents create <page-id>` | Draft a new incident |
| `devhelm status-pages incidents update <page-id> <incident-id>` | Update title/impact/status |
| `devhelm status-pages incidents publish <page-id> <incident-id>` | Promote a draft to public |
| `devhelm status-pages incidents post-update <page-id> <incident-id>` | Append a status update entry |
| `devhelm status-pages incidents dismiss <page-id> <incident-id>` | Discard a draft incident |
| `devhelm status-pages incidents delete <page-id> <incident-id>` | Delete a published incident |

```bash theme={null}
devhelm status-pages incidents update <page-id> <incident-id> \
  --status MONITORING \
  --impact MAJOR
```

| Flag | Values |
| - | - |
| `--status` | `INVESTIGATING`, `IDENTIFIED`, `MONITORING`, `RESOLVED` |
| `--impact` | `NONE`, `MINOR`, `MAJOR`, `CRITICAL` |

`incidents list` accepts `--limit <n>` (default 20) to cap results.

`--scheduled` is no longer valid on `status-pages incidents create`. Use `status-pages maintenance create` for planned windows.

***

## Maintenance

A maintenance window is a scheduled, customer-facing notice on the public status page: title, impact, start/end, and optional subscriber email. Visitors see upcoming or in-progress work as maintenance, not as an incident.

Mute alerts during a deploy with `devhelm maintenance-windows`. Show a vendor's own planned work with `devhelm services maintenances`.

| Command | Description |
| - | - |
| `devhelm status-pages maintenance list <page-id>` | List maintenance windows |
| `devhelm status-pages maintenance get <page-id> <window-id>` | Get a window |
| `devhelm status-pages maintenance create <page-id>` | Draft a scheduled window |
| `devhelm status-pages maintenance update <page-id> <window-id>` | Update title/impact/schedule |
| `devhelm status-pages maintenance publish <page-id> <window-id>` | Promote a draft to public |
| `devhelm status-pages maintenance post-update <page-id> <window-id>` | Append a timeline update |
| `devhelm status-pages maintenance dismiss <page-id> <window-id>` | Discard a draft window |
| `devhelm status-pages maintenance delete <page-id> <window-id>` | Delete a published window |

```bash theme={null}
devhelm status-pages maintenance create <page-id> \
  --title "DB upgrade" \
  --impact MINOR \
  --body "Read-only for 30m" \
  --scheduled-for 2026-09-01T02:00:00Z
```

| Flag | Required | Description |
| - | - | - |
| `--title` | Yes | Customer-facing title |
| `--impact` | Yes | `NONE`, `MINOR`, `MAJOR`, `CRITICAL` |
| `--body` | Yes | Initial update body in markdown |
| `--scheduled-for` | Yes | Start time (ISO 8601) |
| `--scheduled-until` | — | End time (ISO 8601) |
| `--status` | — | Initial status (`INVESTIGATING`, `IDENTIFIED`, `MONITORING`, `RESOLVED`) |
| `--auto-resolve` | — | Auto-resolve at `--scheduled-until` |
| `--notify-subscribers` / `--no-notify-subscribers` | — | Email confirmed subscribers (default: notify) |

`maintenance list` accepts `--limit <n>` (default 20).

```bash theme={null}
devhelm status-pages maintenance publish <page-id> <window-id>
devhelm status-pages maintenance post-update <page-id> <window-id> \
  --status MONITORING \
  --body "Halfway through"
devhelm status-pages maintenance update <page-id> <window-id> \
  --scheduled-until 2026-09-01T04:00:00Z
```

***

## Subscribers

Manage the email subscriber list for incident notifications.

| Command | Description |
| - | - |
| `devhelm status-pages subscribers list <page-id>` | List subscribers |
| `devhelm status-pages subscribers add <page-id>` | Add a subscriber |
| `devhelm status-pages subscribers remove <page-id> <subscriber-id>` | Remove a subscriber |

```bash theme={null}
devhelm status-pages subscribers add <page-id> --email user@example.com
```

***

## Custom domains

Every status page is served from a default first-party host:
`https://<slug>.devhelmstatus.com`. The API returns this as the page's
`page_url` until a custom domain is set as primary.

To attach a vanity domain (e.g. `status.example.com`):

1. Register the domain with `devhelm status-pages domains add`.
2. Add a `CNAME` record at your DNS provider pointing the vanity hostname
   at the brand-stable target `cname.devhelm.io`.
3. Run `devhelm status-pages domains verify` until the status flips to
   `active` (DevHelm provisions the TLS certificate via Cloudflare for SaaS).
4. Optionally `set-primary` so the public URL switches over.

| Command | Description |
| - | - |
| `devhelm status-pages domains list <page-id>` | List custom domains |
| `devhelm status-pages domains add <page-id>` | Register a new domain |
| `devhelm status-pages domains verify <page-id> <domain-id>` | Trigger DNS verification |
| `devhelm status-pages domains set-primary <page-id> <domain-id>` | Mark a verified domain as the canonical URL |
| `devhelm status-pages domains remove <page-id> <domain-id>` | Detach a domain |

```bash theme={null}
devhelm status-pages domains add <page-id> --hostname status.example.com
# DNS: CNAME status.example.com -> cname.devhelm.io
devhelm status-pages domains verify <page-id> <domain-id>
devhelm status-pages domains set-primary <page-id> <domain-id>
```

When a domain is set as primary, the public status page redirects from the
default `<slug>.devhelmstatus.com` URL to the custom domain.

***

## Common patterns

### Bootstrap a status page from scratch

```bash theme={null}
PAGE_ID=$(devhelm status-pages create --name "Acme Status" --slug acme --visibility PUBLIC -o json | jq -r '.id')

devhelm status-pages groups create "$PAGE_ID" --name "APIs" --default-open
devhelm status-pages components create "$PAGE_ID" --name "API" --monitor-id <monitor-uuid>
devhelm status-pages domains add "$PAGE_ID" --hostname status.example.com
```

### Publish an incident with two updates

```bash theme={null}
INCIDENT_ID=$(devhelm status-pages incidents create "$PAGE_ID" \
  --title "Elevated API latency" --impact MINOR -o json | jq -r '.id')

devhelm status-pages incidents publish "$PAGE_ID" "$INCIDENT_ID"
devhelm status-pages incidents post-update "$PAGE_ID" "$INCIDENT_ID" \
  --status MONITORING --body "Mitigation deployed; watching."
devhelm status-pages incidents update "$PAGE_ID" "$INCIDENT_ID" --status RESOLVED
```

## Next steps

<CardGroup cols={2}>
  <Card title="Status data overview" icon="signal" href="/status-data/overview">
    Concepts behind status pages and component health.
  </Card>

  <Card title="Resource groups" icon="folder-tree" href="/platform/resource-groups">
    Compose monitors and dependencies into status-page components.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.