> ## 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 or severity, and add notes.

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.

## List incidents

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.

### List by type

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 incidents
appsignal-cli incidents list-performance --app "MyApp" --environment production

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

## Filter and search

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`)           |

Exception and performance incidents support a text search over the incident name or message with `--query`:

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

## Show an incident

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

## Update an incident

Update an incident's state, severity, 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` |
| `--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
```

### Assign an incident

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.

## Add a note

To record what you found on an incident:

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

## JSON output

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

## Next steps

Incidents tell you what's failing. To see the individual samples 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.