> ## 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, subscribers, and custom domains

Manage public status pages from the command line. The `status-pages` topic groups six related command trees: the status page itself, plus its components, component groups, published incidents, 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.

***

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