# checkly incidents - Checkly Docs

> Create, update, and resolve incidents on your status pages from the CLI.

Source: https://www.checklyhq.com/docs/cli/checkly-incidents/

---

Back to top
- Usage
- Subcommands
- checkly incidents list List Options
- List Examples

- checkly incidents create Create Options
- Create Examples

- checkly incidents update Update Options
- Update Examples

- checkly incidents resolve Resolve Options
- Resolve Examples

- Related Commands

CLI Commands

# checkly incidents

Create, update, and resolve incidents on your status pages from the CLI.

Available since CLI v7.5.0.

The `checkly incidents` command lets you manage incidents on your status pages directly from the terminal. You can list, create, update, and resolve incidents, and optionally notify subscribers with each action.

Prerequisites

Before using `checkly incidents`, ensure you have:

- Checkly CLI installed

- Valid Checkly account authentication (run `npx checkly login` if needed)

- At least one status page configured in your Checkly account

For additional setup information, see [CLI overview](https://www.checklyhq.com/docs/cli/overview).

## ​ Usage

Terminal

```
npx checkly incidents [arguments] [options]
```

## ​ Subcommands

Subcommand Description

`list` List incidents, optionally filtered by status page or status.

`create` Declare a new incident on a status page.

`update` Post a progress update to an incident.

`resolve` Resolve an incident.

`create`, `update` and `resolve` show the planned change and ask for confirmation before they run. In CI or when an AI agent runs them, they don’t prompt: they print a `confirmation_required` summary and exit with code `3` without changing anything. Add `--force` to run them non-interactively.

## ​ `checkly incidents list`

List incidents, optionally filtered by status page or status.
**Usage:**
Terminal

```
npx checkly incidents list [options]
```

**Options:**
Option Required Description

`--limit, -l` - Number of incidents to return (1-100). Default: `25`.

`--status-page-id` - Filter incidents by status page ID.

`--status` - Filter by incident status: `open`, `resolved`, or `all`. Default: `open`.

`--output, -o` - Output format: `table`, `json`, or `md`. Default: `table`.

### ​ List Options

​

number

default: "25"

Number of incidents to return, between 1 and 100. **Usage:** Terminal

```
npx checkly incidents list --limit=50
npx checkly incidents list -l 10
```

​

string

Filter incidents to only those associated with a specific status page. **Usage:** Terminal

```
npx checkly incidents list --status-page-id=
```

​

string

default: "open"

Filter incidents by status. Available values: `open`, `resolved`, `all`. **Usage:** Terminal

```
npx checkly incidents list --status=open
npx checkly incidents list --status=resolved
npx checkly incidents list --status=all
```

​

string

default: "table"

Set the output format. Use `json` for programmatic access or `md` for markdown. **Usage:** Terminal

```
npx checkly incidents list --output=json
npx checkly incidents list -o md
```

### ​ List Examples

Terminal

```
# List all open incidents (default)
npx checkly incidents list

# List resolved incidents
npx checkly incidents list --status=resolved

# Filter by status page
npx checkly incidents list --status-page-id=

# Get results as JSON
npx checkly incidents list --output=json
```

## ​ `checkly incidents create`

Declare a new incident on a status page. By default, all services on the status page are affected. Use `--services` to specify individual services.
**Usage:**
Terminal

```
npx checkly incidents create [options]
```

**Options:**
Option Required Description

`--status-page-id` yes Target status page ID.

`--title` yes Incident title.

`--services` - Affected service IDs. Repeat the flag for multiple services.

`--severity` - Incident severity: `minor`, `medium`, `major`, or `critical`. Default: `minor`.

`--message` - Initial incident update message.

`--notify-subscribers` - Notify status page subscribers. Default: `true`. Use `--no-notify-subscribers` to disable.

`--output, -o` - Output format: `table`, `json`, or `md`. Default: `table`.

`--force, -f` - Skip the confirmation prompt.

`--dry-run` - Preview what would happen without executing.

### ​ Create Options

​

string

required

The ID of the status page to create the incident on. You can find status page IDs using `checkly status-pages list`. **Usage:** Terminal

```
npx checkly incidents create --status-page-id= --title="..."
```

​

string

required

The title of the incident. **Usage:** Terminal

```
npx checkly incidents create --status-page-id= --title="API degraded performance"
```

​

string

Specify affected service IDs. Repeat the flag to affect multiple services. If omitted, all services on the status page are affected. **Usage:** Terminal

```
npx checkly incidents create --status-page-id= --title="..." --services= --services=
```

​

string

default: "minor"

Set the incident severity. Available values: `minor`, `medium`, `major`, `critical`. **Usage:** Terminal

```
npx checkly incidents create --status-page-id= --title="..." --severity=major
```

​

string

Provide an initial incident update message. If omitted, a default message is used. **Usage:** Terminal

```
npx checkly incidents create --status-page-id= --title="..." --message="We are investigating elevated error rates."
```

​

boolean

default: "true"

Notify status page subscribers about this incident. Use `--no-notify-subscribers` to suppress notifications. **Usage:** Terminal

```
npx checkly incidents create --status-page-id= --title="..." --no-notify-subscribers
```

​

string

default: "table"

Set the output format. Use `json` for programmatic access or `md` for markdown. **Usage:** Terminal

```
npx checkly incidents create --status-page-id= --title="..." --output=json
```

### ​ Create Examples

Terminal

```
# Create a minor incident affecting all services
npx checkly incidents create --status-page-id= --title="Elevated error rates"

# Create a major incident with a custom message
npx checkly incidents create --status-page-id= --title="API outage" --severity=major --message="Our API is currently unavailable."

# Create an incident affecting specific services without notifying subscribers
npx checkly incidents create --status-page-id= --title="Degraded performance" --services= --no-notify-subscribers
```

## ​ `checkly incidents update`

Post a progress update to an existing incident. You can change the status and severity of the incident at the same time.
**Usage:**
Terminal

```
npx checkly incidents update [options]
```

**Arguments:**
Argument Description

`id` The ID of the incident to update.

**Options:**
Option Required Description

`--message` yes Update message.

`--status` - Incident progress status: `investigating`, `identified`, or `monitoring`. Default: `investigating`.

`--severity` - Update the overall incident severity: `minor`, `medium`, `major`, or `critical`.

`--notify-subscribers` - Notify status page subscribers. Default: `true`. Use `--no-notify-subscribers` to disable.

`--output, -o` - Output format: `table`, `json`, or `md`. Default: `table`.

`--force, -f` - Skip the confirmation prompt.

`--dry-run` - Preview what would happen without executing.

### ​ Update Options

​

string

required

The progress update message. **Usage:** Terminal

```
npx checkly incidents update --message="We have identified the root cause."
```

​

string

default: "investigating"

Set the incident progress status. Available values: `investigating`, `identified`, `monitoring`. **Usage:** Terminal

```
npx checkly incidents update --message="..." --status=identified
npx checkly incidents update --message="..." --status=monitoring
```

​

string

Update the overall incident severity. Available values: `minor`, `medium`, `major`, `critical`. **Usage:** Terminal

```
npx checkly incidents update --message="..." --severity=critical
```

​

boolean

default: "true"

Notify status page subscribers about this update. Use `--no-notify-subscribers` to suppress notifications. **Usage:** Terminal

```
npx checkly incidents update --message="..." --no-notify-subscribers
```

​

string

default: "table"

Set the output format. Use `json` for programmatic access or `md` for markdown. **Usage:** Terminal

```
npx checkly incidents update --message="..." --output=json
```

### ​ Update Examples

Terminal

```
# Post an investigating update
npx checkly incidents update --message="We are looking into the issue."

# Mark the root cause as identified
npx checkly incidents update --message="Root cause identified: database connection pool exhaustion." --status=identified

# Escalate severity and post an update
npx checkly incidents update --message="Impact is wider than initially assessed." --severity=critical

# Post a monitoring update without notifying subscribers
npx checkly incidents update --message="Fix deployed, monitoring for stability." --status=monitoring --no-notify-subscribers
```

## ​ `checkly incidents resolve`

Resolve an incident. This posts a final update with status `RESOLVED`.
**Usage:**
Terminal

```
npx checkly incidents resolve [options]
```

**Arguments:**
Argument Description

`id` The ID of the incident to resolve.

**Options:**
Option Required Description

`--message` - Optional closing note. If omitted, a default message is used.

`--notify-subscribers` - Notify status page subscribers. Default: `true`. Use `--no-notify-subscribers` to disable.

`--output, -o` - Output format: `table`, `json`, or `md`. Default: `table`.

`--force, -f` - Skip the confirmation prompt.

`--dry-run` - Preview what would happen without executing.

### ​ Resolve Options

​

string

Provide a closing note for the incident. If omitted, a default resolution message is used. **Usage:** Terminal

```
npx checkly incidents resolve --message="Root cause fixed and deployed. No further action needed."
```

​

boolean

default: "true"

Notify status page subscribers about the resolution. Use `--no-notify-subscribers` to suppress notifications. **Usage:** Terminal

```
npx checkly incidents resolve --no-notify-subscribers
```

​

string

default: "table"

Set the output format. Use `json` for programmatic access or `md` for markdown. **Usage:** Terminal

```
npx checkly incidents resolve --output=json
```

### ​ Resolve Examples

Terminal

```
# Resolve an incident with default message
npx checkly incidents resolve

# Resolve with a custom closing note
npx checkly incidents resolve --message="Database connection pool issue resolved. Monitoring confirms normal operations."

# Resolve without notifying subscribers
npx checkly incidents resolve --no-notify-subscribers
```

## ​ Related Commands

- [`checkly status-pages`](https://www.checklyhq.com/docs/cli/checkly-status-pages) - List and inspect status pages

- [`checkly checks`](https://www.checklyhq.com/docs/cli/checkly-checks) - List and inspect checks

- [`checkly whoami`](https://www.checklyhq.com/docs/cli/checkly-whoami) - Display current account information

Was this page helpful?

[Suggest edits](https://github.com/checkly/docs/edit/main/cli/checkly-incidents.mdx)[Raise issue](https://github.com/checkly/docs/issues/new?title=Issue%20on%20docs&body=Path:%20/cli/checkly-incidents)

[checkly import Previous](https://www.checklyhq.com/docs/cli/checkly-import)[checkly init Next](https://www.checklyhq.com/docs/cli/checkly-init)

[x](https://x.com/checklyhq)[github](https://github.com/checkly)[linkedin](https://linkedin.com/company/checkly)

[Powered by This documentation is built and hosted on Mintlify, a developer documentation platform](https://www.mintlify.com/?utm_campaign=poweredBy&utm_medium=referral&utm_source=checkly-422f444a)
