> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Incidents

> List, search, inspect, and triage exception, performance, and anomaly incidents from the terminal.

The CLI lets you work through incidents without opening the web UI. You can list incidents across all types or by type, narrow them by state, namespace, or action, open a single incident's details, update its state, severity, or notification frequency, and manage the notes on it.

Every `incidents` command targets one application, identified either by name and environment (`--app "MyApp" --environment production`) or by ID (`--app-id <APP_ID>`, the long hexadecimal app ID from `appsignal-cli apps list`). The `--environment` flag is only needed when several apps share a name. Add `--org` to override your default organization. See [Apps and organizations](/cli/apps) for how apps are identified.

<h2 id="list-incidents">
  List incidents
</h2>

To list recent incidents of all types for an app:

```sh Shell theme={null}
appsignal-cli incidents list --app "MyApp" --environment production --limit 5
```

By default, the list commands return the 10 most recent incidents, ordered by most recent activity.

<h3 id="list-by-type">
  List by type
</h3>

Three commands narrow the results to a single incident type:

```sh Shell theme={null}
# Exception incidents
appsignal-cli incidents list-exceptions --app "MyApp" --environment production

# Performance traces
appsignal-cli incidents list-performance --app "MyApp" --environment production

# Anomaly detection incidents
appsignal-cli incidents list-anomalies --app "MyApp" --environment production
```

<h2 id="filter-and-search">
  Filter and search
</h2>

The list commands share a set of filters:

| Flag | Description |
| - | - |
| `--state <STATE>` | Filter by state: `OPEN`, `CLOSED`, or `WIP` |
| `--order <ORDER>` | Sort by `LAST` (most recent activity, the default) or `ID` (creation order) |
| `--limit <N>` | Maximum results (default: 10) |
| `--offset <N>` | Number of results to skip, for paging |

`incidents list`, `list-exceptions`, and `list-performance` also accept:

| Flag | Description |
| - | - |
| `--namespaces <list>` | Filter by namespaces, comma-separated (e.g. `web,background`) |
| `--action <name>` | Filter by action name (e.g. `UsersController#show`) |
| `--query <text>` | Search exception incidents by name or message, or performance incidents by action name (`list-exceptions` and `list-performance` only) |

To find timeout errors:

```sh Shell theme={null}
appsignal-cli incidents list-exceptions --app "MyApp" --environment production --query "TimeoutError"
```

You can pass several filters in one command, and they all apply together to narrow the results. For example, list only the open exceptions in the `web` namespace:

```sh Shell theme={null}
appsignal-cli incidents list-exceptions --app "MyApp" --environment production \
  --state OPEN --namespaces web
```

<Note>
  The list commands return recent incidents, so older ones may not appear even when they're still open. To open a specific incident regardless of age, use `incidents show` with its number.
</Note>

<h2 id="show-an-incident">
  Show an incident
</h2>

To see the full details of a single incident, pass its number:

```sh Shell theme={null}
appsignal-cli incidents show --number 42 --app "MyApp" --environment production
```

For exception incidents, `show` also lists the error causes from the incident's trace data. Sometimes one error wraps another, such as a timeout that surfaces as a generic request error. When that happens, the underlying causes appear next to the top-level exception, so you can find the root cause without opening a trace in the web UI.

<h2 id="update-an-incident">
  Update an incident
</h2>

Update an incident's state, severity, notification frequency, assignees, or description by number:

```sh Shell theme={null}
appsignal-cli incidents update --number 42 --app "MyApp" --environment production --state CLOSED
```

| Flag | Description |
| - | - |
| `--state <STATE>` | New state: `OPEN`, `CLOSED`, or `WIP` |
| `--severity <SEV>` | New severity: `UNTRIAGED`, `CRITICAL`, `HIGH`, `LOW`, `NONE`, or `INFORMATIONAL` |
| `--notification-frequency <FREQ>` | When to notify: `ALWAYS`, `NEVER`, `FIRST_IN_DEPLOY`, `FIRST_AFTER_CLOSE`, `NTH_IN_HOUR`, or `NTH_IN_DAY` |
| `--notification-threshold <N>` | Occurrence number that sends an `NTH_IN_HOUR` or `NTH_IN_DAY` notification |
| `--assign <NAMES_OR_IDS>` | User names or IDs to add as assignees, comma-separated |
| `--assign-me` | Assign the incident to your authenticated user |
| `--unassign <NAMES_OR_IDS>` | User names or IDs to remove from assignees, comma-separated |
| `--description <text>` | New description |

To change several incidents at once, pass a comma-separated list of numbers. Bulk updates currently support `--state` only:

```sh Shell theme={null}
appsignal-cli incidents update --number 41,42,43 --app "MyApp" --environment production --state CLOSED
```

