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, 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 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 traces
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`)
`--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:

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 reads the newest error trace AppSignal kept for the incident. It adds the exception’s name and message, and the error causes in order. Causes appear when one error wraps another, such as a timeout that surfaces as a generic request error. Each cause shows the first line of your app’s code in its backtrace, when available. Without a trace, show prints the incident details alone. Loading the trace has a 10-second limit. If it fails or times out, show prints a warning on standard error and shows what it has. The command still succeeds, so check standard error when a script relies on the causes.

Update an incident

Update an incident’s state, severity, notification frequency, 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`
`--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, or repeat --number. Bulk updates currently support --state only:

Shell

appsignal-cli incidents update --number 41,42,43 --app "MyApp" --environment production --state CLOSED

Set notification frequency

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

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:

Shell

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:

Shell

appsignal-cli incidents update --number 42 --app "MyApp" --environment production \
  --notification-frequency NTH_IN_DAY --notification-threshold 10

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.

Notes

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.

Add a note

Shell

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:

Shell

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.

List notes

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:

Shell

appsignal-cli incidents list-notes --number 42 --app "MyApp" --environment production

Update or delete a note

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

Shell

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:

Shell

appsignal-cli incidents delete-note --number 42 --app "MyApp" --environment production \
  --id <NOTE_ID>

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

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

The JSON holds the incident under incident. For an exception incident with trace details, it adds two fields:

exception_error: the exception’s name and message.
error_causes: each cause’s name, message, and first_line (the first line of your app’s code in its backtrace).

A field is left out when there’s nothing to put in it.

Next steps

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

​Set notification frequency

​Assign an incident

​Notes

​Add a note

​List notes

​Update or delete a note

​JSON output

​Next steps

List incidents

List by type

Filter and search

Show an incident

Update an incident

Set notification frequency

Assign an incident

Notes

Add a note

List notes

Update or delete a note

JSON output

Next steps