diff --git a/README.md b/README.md index 6af9ffa..00c3c6f 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,18 @@ openstatus monitors info 123 # Trigger an on-demand check openstatus monitors trigger 123 -# Report an incident +# Declare an incident, then publish a linked public status report +ID=$(openstatus incident declare --title "Checkout API returns 502" --severity major -q) +openstatus status-report create --title "Checkout issues" --status investigating \ + --message "We are investigating failed payments" --page-id 1 --incident-id "$ID" + +# Run the incident: notes, status changes, postmortem +openstatus inc note "$ID" --message "Rolled back the deploy" +openstatus inc resolve "$ID" --note "Error rate back to normal" +openstatus inc postmortem edit "$ID" --file postmortem.md +openstatus inc postmortem approve "$ID" --close -y + +# Post a public status update openstatus status-report create --title "API degradation" --status investigating --page-id 1 # Report an incident with per-component impact @@ -78,7 +89,8 @@ Rate limit: 3 requests per 60 seconds. | `login` / `logout` | | Authenticate with the OpenStatus API | | `whoami` | `w` | Show current workspace info | | `monitors` | `m` | List, inspect, trigger, import, and apply monitors | -| `status-report` | `sr` | Create and manage incident reports | +| `incident` | `inc`, `incidents` | Declare and run incidents (lifecycle, notes, status report link, postmortem) | +| `status-report` | `sr` | Post and manage public status reports | | `maintenance` | `mt` | Schedule and manage maintenance windows | | `status-page` | `sp` | View status pages and components | | `notification` | `n` | View notification channels | diff --git a/docs/openstatus-docs.md b/docs/openstatus-docs.md index 647bfd9..e89ca1a 100644 --- a/docs/openstatus-docs.md +++ b/docs/openstatus-docs.md @@ -2,7 +2,7 @@ ## CLI interface - openstatus -OpenStatus CLI lets you manage your status pages and uptime monitors from the command line. Report and track incidents, define monitors as code, and run on-demand checks. Get started: openstatus login Save your API token openstatus status-report create Report an incident openstatus status-report list View active incidents openstatus maintenance create Schedule a maintenance window openstatus maintenance list View maintenance windows openstatus monitors apply Sync monitors from config openstatus monitors list List your monitors openstatus run Run synthetic tests openstatus pl list List your private locations https://docs.openstatus.dev | https://github.com/openstatusHQ/cli/issues/new. +OpenStatus CLI lets you manage your status pages and uptime monitors from the command line. Declare and run incidents, post public status updates, define monitors as code, and run on-demand checks. Get started: openstatus login Save your API token openstatus incident declare Declare an incident openstatus incident list View incidents openstatus status-report create Post a public status update openstatus status-report list View status reports openstatus maintenance create Schedule a maintenance window openstatus maintenance list View maintenance windows openstatus monitors apply Sync monitors from config openstatus monitors list List your monitors openstatus run Run synthetic tests openstatus pl list List your private locations https://docs.openstatus.dev | https://github.com/openstatusHQ/cli/issues/new. Manage status pages, monitors, and incidents from the terminal. @@ -339,6 +339,7 @@ The following flags are supported: | `--impact="…"` | Per-component impact, repeatable: --impact = (level: operational, degraded, partial_outage, major_outage). Mutually exclusive with --component-ids | string | | *none* | | `--notify` | Notify subscribers about this status report | bool | `false` | *none* | | `--date="…"` | Date when the event occurred (RFC 3339 format, defaults to now) | string | | *none* | +| `--incident-id="…"` | ID of an incident to link the report to | string | | *none* | ### `status-report update` subcommand @@ -403,6 +404,403 @@ The following flags are supported: | `--impact="…"` | Per-component impact, repeatable: --impact = (level: operational, degraded, partial_outage, major_outage). Can also add new affected components | string | | *none* | | `--notify` | Notify subscribers about this update | bool | `false` | *none* | +### `incident` command (aliases: `inc`, `incidents`) + +Declare and run incidents. + +Incidents are the internal response to an outage: severity, commander, lifecycle (open -> mitigated -> resolved, or canceled), timeline notes, a linked public status report and the postmortem. Use 'openstatus status-report' for the public communication on a status page. + +Usage: + +```bash +$ openstatus [GLOBAL FLAGS] incident [ARGUMENTS...] +``` + +### `incident list` subcommand + +List incidents. + +> openstatus incident list +> openstatus inc list --active +> openstatus inc list --status open,mitigated --limit 10 + +Usage: + +```bash +$ openstatus [GLOBAL FLAGS] incident list [COMMAND FLAGS] [ARGUMENTS...] +``` + +The following flags are supported: + +| Name | Description | Type | Default value | Environment variables | +|-----------------------------|-------------------------------------------------------------------------|--------|:-------------:|:----------------------:| +| `--access-token="…"` (`-t`) | OpenStatus API Access Token | string | | `OPENSTATUS_API_TOKEN` | +| `--status="…"` | Filter by status, comma-separated (open, mitigated, resolved, canceled) | string | | *none* | +| `--active` | Only incidents that are not closed | bool | `false` | *none* | +| `--closed` | Only closed incidents | bool | `false` | *none* | +| `--limit="…"` | Maximum number of incidents to return (1-100, defaults to 50) | int | `0` | *none* | +| `--offset="…"` | Number of incidents to skip | int | `0` | *none* | + +### `incident info` subcommand + +Get incident details and timeline. + +> openstatus incident info +> openstatus inc info 42 + +Usage: + +```bash +$ openstatus [GLOBAL FLAGS] incident info [COMMAND FLAGS] [ARGUMENTS...] +``` + +The following flags are supported: + +| Name | Description | Type | Default value | Environment variables | +|-----------------------------|-----------------------------|--------|:-------------:|:----------------------:| +| `--access-token="…"` (`-t`) | OpenStatus API Access Token | string | | `OPENSTATUS_API_TOKEN` | + +### `incident declare` subcommand (aliases: `create`) + +Declare a new incident. + +> openstatus incident declare --title "Checkout API returns 502" --severity major +> openstatus inc declare --title "Database down" --severity critical --commander jane@example.com --slack +> ID=$(openstatus inc declare --title "Login errors" --severity minor -q) + +Declare a new incident in the open status. Run without --title or --severity in an interactive terminal to be prompted. In scripts, pass every required flag. + +Usage: + +```bash +$ openstatus [GLOBAL FLAGS] incident declare [COMMAND FLAGS] [ARGUMENTS...] +``` + +The following flags are supported: + +| Name | Description | Type | Default value | Environment variables | +|-----------------------------|--------------------------------------------------------|--------|:-------------:|:----------------------:| +| `--access-token="…"` (`-t`) | OpenStatus API Access Token | string | | `OPENSTATUS_API_TOKEN` | +| `--title="…"` | Title of the incident (1-256 characters) | string | | *none* | +| `--severity="…"` | Severity of the incident (critical, major, minor) | string | | *none* | +| `--summary="…"` | Short human summary | string | | *none* | +| `--commander="…"` | Email of the workspace member leading the response | string | | *none* | +| `--started-at="…"` | When the impact began (RFC 3339, defaults to now) | string | | *none* | +| `--status-report-id="…"` | ID of an existing status report to link | string | | *none* | +| `--slack` | Open a dedicated Slack channel when Slack is connected | bool | `false` | *none* | + +### `incident update` subcommand + +Edit an incident's title, severity, summary, commander or start time. + +> openstatus incident update [flags] +> openstatus inc update 42 --severity critical +> openstatus inc update 42 --commander jane@example.com +> openstatus inc update 42 --clear-summary + +Usage: + +```bash +$ openstatus [GLOBAL FLAGS] incident update [COMMAND FLAGS] [ARGUMENTS...] +``` + +The following flags are supported: + +| Name | Description | Type | Default value | Environment variables | +|-----------------------------|---------------------------------------|--------|:-------------:|:----------------------:| +| `--access-token="…"` (`-t`) | OpenStatus API Access Token | string | | `OPENSTATUS_API_TOKEN` | +| `--title="…"` | New title (1-256 characters) | string | | *none* | +| `--severity="…"` | New severity (critical, major, minor) | string | | *none* | +| `--summary="…"` | New summary | string | | *none* | +| `--clear-summary` | Remove the summary | bool | `false` | *none* | +| `--commander="…"` | Email of the new commander | string | | *none* | +| `--clear-commander` | Unassign the commander | bool | `false` | *none* | +| `--started-at="…"` | New start of impact (RFC 3339) | string | | *none* | + +### `incident set-status` subcommand + +Move an incident to a new status. + +> openstatus incident set-status --status [--note "..."] +> openstatus inc set-status 42 --status mitigated --note "Rolled back the deploy" + +Allowed transitions: open -> mitigated, resolved or canceled; mitigated -> resolved, open or canceled; resolved -> open. Canceled is terminal and closes the incident. A linked status report is not updated: post the public update with 'openstatus status-report add-update'. + +Usage: + +```bash +$ openstatus [GLOBAL FLAGS] incident set-status [COMMAND FLAGS] [ARGUMENTS...] +``` + +The following flags are supported: + +| Name | Description | Type | Default value | Environment variables | +|-----------------------------|-----------------------------------------------------|--------|:-------------:|:----------------------:| +| `--access-token="…"` (`-t`) | OpenStatus API Access Token | string | | `OPENSTATUS_API_TOKEN` | +| `--status="…"` | Target status (open, mitigated, resolved, canceled) | string | | *none* | +| `--note="…"` | Note recorded on the timeline with the change | string | | *none* | +| `--auto-accept` (`-y`) | Automatically accept the prompt | bool | `false` | *none* | + +### `incident mitigate` subcommand + +Mark an incident as mitigated. + +> openstatus incident mitigate [--note "..."] +> openstatus inc mitigate 42 --note "..." + +Usage: + +```bash +$ openstatus [GLOBAL FLAGS] incident mitigate [COMMAND FLAGS] [ARGUMENTS...] +``` + +The following flags are supported: + +| Name | Description | Type | Default value | Environment variables | +|-----------------------------|-----------------------------------------------|--------|:-------------:|:----------------------:| +| `--access-token="…"` (`-t`) | OpenStatus API Access Token | string | | `OPENSTATUS_API_TOKEN` | +| `--note="…"` | Note recorded on the timeline with the change | string | | *none* | + +### `incident resolve` subcommand + +Mark an incident as resolved. + +> openstatus incident resolve [--note "..."] +> openstatus inc resolve 42 --note "..." + +Usage: + +```bash +$ openstatus [GLOBAL FLAGS] incident resolve [COMMAND FLAGS] [ARGUMENTS...] +``` + +The following flags are supported: + +| Name | Description | Type | Default value | Environment variables | +|-----------------------------|-----------------------------------------------|--------|:-------------:|:----------------------:| +| `--access-token="…"` (`-t`) | OpenStatus API Access Token | string | | `OPENSTATUS_API_TOKEN` | +| `--note="…"` | Note recorded on the timeline with the change | string | | *none* | + +### `incident reopen` subcommand + +Reopen a mitigated or resolved incident. + +> openstatus incident reopen [--note "..."] +> openstatus inc reopen 42 --note "..." + +Usage: + +```bash +$ openstatus [GLOBAL FLAGS] incident reopen [COMMAND FLAGS] [ARGUMENTS...] +``` + +The following flags are supported: + +| Name | Description | Type | Default value | Environment variables | +|-----------------------------|-----------------------------------------------|--------|:-------------:|:----------------------:| +| `--access-token="…"` (`-t`) | OpenStatus API Access Token | string | | `OPENSTATUS_API_TOKEN` | +| `--note="…"` | Note recorded on the timeline with the change | string | | *none* | + +### `incident cancel` subcommand + +Cancel an incident (closes it). + +> openstatus incident cancel [--note "..."] +> openstatus inc cancel 42 --note "..." + +Usage: + +```bash +$ openstatus [GLOBAL FLAGS] incident cancel [COMMAND FLAGS] [ARGUMENTS...] +``` + +The following flags are supported: + +| Name | Description | Type | Default value | Environment variables | +|-----------------------------|-----------------------------------------------|--------|:-------------:|:----------------------:| +| `--access-token="…"` (`-t`) | OpenStatus API Access Token | string | | `OPENSTATUS_API_TOKEN` | +| `--note="…"` | Note recorded on the timeline with the change | string | | *none* | +| `--auto-accept` (`-y`) | Automatically accept the prompt | bool | `false` | *none* | + +### `incident note` subcommand + +Add a note to an incident timeline. + +> openstatus incident note --message "Rolled back the deploy" +> echo "multi-line markdown" | openstatus inc note 42 --message - + +Usage: + +```bash +$ openstatus [GLOBAL FLAGS] incident note [COMMAND FLAGS] [ARGUMENTS...] +``` + +The following flags are supported: + +| Name | Description | Type | Default value | Environment variables | +|-----------------------------|----------------------------------------------------------------------|--------|:-------------:|:----------------------:| +| `--access-token="…"` (`-t`) | OpenStatus API Access Token | string | | `OPENSTATUS_API_TOKEN` | +| `--message="…"` (`-m`) | Note text in markdown (1-10000 characters); use - to read from stdin | string | | *none* | + +### `incident link-report` subcommand + +Link a public status report to an incident. + +> openstatus incident link-report +> openstatus inc link-report 42 123 + +Usage: + +```bash +$ openstatus [GLOBAL FLAGS] incident link-report [COMMAND FLAGS] [ARGUMENTS...] +``` + +The following flags are supported: + +| Name | Description | Type | Default value | Environment variables | +|-----------------------------|-----------------------------|--------|:-------------:|:----------------------:| +| `--access-token="…"` (`-t`) | OpenStatus API Access Token | string | | `OPENSTATUS_API_TOKEN` | + +### `incident unlink-report` subcommand + +Remove the link to an incident's status report. + +> openstatus incident unlink-report +> openstatus inc unlink-report 42 + +Usage: + +```bash +$ openstatus [GLOBAL FLAGS] incident unlink-report [COMMAND FLAGS] [ARGUMENTS...] +``` + +The following flags are supported: + +| Name | Description | Type | Default value | Environment variables | +|-----------------------------|-----------------------------|--------|:-------------:|:----------------------:| +| `--access-token="…"` (`-t`) | OpenStatus API Access Token | string | | `OPENSTATUS_API_TOKEN` | + +### `incident close` subcommand + +Close a resolved incident. + +> openstatus incident close +> openstatus inc close 42 --skip-postmortem -y + +Close a resolved incident. A closed incident is read-only except for its postmortem. Requires an approved postmortem, or --skip-postmortem. + +Usage: + +```bash +$ openstatus [GLOBAL FLAGS] incident close [COMMAND FLAGS] [ARGUMENTS...] +``` + +The following flags are supported: + +| Name | Description | Type | Default value | Environment variables | +|-----------------------------|--------------------------------------|--------|:-------------:|:----------------------:| +| `--access-token="…"` (`-t`) | OpenStatus API Access Token | string | | `OPENSTATUS_API_TOKEN` | +| `--skip-postmortem` | Close without an approved postmortem | bool | `false` | *none* | +| `--auto-accept` (`-y`) | Automatically accept the prompt | bool | `false` | *none* | + +### `incident delete` subcommand + +Delete an incident declared by mistake. + +> openstatus incident delete +> openstatus inc delete 42 -y + +Delete an incident declared by mistake. Only allowed while the incident is open and was never mitigated, resolved or closed; cancel it otherwise. + +Usage: + +```bash +$ openstatus [GLOBAL FLAGS] incident delete [COMMAND FLAGS] [ARGUMENTS...] +``` + +The following flags are supported: + +| Name | Description | Type | Default value | Environment variables | +|-----------------------------|---------------------------------|--------|:-------------:|:----------------------:| +| `--access-token="…"` (`-t`) | OpenStatus API Access Token | string | | `OPENSTATUS_API_TOKEN` | +| `--auto-accept` (`-y`) | Automatically accept the prompt | bool | `false` | *none* | + +### `incident postmortem` subcommand (aliases: `pm`) + +Read, write and approve an incident's postmortem. + +Usage: + +```bash +$ openstatus [GLOBAL FLAGS] incident postmortem [ARGUMENTS...] +``` + +### `incident postmortem show` subcommand + +Show the postmortem of an incident. + +> openstatus incident postmortem show +> openstatus inc pm show 42 > postmortem.md + +In a terminal, prints the review status and the markdown body through your pager. When piped, prints only the markdown body, so it can be edited and sent back with 'openstatus inc pm edit --file postmortem.md'. + +Usage: + +```bash +$ openstatus [GLOBAL FLAGS] incident postmortem show [COMMAND FLAGS] [ARGUMENTS...] +``` + +The following flags are supported: + +| Name | Description | Type | Default value | Environment variables | +|-----------------------------|-----------------------------|--------|:-------------:|:----------------------:| +| `--access-token="…"` (`-t`) | OpenStatus API Access Token | string | | `OPENSTATUS_API_TOKEN` | + +### `incident postmortem edit` subcommand + +Write or replace the postmortem of a resolved incident. + +> openstatus incident postmortem edit --file postmortem.md +> cat postmortem.md | openstatus inc pm edit 42 --file - +> openstatus inc pm edit 42 --content "## Summary ..." + +Replaces the whole markdown body. An approved postmortem stays approved. + +Usage: + +```bash +$ openstatus [GLOBAL FLAGS] incident postmortem edit [COMMAND FLAGS] [ARGUMENTS...] +``` + +The following flags are supported: + +| Name | Description | Type | Default value | Environment variables | +|-----------------------------|---------------------------------------------------|--------|:-------------:|:----------------------:| +| `--access-token="…"` (`-t`) | OpenStatus API Access Token | string | | `OPENSTATUS_API_TOKEN` | +| `--file="…"` | Markdown file to upload; use - to read from stdin | string | | *none* | +| `--content="…"` | Markdown body passed inline | string | | *none* | + +### `incident postmortem approve` subcommand + +Approve the postmortem, optionally closing the incident. + +> openstatus incident postmortem approve +> openstatus inc pm approve 42 --close -y + +Usage: + +```bash +$ openstatus [GLOBAL FLAGS] incident postmortem approve [COMMAND FLAGS] [ARGUMENTS...] +``` + +The following flags are supported: + +| Name | Description | Type | Default value | Environment variables | +|-----------------------------|---------------------------------|--------|:-------------:|:----------------------:| +| `--access-token="…"` (`-t`) | OpenStatus API Access Token | string | | `OPENSTATUS_API_TOKEN` | +| `--close` | Also close the incident | bool | `false` | *none* | +| `--auto-accept` (`-y`) | Automatically accept the prompt | bool | `false` | *none* | + ### `maintenance` command (aliases: `mt`) Manage maintenance windows. diff --git a/docs/openstatus.1 b/docs/openstatus.1 index b0ed0af..6d52d0b 100644 --- a/docs/openstatus.1 +++ b/docs/openstatus.1 @@ -1,20 +1,22 @@ '\" t -.\" Automatically generated by Pandoc 3.10.1 +.\" Automatically generated by Pandoc 3.12.1 .\" .TH "" "" "" "" .SH OpenStatus CLI .SS CLI interface \- openstatus OpenStatus CLI lets you manage your status pages and uptime monitors from the command line. -Report and track incidents, define monitors as code, and run on\-demand -checks. -Get started: openstatus login Save your API token openstatus -status\-report create Report an incident openstatus status\-report list -View active incidents openstatus maintenance create Schedule a -maintenance window openstatus maintenance list View maintenance windows -openstatus monitors apply Sync monitors from config openstatus monitors -list List your monitors openstatus run Run synthetic tests openstatus pl -list List your private locations https://docs.openstatus.dev | +Declare and run incidents, post public status updates, define monitors +as code, and run on\-demand checks. +Get started: openstatus login Save your API token openstatus incident +declare Declare an incident openstatus incident list View incidents +openstatus status\-report create Post a public status update openstatus +status\-report list View status reports openstatus maintenance create +Schedule a maintenance window openstatus maintenance list View +maintenance windows openstatus monitors apply Sync monitors from config +openstatus monitors list List your monitors openstatus run Run synthetic +tests openstatus pl list List your private locations +https://docs.openstatus.dev | https://github.com/openstatusHQ/cli/issues/new. .PP Manage status pages, monitors, and incidents from the terminal. @@ -197,6 +199,9 @@ Creates or updates monitors according to the OpenStatus configuration file. Compares your openstatus.yaml with the current state and applies changes. +DEPRECATED: this command is deprecated. +Prefer managing your monitors with Terraform via `openstatus terraform +generate'. .PP Usage: .IP @@ -393,6 +398,8 @@ monitors.yaml .PP Import all your monitors from your workspace to a YAML file; it will also create a lock file to manage your monitors with `apply'. +DEPRECATED: the monitors.yaml config file is deprecated for import. +Prefer managing monitors declaratively with `openstatus monitors apply'. .PP Usage: .IP @@ -967,6 +974,16 @@ T}@T{ T}@T{ \f[I]none\f[R] T} +T{ +\f[CR]\-\-incident\-id=\(dq\&...\(dq\f[R] +T}@T{ +ID of an incident to link the report to +T}@T{ +string +T}@T{ +T}@T{ +\f[I]none\f[R] +T} .TE .SS \f[CR]status\-report update\f[R] subcommand Update status report metadata. @@ -1178,6 +1195,1137 @@ T}@T{ \f[I]none\f[R] T} .TE +.SS \f[CR]incident\f[R] command (aliases: \f[CR]inc\f[R], \f[CR]incidents\f[R]) +Declare and run incidents. +.PP +Incidents are the internal response to an outage: severity, commander, +lifecycle (open \-> mitigated \-> resolved, or canceled), timeline +notes, a linked public status report and the postmortem. +Use `openstatus status\-report' for the public communication on a status +page. +.PP +Usage: +.IP +.EX +$ openstatus [GLOBAL FLAGS] incident [ARGUMENTS...] +.EE +.SS \f[CR]incident list\f[R] subcommand +List incidents. +.RS +.PP +openstatus incident list openstatus inc list \(enactive openstatus inc +list \(enstatus open,mitigated \(enlimit 10 +.RE +.PP +Usage: +.IP +.EX +$ openstatus [GLOBAL FLAGS] incident list [COMMAND FLAGS] [ARGUMENTS...] +.EE +.PP +The following flags are supported: +.PP +.TS +tab(@); +lw(13.6n) lw(34.3n) lw(3.8n) cw(7.0n) cw(11.3n). +T{ +Name +T}@T{ +Description +T}@T{ +Type +T}@T{ +Default value +T}@T{ +Environment variables +T} +_ +T{ +\f[CR]\-\-access\-token=\(dq\&...\(dq\f[R] (\f[CR]\-t\f[R]) +T}@T{ +OpenStatus API Access Token +T}@T{ +string +T}@T{ +T}@T{ +\f[CR]OPENSTATUS_API_TOKEN\f[R] +T} +T{ +\f[CR]\-\-status=\(dq\&...\(dq\f[R] +T}@T{ +Filter by status, comma\-separated (open, mitigated, resolved, canceled) +T}@T{ +string +T}@T{ +T}@T{ +\f[I]none\f[R] +T} +T{ +\f[CR]\-\-active\f[R] +T}@T{ +Only incidents that are not closed +T}@T{ +bool +T}@T{ +\f[CR]false\f[R] +T}@T{ +\f[I]none\f[R] +T} +T{ +\f[CR]\-\-closed\f[R] +T}@T{ +Only closed incidents +T}@T{ +bool +T}@T{ +\f[CR]false\f[R] +T}@T{ +\f[I]none\f[R] +T} +T{ +\f[CR]\-\-limit=\(dq\&...\(dq\f[R] +T}@T{ +Maximum number of incidents to return (1\-100, defaults to 50) +T}@T{ +int +T}@T{ +\f[CR]0\f[R] +T}@T{ +\f[I]none\f[R] +T} +T{ +\f[CR]\-\-offset=\(dq\&...\(dq\f[R] +T}@T{ +Number of incidents to skip +T}@T{ +int +T}@T{ +\f[CR]0\f[R] +T}@T{ +\f[I]none\f[R] +T} +.TE +.SS \f[CR]incident info\f[R] subcommand +Get incident details and timeline. +.RS +.PP +openstatus incident info openstatus inc info 42 +.RE +.PP +Usage: +.IP +.EX +$ openstatus [GLOBAL FLAGS] incident info [COMMAND FLAGS] [ARGUMENTS...] +.EE +.PP +The following flags are supported: +.PP +.TS +tab(@); +lw(19.3n) lw(19.3n) lw(5.3n) cw(10.0n) cw(16.0n). +T{ +Name +T}@T{ +Description +T}@T{ +Type +T}@T{ +Default value +T}@T{ +Environment variables +T} +_ +T{ +\f[CR]\-\-access\-token=\(dq\&...\(dq\f[R] (\f[CR]\-t\f[R]) +T}@T{ +OpenStatus API Access Token +T}@T{ +string +T}@T{ +T}@T{ +\f[CR]OPENSTATUS_API_TOKEN\f[R] +T} +.TE +.SS \f[CR]incident declare\f[R] subcommand (aliases: \f[CR]create\f[R]) +Declare a new incident. +.RS +.PP +openstatus incident declare \(entitle \(lqCheckout API returns 502\(rq +\(enseverity major openstatus inc declare \(entitle \(lqDatabase +down\(rq \(enseverity critical \(encommander jane\(atexample.com +\(enslack ID=$(openstatus inc declare \(entitle \(lqLogin errors\(rq +\(enseverity minor \-q) +.RE +.PP +Declare a new incident in the open status. +Run without \(entitle or \(enseverity in an interactive terminal to be +prompted. +In scripts, pass every required flag. +.PP +Usage: +.IP +.EX +$ openstatus [GLOBAL FLAGS] incident declare [COMMAND FLAGS] [ARGUMENTS...] +.EE +.PP +The following flags are supported: +.PP +.TS +tab(@); +lw(15.4n) lw(29.7n) lw(4.2n) cw(8.0n) cw(12.7n). +T{ +Name +T}@T{ +Description +T}@T{ +Type +T}@T{ +Default value +T}@T{ +Environment variables +T} +_ +T{ +\f[CR]\-\-access\-token=\(dq\&...\(dq\f[R] (\f[CR]\-t\f[R]) +T}@T{ +OpenStatus API Access Token +T}@T{ +string +T}@T{ +T}@T{ +\f[CR]OPENSTATUS_API_TOKEN\f[R] +T} +T{ +\f[CR]\-\-title=\(dq\&...\(dq\f[R] +T}@T{ +Title of the incident (1\-256 characters) +T}@T{ +string +T}@T{ +T}@T{ +\f[I]none\f[R] +T} +T{ +\f[CR]\-\-severity=\(dq\&...\(dq\f[R] +T}@T{ +Severity of the incident (critical, major, minor) +T}@T{ +string +T}@T{ +T}@T{ +\f[I]none\f[R] +T} +T{ +\f[CR]\-\-summary=\(dq\&...\(dq\f[R] +T}@T{ +Short human summary +T}@T{ +string +T}@T{ +T}@T{ +\f[I]none\f[R] +T} +T{ +\f[CR]\-\-commander=\(dq\&...\(dq\f[R] +T}@T{ +Email of the workspace member leading the response +T}@T{ +string +T}@T{ +T}@T{ +\f[I]none\f[R] +T} +T{ +\f[CR]\-\-started\-at=\(dq\&...\(dq\f[R] +T}@T{ +When the impact began (RFC 3339, defaults to now) +T}@T{ +string +T}@T{ +T}@T{ +\f[I]none\f[R] +T} +T{ +\f[CR]\-\-status\-report\-id=\(dq\&...\(dq\f[R] +T}@T{ +ID of an existing status report to link +T}@T{ +string +T}@T{ +T}@T{ +\f[I]none\f[R] +T} +T{ +\f[CR]\-\-slack\f[R] +T}@T{ +Open a dedicated Slack channel when Slack is connected +T}@T{ +bool +T}@T{ +\f[CR]false\f[R] +T}@T{ +\f[I]none\f[R] +T} +.TE +.SS \f[CR]incident update\f[R] subcommand +Edit an incident\(cqs title, severity, summary, commander or start time. +.RS +.PP +openstatus incident update [flags] openstatus inc update 42 +\(enseverity critical openstatus inc update 42 \(encommander +jane\(atexample.com openstatus inc update 42 \(enclear\-summary +.RE +.PP +Usage: +.IP +.EX +$ openstatus [GLOBAL FLAGS] incident update [COMMAND FLAGS] [ARGUMENTS...] +.EE +.PP +The following flags are supported: +.PP +.TS +tab(@); +lw(17.7n) lw(23.7n) lw(4.9n) cw(9.1n) cw(14.6n). +T{ +Name +T}@T{ +Description +T}@T{ +Type +T}@T{ +Default value +T}@T{ +Environment variables +T} +_ +T{ +\f[CR]\-\-access\-token=\(dq\&...\(dq\f[R] (\f[CR]\-t\f[R]) +T}@T{ +OpenStatus API Access Token +T}@T{ +string +T}@T{ +T}@T{ +\f[CR]OPENSTATUS_API_TOKEN\f[R] +T} +T{ +\f[CR]\-\-title=\(dq\&...\(dq\f[R] +T}@T{ +New title (1\-256 characters) +T}@T{ +string +T}@T{ +T}@T{ +\f[I]none\f[R] +T} +T{ +\f[CR]\-\-severity=\(dq\&...\(dq\f[R] +T}@T{ +New severity (critical, major, minor) +T}@T{ +string +T}@T{ +T}@T{ +\f[I]none\f[R] +T} +T{ +\f[CR]\-\-summary=\(dq\&...\(dq\f[R] +T}@T{ +New summary +T}@T{ +string +T}@T{ +T}@T{ +\f[I]none\f[R] +T} +T{ +\f[CR]\-\-clear\-summary\f[R] +T}@T{ +Remove the summary +T}@T{ +bool +T}@T{ +\f[CR]false\f[R] +T}@T{ +\f[I]none\f[R] +T} +T{ +\f[CR]\-\-commander=\(dq\&...\(dq\f[R] +T}@T{ +Email of the new commander +T}@T{ +string +T}@T{ +T}@T{ +\f[I]none\f[R] +T} +T{ +\f[CR]\-\-clear\-commander\f[R] +T}@T{ +Unassign the commander +T}@T{ +bool +T}@T{ +\f[CR]false\f[R] +T}@T{ +\f[I]none\f[R] +T} +T{ +\f[CR]\-\-started\-at=\(dq\&...\(dq\f[R] +T}@T{ +New start of impact (RFC 3339) +T}@T{ +string +T}@T{ +T}@T{ +\f[I]none\f[R] +T} +.TE +.SS \f[CR]incident set\-status\f[R] subcommand +Move an incident to a new status. +.RS +.PP +openstatus incident set\-status \(enstatus + [\(ennote \(lq\&...\(rq] openstatus +inc set\-status 42 \(enstatus mitigated \(ennote \(lqRolled back the +deploy\(rq +.RE +.PP +Allowed transitions: open \-> mitigated, resolved or canceled; mitigated +\-> resolved, open or canceled; resolved \-> open. +Canceled is terminal and closes the incident. +A linked status report is not updated: post the public update with +`openstatus status\-report add\-update'. +.PP +Usage: +.IP +.EX +$ openstatus [GLOBAL FLAGS] incident set\-status [COMMAND FLAGS] [ARGUMENTS...] +.EE +.PP +The following flags are supported: +.PP +.TS +tab(@); +lw(15.7n) lw(28.8n) lw(4.3n) cw(8.1n) cw(13.0n). +T{ +Name +T}@T{ +Description +T}@T{ +Type +T}@T{ +Default value +T}@T{ +Environment variables +T} +_ +T{ +\f[CR]\-\-access\-token=\(dq\&...\(dq\f[R] (\f[CR]\-t\f[R]) +T}@T{ +OpenStatus API Access Token +T}@T{ +string +T}@T{ +T}@T{ +\f[CR]OPENSTATUS_API_TOKEN\f[R] +T} +T{ +\f[CR]\-\-status=\(dq\&...\(dq\f[R] +T}@T{ +Target status (open, mitigated, resolved, canceled) +T}@T{ +string +T}@T{ +T}@T{ +\f[I]none\f[R] +T} +T{ +\f[CR]\-\-note=\(dq\&...\(dq\f[R] +T}@T{ +Note recorded on the timeline with the change +T}@T{ +string +T}@T{ +T}@T{ +\f[I]none\f[R] +T} +T{ +\f[CR]\-\-auto\-accept\f[R] (\f[CR]\-y\f[R]) +T}@T{ +Automatically accept the prompt +T}@T{ +bool +T}@T{ +\f[CR]false\f[R] +T}@T{ +\f[I]none\f[R] +T} +.TE +.SS \f[CR]incident mitigate\f[R] subcommand +Mark an incident as mitigated. +.RS +.PP +openstatus incident mitigate [\(ennote \(lq\&...\(rq] openstatus inc +mitigate 42 \(ennote \(lq\&...\(rq +.RE +.PP +Usage: +.IP +.EX +$ openstatus [GLOBAL FLAGS] incident mitigate [COMMAND FLAGS] [ARGUMENTS...] +.EE +.PP +The following flags are supported: +.PP +.TS +tab(@); +lw(16.5n) lw(26.7n) lw(4.6n) cw(8.5n) cw(13.7n). +T{ +Name +T}@T{ +Description +T}@T{ +Type +T}@T{ +Default value +T}@T{ +Environment variables +T} +_ +T{ +\f[CR]\-\-access\-token=\(dq\&...\(dq\f[R] (\f[CR]\-t\f[R]) +T}@T{ +OpenStatus API Access Token +T}@T{ +string +T}@T{ +T}@T{ +\f[CR]OPENSTATUS_API_TOKEN\f[R] +T} +T{ +\f[CR]\-\-note=\(dq\&...\(dq\f[R] +T}@T{ +Note recorded on the timeline with the change +T}@T{ +string +T}@T{ +T}@T{ +\f[I]none\f[R] +T} +.TE +.SS \f[CR]incident resolve\f[R] subcommand +Mark an incident as resolved. +.RS +.PP +openstatus incident resolve [\(ennote \(lq\&...\(rq] openstatus inc +resolve 42 \(ennote \(lq\&...\(rq +.RE +.PP +Usage: +.IP +.EX +$ openstatus [GLOBAL FLAGS] incident resolve [COMMAND FLAGS] [ARGUMENTS...] +.EE +.PP +The following flags are supported: +.PP +.TS +tab(@); +lw(16.5n) lw(26.7n) lw(4.6n) cw(8.5n) cw(13.7n). +T{ +Name +T}@T{ +Description +T}@T{ +Type +T}@T{ +Default value +T}@T{ +Environment variables +T} +_ +T{ +\f[CR]\-\-access\-token=\(dq\&...\(dq\f[R] (\f[CR]\-t\f[R]) +T}@T{ +OpenStatus API Access Token +T}@T{ +string +T}@T{ +T}@T{ +\f[CR]OPENSTATUS_API_TOKEN\f[R] +T} +T{ +\f[CR]\-\-note=\(dq\&...\(dq\f[R] +T}@T{ +Note recorded on the timeline with the change +T}@T{ +string +T}@T{ +T}@T{ +\f[I]none\f[R] +T} +.TE +.SS \f[CR]incident reopen\f[R] subcommand +Reopen a mitigated or resolved incident. +.RS +.PP +openstatus incident reopen [\(ennote \(lq\&...\(rq] openstatus inc +reopen 42 \(ennote \(lq\&...\(rq +.RE +.PP +Usage: +.IP +.EX +$ openstatus [GLOBAL FLAGS] incident reopen [COMMAND FLAGS] [ARGUMENTS...] +.EE +.PP +The following flags are supported: +.PP +.TS +tab(@); +lw(16.5n) lw(26.7n) lw(4.6n) cw(8.5n) cw(13.7n). +T{ +Name +T}@T{ +Description +T}@T{ +Type +T}@T{ +Default value +T}@T{ +Environment variables +T} +_ +T{ +\f[CR]\-\-access\-token=\(dq\&...\(dq\f[R] (\f[CR]\-t\f[R]) +T}@T{ +OpenStatus API Access Token +T}@T{ +string +T}@T{ +T}@T{ +\f[CR]OPENSTATUS_API_TOKEN\f[R] +T} +T{ +\f[CR]\-\-note=\(dq\&...\(dq\f[R] +T}@T{ +Note recorded on the timeline with the change +T}@T{ +string +T}@T{ +T}@T{ +\f[I]none\f[R] +T} +.TE +.SS \f[CR]incident cancel\f[R] subcommand +Cancel an incident (closes it). +.RS +.PP +openstatus incident cancel [\(ennote \(lq\&...\(rq] openstatus inc +cancel 42 \(ennote \(lq\&...\(rq +.RE +.PP +Usage: +.IP +.EX +$ openstatus [GLOBAL FLAGS] incident cancel [COMMAND FLAGS] [ARGUMENTS...] +.EE +.PP +The following flags are supported: +.PP +.TS +tab(@); +lw(16.5n) lw(26.7n) lw(4.6n) cw(8.5n) cw(13.7n). +T{ +Name +T}@T{ +Description +T}@T{ +Type +T}@T{ +Default value +T}@T{ +Environment variables +T} +_ +T{ +\f[CR]\-\-access\-token=\(dq\&...\(dq\f[R] (\f[CR]\-t\f[R]) +T}@T{ +OpenStatus API Access Token +T}@T{ +string +T}@T{ +T}@T{ +\f[CR]OPENSTATUS_API_TOKEN\f[R] +T} +T{ +\f[CR]\-\-note=\(dq\&...\(dq\f[R] +T}@T{ +Note recorded on the timeline with the change +T}@T{ +string +T}@T{ +T}@T{ +\f[I]none\f[R] +T} +T{ +\f[CR]\-\-auto\-accept\f[R] (\f[CR]\-y\f[R]) +T}@T{ +Automatically accept the prompt +T}@T{ +bool +T}@T{ +\f[CR]false\f[R] +T}@T{ +\f[I]none\f[R] +T} +.TE +.SS \f[CR]incident note\f[R] subcommand +Add a note to an incident timeline. +.RS +.PP +openstatus incident note \(enmessage \(lqRolled back the deploy\(rq +echo \(lqmulti\-line markdown\(rq | openstatus inc note 42 \(enmessage +\- +.RE +.PP +Usage: +.IP +.EX +$ openstatus [GLOBAL FLAGS] incident note [COMMAND FLAGS] [ARGUMENTS...] +.EE +.PP +The following flags are supported: +.PP +.TS +tab(@); +lw(13.9n) lw(33.6n) lw(3.8n) cw(7.2n) cw(11.5n). +T{ +Name +T}@T{ +Description +T}@T{ +Type +T}@T{ +Default value +T}@T{ +Environment variables +T} +_ +T{ +\f[CR]\-\-access\-token=\(dq\&...\(dq\f[R] (\f[CR]\-t\f[R]) +T}@T{ +OpenStatus API Access Token +T}@T{ +string +T}@T{ +T}@T{ +\f[CR]OPENSTATUS_API_TOKEN\f[R] +T} +T{ +\f[CR]\-\-message=\(dq\&...\(dq\f[R] (\f[CR]\-m\f[R]) +T}@T{ +Note text in markdown (1\-10000 characters); use \- to read from stdin +T}@T{ +string +T}@T{ +T}@T{ +\f[I]none\f[R] +T} +.TE +.SS \f[CR]incident link\-report\f[R] subcommand +Link a public status report to an incident. +.RS +.PP +openstatus incident link\-report openstatus inc link\-report 42 123 +.RE +.PP +Usage: +.IP +.EX +$ openstatus [GLOBAL FLAGS] incident link\-report [COMMAND FLAGS] [ARGUMENTS...] +.EE +.PP +The following flags are supported: +.PP +.TS +tab(@); +lw(19.3n) lw(19.3n) lw(5.3n) cw(10.0n) cw(16.0n). +T{ +Name +T}@T{ +Description +T}@T{ +Type +T}@T{ +Default value +T}@T{ +Environment variables +T} +_ +T{ +\f[CR]\-\-access\-token=\(dq\&...\(dq\f[R] (\f[CR]\-t\f[R]) +T}@T{ +OpenStatus API Access Token +T}@T{ +string +T}@T{ +T}@T{ +\f[CR]OPENSTATUS_API_TOKEN\f[R] +T} +.TE +.SS \f[CR]incident unlink\-report\f[R] subcommand +Remove the link to an incident\(cqs status report. +.RS +.PP +openstatus incident unlink\-report openstatus inc unlink\-report 42 +.RE +.PP +Usage: +.IP +.EX +$ openstatus [GLOBAL FLAGS] incident unlink\-report [COMMAND FLAGS] [ARGUMENTS...] +.EE +.PP +The following flags are supported: +.PP +.TS +tab(@); +lw(19.3n) lw(19.3n) lw(5.3n) cw(10.0n) cw(16.0n). +T{ +Name +T}@T{ +Description +T}@T{ +Type +T}@T{ +Default value +T}@T{ +Environment variables +T} +_ +T{ +\f[CR]\-\-access\-token=\(dq\&...\(dq\f[R] (\f[CR]\-t\f[R]) +T}@T{ +OpenStatus API Access Token +T}@T{ +string +T}@T{ +T}@T{ +\f[CR]OPENSTATUS_API_TOKEN\f[R] +T} +.TE +.SS \f[CR]incident close\f[R] subcommand +Close a resolved incident. +.RS +.PP +openstatus incident close openstatus inc close 42 \(enskip\-postmortem +\-y +.RE +.PP +Close a resolved incident. +A closed incident is read\-only except for its postmortem. +Requires an approved postmortem, or \(enskip\-postmortem. +.PP +Usage: +.IP +.EX +$ openstatus [GLOBAL FLAGS] incident close [COMMAND FLAGS] [ARGUMENTS...] +.EE +.PP +The following flags are supported: +.PP +.TS +tab(@); +lw(17.8n) lw(23.3n) lw(4.9n) cw(9.2n) cw(14.7n). +T{ +Name +T}@T{ +Description +T}@T{ +Type +T}@T{ +Default value +T}@T{ +Environment variables +T} +_ +T{ +\f[CR]\-\-access\-token=\(dq\&...\(dq\f[R] (\f[CR]\-t\f[R]) +T}@T{ +OpenStatus API Access Token +T}@T{ +string +T}@T{ +T}@T{ +\f[CR]OPENSTATUS_API_TOKEN\f[R] +T} +T{ +\f[CR]\-\-skip\-postmortem\f[R] +T}@T{ +Close without an approved postmortem +T}@T{ +bool +T}@T{ +\f[CR]false\f[R] +T}@T{ +\f[I]none\f[R] +T} +T{ +\f[CR]\-\-auto\-accept\f[R] (\f[CR]\-y\f[R]) +T}@T{ +Automatically accept the prompt +T}@T{ +bool +T}@T{ +\f[CR]false\f[R] +T}@T{ +\f[I]none\f[R] +T} +.TE +.SS \f[CR]incident delete\f[R] subcommand +Delete an incident declared by mistake. +.RS +.PP +openstatus incident delete openstatus inc delete 42 \-y +.RE +.PP +Delete an incident declared by mistake. +Only allowed while the incident is open and was never mitigated, +resolved or closed; cancel it otherwise. +.PP +Usage: +.IP +.EX +$ openstatus [GLOBAL FLAGS] incident delete [COMMAND FLAGS] [ARGUMENTS...] +.EE +.PP +The following flags are supported: +.PP +.TS +tab(@); +lw(18.6n) lw(21.2n) lw(5.1n) cw(9.6n) cw(15.4n). +T{ +Name +T}@T{ +Description +T}@T{ +Type +T}@T{ +Default value +T}@T{ +Environment variables +T} +_ +T{ +\f[CR]\-\-access\-token=\(dq\&...\(dq\f[R] (\f[CR]\-t\f[R]) +T}@T{ +OpenStatus API Access Token +T}@T{ +string +T}@T{ +T}@T{ +\f[CR]OPENSTATUS_API_TOKEN\f[R] +T} +T{ +\f[CR]\-\-auto\-accept\f[R] (\f[CR]\-y\f[R]) +T}@T{ +Automatically accept the prompt +T}@T{ +bool +T}@T{ +\f[CR]false\f[R] +T}@T{ +\f[I]none\f[R] +T} +.TE +.SS \f[CR]incident postmortem\f[R] subcommand (aliases: \f[CR]pm\f[R]) +Read, write and approve an incident\(cqs postmortem. +.PP +Usage: +.IP +.EX +$ openstatus [GLOBAL FLAGS] incident postmortem [ARGUMENTS...] +.EE +.SS \f[CR]incident postmortem show\f[R] subcommand +Show the postmortem of an incident. +.RS +.PP +openstatus incident postmortem show openstatus inc pm show 42 > +postmortem.md +.RE +.PP +In a terminal, prints the review status and the markdown body through +your pager. +When piped, prints only the markdown body, so it can be edited and sent +back with `openstatus inc pm edit \(enfile postmortem.md'. +.PP +Usage: +.IP +.EX +$ openstatus [GLOBAL FLAGS] incident postmortem show [COMMAND FLAGS] [ARGUMENTS...] +.EE +.PP +The following flags are supported: +.PP +.TS +tab(@); +lw(19.3n) lw(19.3n) lw(5.3n) cw(10.0n) cw(16.0n). +T{ +Name +T}@T{ +Description +T}@T{ +Type +T}@T{ +Default value +T}@T{ +Environment variables +T} +_ +T{ +\f[CR]\-\-access\-token=\(dq\&...\(dq\f[R] (\f[CR]\-t\f[R]) +T}@T{ +OpenStatus API Access Token +T}@T{ +string +T}@T{ +T}@T{ +\f[CR]OPENSTATUS_API_TOKEN\f[R] +T} +.TE +.SS \f[CR]incident postmortem edit\f[R] subcommand +Write or replace the postmortem of a resolved incident. +.RS +.PP +openstatus incident postmortem edit \(enfile postmortem.md cat +postmortem.md | openstatus inc pm edit 42 \(enfile \- openstatus inc pm +edit 42 \(encontent \(lq## Summary \&...\(rq +.RE +.PP +Replaces the whole markdown body. +An approved postmortem stays approved. +.PP +Usage: +.IP +.EX +$ openstatus [GLOBAL FLAGS] incident postmortem edit [COMMAND FLAGS] [ARGUMENTS...] +.EE +.PP +The following flags are supported: +.PP +.TS +tab(@); +lw(16.0n) lw(28.1n) lw(4.4n) cw(8.3n) cw(13.2n). +T{ +Name +T}@T{ +Description +T}@T{ +Type +T}@T{ +Default value +T}@T{ +Environment variables +T} +_ +T{ +\f[CR]\-\-access\-token=\(dq\&...\(dq\f[R] (\f[CR]\-t\f[R]) +T}@T{ +OpenStatus API Access Token +T}@T{ +string +T}@T{ +T}@T{ +\f[CR]OPENSTATUS_API_TOKEN\f[R] +T} +T{ +\f[CR]\-\-file=\(dq\&...\(dq\f[R] +T}@T{ +Markdown file to upload; use \- to read from stdin +T}@T{ +string +T}@T{ +T}@T{ +\f[I]none\f[R] +T} +T{ +\f[CR]\-\-content=\(dq\&...\(dq\f[R] +T}@T{ +Markdown body passed inline +T}@T{ +string +T}@T{ +T}@T{ +\f[I]none\f[R] +T} +.TE +.SS \f[CR]incident postmortem approve\f[R] subcommand +Approve the postmortem, optionally closing the incident. +.RS +.PP +openstatus incident postmortem approve openstatus inc pm approve 42 +\(enclose \-y +.RE +.PP +Usage: +.IP +.EX +$ openstatus [GLOBAL FLAGS] incident postmortem approve [COMMAND FLAGS] [ARGUMENTS...] +.EE +.PP +The following flags are supported: +.PP +.TS +tab(@); +lw(18.6n) lw(21.2n) lw(5.1n) cw(9.6n) cw(15.4n). +T{ +Name +T}@T{ +Description +T}@T{ +Type +T}@T{ +Default value +T}@T{ +Environment variables +T} +_ +T{ +\f[CR]\-\-access\-token=\(dq\&...\(dq\f[R] (\f[CR]\-t\f[R]) +T}@T{ +OpenStatus API Access Token +T}@T{ +string +T}@T{ +T}@T{ +\f[CR]OPENSTATUS_API_TOKEN\f[R] +T} +T{ +\f[CR]\-\-close\f[R] +T}@T{ +Also close the incident +T}@T{ +bool +T}@T{ +\f[CR]false\f[R] +T}@T{ +\f[I]none\f[R] +T} +T{ +\f[CR]\-\-auto\-accept\f[R] (\f[CR]\-y\f[R]) +T}@T{ +Automatically accept the prompt +T}@T{ +bool +T}@T{ +\f[CR]false\f[R] +T}@T{ +\f[I]none\f[R] +T} +.TE .SS \f[CR]maintenance\f[R] command (aliases: \f[CR]mt\f[R]) Manage maintenance windows. .PP diff --git a/internal/cmd/app.go b/internal/cmd/app.go index cfa147f..587eb10 100644 --- a/internal/cmd/app.go +++ b/internal/cmd/app.go @@ -33,13 +33,15 @@ func NewApp() *cli.Command { EnableShellCompletion: true, Usage: "Manage status pages, monitors, and incidents from the terminal", Description: `OpenStatus CLI lets you manage your status pages and uptime monitors -from the command line. Report and track incidents, define monitors as code, -and run on-demand checks. +from the command line. Declare and run incidents, post public status updates, +define monitors as code, and run on-demand checks. Get started: openstatus login Save your API token - openstatus status-report create Report an incident - openstatus status-report list View active incidents + openstatus incident declare Declare an incident + openstatus incident list View incidents + openstatus status-report create Post a public status update + openstatus status-report list View status reports openstatus maintenance create Schedule a maintenance window openstatus maintenance list View maintenance windows openstatus monitors apply Sync monitors from config diff --git a/skills/cli/SKILL.md b/skills/cli/SKILL.md index 113605e..0f8ebfa 100644 --- a/skills/cli/SKILL.md +++ b/skills/cli/SKILL.md @@ -1,14 +1,14 @@ --- name: openstatus-cli description: | - OpenStatus CLI for managing uptime monitors, incident reports, status pages, notifications, maintenance windows, synthetic tests, monitor response logs, and ad-hoc global HTTP checks. Use this skill whenever the user wants to monitor a website or API, set up uptime checks, create or manage monitors, inspect monitor response logs or debug why a check failed, report an incident, update a status page, view notifications, schedule maintenance, run synthetic tests, check latency or availability from around the world, run an ad-hoc speed check, define monitors as code, generate Terraform configuration, export to Terraform, log in or out, or use the openstatus command. Also trigger when the user says "is my site up", "check my endpoint", "speed check", "global latency", "latency from regions", "ad-hoc check", "test from multiple regions", "show monitor logs", "response logs", "why did my monitor fail", "see the failed requests", "create a status report", "set component impact", "monitor this URL", "run uptime tests", "set up monitoring", "our API is down", "schedule maintenance", "maintenance window", "planned downtime", "terraform", "generate terraform", "export to terraform", "infrastructure as code", "list notifications", "notification channels", "log in to openstatus", "save my api token", or mentions openstatus in any context. This skill knows the full CLI — commands, flags, config format, and workflows — so Claude can act without guessing. + OpenStatus CLI for managing uptime monitors, incidents (declare, run, postmortem), public status reports, status pages, notifications, maintenance windows, synthetic tests, monitor response logs, and ad-hoc global HTTP checks. Use this skill whenever the user wants to monitor a website or API, set up uptime checks, create or manage monitors, inspect monitor response logs or debug why a check failed, declare or run an incident, write or approve a postmortem, report an incident publicly, update a status page, view notifications, schedule maintenance, run synthetic tests, check latency or availability from around the world, run an ad-hoc speed check, define monitors as code, generate Terraform configuration, export to Terraform, log in or out, or use the openstatus command. Also trigger when the user says "is my site up", "check my endpoint", "speed check", "global latency", "latency from regions", "ad-hoc check", "test from multiple regions", "show monitor logs", "response logs", "why did my monitor fail", "see the failed requests", "create a status report", "set component impact", "monitor this URL", "run uptime tests", "set up monitoring", "our API is down", "we have an incident", "declare an incident", "open an incident", "incident commander", "mitigate", "resolve the incident", "close the incident", "postmortem", "post-mortem", "schedule maintenance", "maintenance window", "planned downtime", "terraform", "generate terraform", "export to terraform", "infrastructure as code", "list notifications", "notification channels", "log in to openstatus", "save my api token", or mentions openstatus in any context. This skill knows the full CLI — commands, flags, config format, and workflows — so Claude can act without guessing. allowed-tools: - Bash(openstatus *) --- # OpenStatus CLI -Manage uptime monitors, incident reports, status pages, notifications, and maintenance windows from the terminal. The CLI supports monitors-as-code via YAML config files. +Manage uptime monitors, incidents, public status reports, status pages, notifications, and maintenance windows from the terminal. The CLI supports monitors-as-code via YAML config files. Run `openstatus --help` or `openstatus --help` for full option details. @@ -42,12 +42,22 @@ Token resolution order: | Trigger a monitor now | `monitors trigger ` | Run an on-demand check across all regions | | Delete a monitor | `monitors delete ` | Remove a monitor | | Export monitors to YAML | `monitors import` | Pull existing monitors into an `openstatus.yaml` + lock file | -| Create incident report | `status-report create` | Something is broken, notify users | -| Add update to incident | `status-report add-update ` | Post a progress update on an ongoing incident | -| List incidents | `status-report list` | See active/recent incidents | -| Get incident details | `status-report info ` | View full incident timeline | -| Update incident metadata | `status-report update ` | Change title or components | -| Delete incident | `status-report delete ` | Remove a status report | +| Declare an incident | `incident declare` | Something is broken — start the internal response first | +| List incidents | `incident list` | See open/recent incidents (`--active`, `--closed`, `--status`) | +| Get incident details + timeline | `incident info ` | Severity, commander, allowed transitions, timeline | +| Edit an incident | `incident update ` | Change title, severity, summary, commander or start time | +| Change incident status | `incident mitigate/resolve/reopen/cancel ` or `incident set-status --status …` | Move through the lifecycle, optionally with `--note` | +| Add a timeline note | `incident note --message …` | Record what happened or what was tried | +| Link a status report | `incident link-report ` / `unlink-report ` | Connect the public report to the incident | +| Close an incident | `incident close ` | After it is resolved and the postmortem is approved (or `--skip-postmortem`) | +| Delete an incident | `incident delete ` | Only for incidents declared by mistake (still open, never mitigated) | +| Read/write/approve the postmortem | `incident postmortem show/edit/approve ` | After the incident is resolved | +| Create public status report | `status-report create` | Users are affected — publish on the status page (link with `--incident-id`) | +| Add update to status report | `status-report add-update ` | Post a public progress update | +| List status reports | `status-report list` | See active/recent public reports | +| Get status report details | `status-report info ` | View the public update timeline | +| Update status report metadata | `status-report update ` | Change title or components | +| Delete status report | `status-report delete ` | Remove a status report | | List status pages | `status-page list` | See all your status pages | | Get status page details | `status-page info ` | View page config, components, theme | | List notifications | `notification list` | See all notification channels in the workspace | @@ -63,7 +73,7 @@ Token resolution order: | Save API token | `login` | Authenticate — paste your token from the dashboard | | Remove saved token | `logout` | Sign out (deletes the saved token) | -Command aliases: `check` = `c`, `monitors` = `m`, `status-report` = `sr`, `status-page` = `sp`, `notification` = `n`, `maintenance` = `mt`, `terraform` = `tf` (and `terraform generate` = `gen`), `run` = `r`, `whoami` = `w`. `login` and `logout` have no aliases. +Command aliases: `check` = `c`, `monitors` = `m`, `incident` = `inc` / `incidents` (and `incident declare` = `create`, `incident postmortem` = `pm`), `status-report` = `sr`, `status-page` = `sp`, `notification` = `n`, `maintenance` = `mt`, `terraform` = `tf` (and `terraform generate` = `gen`), `run` = `r`, `whoami` = `w`. `login` and `logout` have no aliases. ## Workflows @@ -119,9 +129,94 @@ This is the primary way to manage monitors. Write a YAML config, then let the CL **The apply workflow** compares your `openstatus.yaml` against the lock file and the API, then creates, updates, or deletes monitors to match. Use `--dry-run` to preview, `-y` to skip the confirmation prompt. -### Incident lifecycle +### Running an incident -Use status reports for **unplanned** outages and incidents. +**Incident vs. status report:** an **incident** is the internal response — severity, commander, lifecycle, timeline notes and the postmortem. A **status report** is the public communication on a status page. When something is broken ("our API is down", "we have an incident"), **declare an incident first**; then, if users are affected, publish a status report linked to it with `--incident-id`. Changing the incident status never updates the public report — post public updates with `status-report add-update`. + +Severities: `critical`, `major`, `minor`. Statuses: `open` -> `mitigated` -> `resolved`, or `canceled`. + +| From | Allowed transitions | +|------|---------------------| +| `open` | `mitigated`, `resolved`, `canceled` | +| `mitigated` | `resolved`, `open`, `canceled` | +| `resolved` | `open` | + +`canceled` is terminal and closes the incident. "Closed" is not a status: a closed incident keeps its last status, has a `closed_at` timestamp, and is read-only except for its postmortem. `incident info ` lists the allowed transitions from the current state. + +**1. Declare:** +```bash +openstatus incident declare \ + --title "Checkout API returns 502" \ + --severity major \ + --summary "Payments failing for EU customers" \ + --commander jane@example.com +``` + +Prints `Incident declared (ID: 42)` and the next step. Use `-q` to print only the ID: `ID=$(openstatus inc declare --title "…" --severity major -q)`. + +**`declare` flags:** + +| Flag | Required | Description | +|------|----------|-------------| +| `--title` | yes | 1-256 characters | +| `--severity` | yes | `critical`, `major` or `minor` | +| `--summary` | no | Short human summary | +| `--commander` | no | Email of the workspace member leading the response (emailed when assigned) | +| `--started-at` | no | RFC 3339 start of impact, defaults to now; can be in the past | +| `--status-report-id` | no | Link an existing status report | +| `--slack` | no | Open a dedicated Slack channel when Slack is connected | + +> **Interactive vs. scripted:** without `--title` or `--severity`, `declare` prompts on a terminal; with `--json` or a non-TTY stdin it fails with `missing required flags: …`. Always pass both when scripting. + +**2. Publish the public status report, linked to the incident** (only if users are affected — see [Public status reports](#public-status-reports)): +```bash +openstatus status-report create --title "Checkout issues" --status investigating \ + --message "We are investigating failed payments" --page-id 123 --incident-id 42 +``` +Or link an existing report: `openstatus incident link-report 42 456` (`unlink-report 42` removes it). + +**3. Record what happens and move the status:** +```bash +openstatus incident note 42 --message "Rolled back deploy 2026-10-16.3" +echo "multi-line markdown" | openstatus incident note 42 --message - +openstatus incident mitigate 42 --note "Traffic shifted to the healthy region" +openstatus incident resolve 42 --note "Error rate back to baseline" +openstatus incident reopen 42 --note "Errors are back" +openstatus incident set-status 42 --status resolved # generic form, for scripts +openstatus incident cancel 42 -y # declared in error but already mitigated: closes it +``` + +Edit metadata with `incident update 42 [--title …] [--severity …] [--summary … | --clear-summary] [--commander … | --clear-commander] [--started-at …]`. + +**4. Postmortem (after it is resolved), then close:** +```bash +openstatus incident postmortem edit 42 --file postmortem.md # or --file - (stdin), or --content "…" +openstatus incident postmortem show 42 # piped: raw markdown only +openstatus incident postmortem approve 42 --close -y # approve and close in one step +openstatus incident close 42 --skip-postmortem -y # close without a postmortem +``` + +`postmortem show 42 > pm.md`, edit, then `postmortem edit 42 --file pm.md` round-trips the body. + +**5. Inspect and list:** +```bash +openstatus incident info 42 # details + timeline, newest first +openstatus incident list # everything, newest declared first +openstatus incident list --active # not closed +openstatus incident list --status open,mitigated --limit 10 --offset 10 +``` + +**Rules agents must know:** +- `cancel` (and `set-status --status canceled`), `close`, `delete` and `postmortem approve --close` ask for confirmation; pass `-y` when not on a terminal. +- `delete` only works while the incident is open and was never mitigated; otherwise `cancel` it. +- `close` needs a resolved incident and an approved postmortem, or `--skip-postmortem`. +- `close`, `delete` and `postmortem approve` act as the API key's creator: they need a workspace owner/admin (or the incident commander for close/approve). API keys without a creator get `permission denied`. +- Every command that changes an incident prints the incident as JSON with `--json`, and only its ID with `-q`. +- A refused change (wrong transition, closed incident, report already linked) prints the server's reason plus a hint. + +### Public status reports + +Use status reports to communicate **unplanned** outages publicly on a status page. When there is an incident, link the report to it with `--incident-id`. Status reports follow a progression: `investigating` -> `identified` -> `monitoring` -> `resolved`. These are the only valid status values — the CLI rejects anything else. @@ -162,6 +257,7 @@ To add updates, run: openstatus status-report add-update 456 --status identified | `--component-ids` | no | **Legacy.** Comma-separated component IDs in a single string: `"id1,id2"` — marks them all affected without a specific impact level. Prefer `--impact`. Mutually exclusive with `--impact`. | | `--notify` | no | Send notification to status page subscribers | | `--date` | no | RFC 3339 timestamp (e.g. `2026-03-25T10:00:00Z`), defaults to now (UTC) | +| `--incident-id` | no | Link the report to an incident (fails if the incident is closed or already linked) | The four impact levels are `operational`, `degraded`, `partial_outage`, `major_outage` (`degraded_performance` is also accepted as an alias for `degraded`). Pass `--impact` once per component, e.g. `--impact comp-1=major_outage --impact comp-2=degraded`.