<h3 id="set-notification-frequency">
  Set notification frequency
</h3>

`--notification-frequency` controls when AppSignal notifies you about an incident's occurrences. It takes the same options as the notification setting in the AppSignal UI, described in [Notification settings](/application/notification-settings):

| Value | Setting in the UI |
| - | - |
| `ALWAYS` | Every Occurrence |
| `FIRST_IN_DEPLOY` | First in Deploy (the default for new error incidents) |
| `FIRST_AFTER_CLOSE` | First After Close |
| `NEVER` | Never Notify |
| `NTH_IN_HOUR` | Every Nth per Hour |
| `NTH_IN_DAY` | Every Nth per Day |

To be notified only when a closed incident happens again:

```sh Shell theme={null}
appsignal-cli incidents update --number 42 --app "MyApp" --environment production \
  --notification-frequency FIRST_AFTER_CLOSE
```

`NTH_IN_HOUR` and `NTH_IN_DAY` use `--notification-threshold` to set which occurrence sends the notification. Pass it together with the frequency. To be notified on every tenth occurrence each day:

```sh Shell theme={null}
appsignal-cli incidents update --number 42 --app "MyApp" --environment production \
  --notification-frequency NTH_IN_DAY --notification-threshold 10
```

<h3 id="assign-an-incident">
  Assign an incident
</h3>

To assign an incident to yourself, use `--assign-me`. It needs no user ID:

```sh Shell theme={null}
appsignal-cli incidents update --number 42 --app "MyApp" --environment production --assign-me
```

To assign other people, pass their names or user IDs to `--assign`, comma-separated. A user ID is a long hexadecimal string. Find names and IDs with [`apps resources users`](/cli/apps), which lists each user's name, ID, and email:

```sh Shell theme={null}
appsignal-cli apps resources users --app "MyApp" --environment production
```

Then pass one or more to `--assign`:

```sh Shell theme={null}
appsignal-cli incidents update --number 42 --app "MyApp" --environment production \
  --assign <NAME_OR_ID>
```

To remove assignees, pass their names or IDs to `--unassign` the same way.

<h2 id="notes">
  Notes
</h2>

Notes record what you found on an incident and stay with it, so whoever opens the incident next has the context. You can add a note, list the notes on an incident, and edit or remove the ones you wrote.

<h3 id="add-a-note">
  Add a note
</h3>

```sh Shell theme={null}
appsignal-cli incidents add-note --number 42 --app "MyApp" --environment production \
  --content "Root cause identified."
```

Note content supports Markdown, so a longer note can carry headings, lists, code, and links:

```sh Shell theme={null}
appsignal-cli incidents add-note --number 42 --app "MyApp" --environment production \
  --content $'## Investigation\n\n- Root cause: connection pool exhaustion\n- Fix: raised the pool limit in `database.yml`'
```

The `$'...'` quoting turns `\n` into a real newline in Bash and Zsh. In a shell without it, pass the content as a quoted multi-line string.

<h3 id="list-notes">
  List notes
</h3>

Editing or deleting a note needs its ID. List an incident's notes to find it, along with each note's author, source, timestamp, and whether you can edit or delete it:

```sh Shell theme={null}
appsignal-cli incidents list-notes --number 42 --app "MyApp" --environment production
```

<h3 id="update-or-delete-a-note">
  Update or delete a note
</h3>

Pass the note ID from `list-notes`. `update-note` replaces the note's content:

```sh Shell theme={null}
appsignal-cli incidents update-note --number 42 --app "MyApp" --environment production \
  --id <NOTE_ID> --content "Root cause confirmed: connection pool exhaustion."
```

`delete-note` removes it:

```sh Shell theme={null}
appsignal-cli incidents delete-note --number 42 --app "MyApp" --environment production \
  --id <NOTE_ID>
```

<Note>
  You can update and delete only the notes you wrote. `list-notes` marks them in its `CAN EDIT` and `CAN DELETE` columns.
</Note>

<h2 id="json-output">
  JSON output
</h2>

Like every command, the incidents commands accept the global `--output json` (or `--format json`) flag, which returns machine-readable output for scripts and AI agents:

```sh Shell theme={null}
appsignal-cli --output json incidents list-exceptions --app "MyApp" --environment production --state OPEN
```

To return a single incident as JSON, narrow by its number with `incidents show`:

```sh Shell theme={null}
appsignal-cli --output json incidents show --number 42 --app "MyApp" --environment production
```

<h2 id="next-steps">
  Next steps
</h2>

Incidents tell you what's failing. To see the individual traces behind one, [fetch its traces](/cli/traces) by incident number. To see the surrounding log lines, [tail or search your logs](/cli/logs) from the terminal.


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