Incidents - AppSignal Documentation

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 for how apps are identified.

List incidents

To list recent incidents of all types for an app:

Shell

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:

Shell

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

Shell

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:

Shell

appsignal-cli incidents list-exceptions --app "MyApp" --environment production \
  --state OPEN --namespaces web

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.

Show an incident

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

Shell

appsignal-cli incidents show --number 42 --app "MyApp" --environment production

For exception incidents, show also lists the error causes from the incident’s sample 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 sample in the web UI.

Update an incident

Update an incident’s state, severity, assignees, or description by number:

Shell

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:

Shell

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:

Shell

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, which lists each user’s name, ID, and email:

Shell

appsignal-cli apps resources users --app "MyApp" --environment production

Then pass one or more to --assign:

Shell

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:

Shell

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:

Shell

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:

Shell

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 by incident number. To see the surrounding log lines, tail or search your logs from the terminal.

​List incidents

​List by type

​Filter and search

​Show an incident

​Update an incident

​Assign an incident

​Add a note

​JSON output

​Next steps

List incidents

List by type

Filter and search

Show an incident

Update an incident

Assign an incident

Add a note

JSON output

Next steps