Skip to Content
incidents-cli

βš™οΈ Configuration

Where the config lives, its keys, how drop-ins merge, the built-in services, the kinds of page and the environment variables.

Where it lives

${XDG_CONFIG_HOME:-~/.config}/incidents/config.yml is read first, then every config.d/*.yml beside it, in lexical order, merged over it by service id. INCIDENTS_CONFIG=<file> replaces both with a single file, and fails with exit 2 if that file does not exist.

With no config file at all, the services are github, npm, cloudflare and claude, and a muted line names the config path to create.

Keys

timeout: 4000 # milliseconds per request, default 4000
view: list # the view to open on: list (default) or board
sort: status # the order to open on: status, worst first (default), or name
services:
  github: {} # take the built-in entry as it is
  aws:
    regions: [us-east-1, us-west-2] # override fields of a built-in entry
  claude:
    pinned: true # always at the top of the overview, always a card
  npm:
    enabled: false # drop one
  acme:
    name: Acme # a full entry defines a new service
    kind: statuspage
    url: https://status.acme.example
    aliases: [ac]
KeyMeaning
timeoutMilliseconds per request, default 4000
viewlist (default) or board: the view the interactive view opens on
sortstatus (default, worst first) or name
servicesA map of service id to its fields; only the services listed here are checked

For timeout, view and sort, the last file to set them wins. Any other value for view or sort is an error naming the file.

The interactive view remembers the last view you chose with v, in ${XDG_STATE_HOME:-~/.local/state}/incidents/state.json, and opens on it next time; view is the start until you have pressed v once. Delete that file to go back to view. A state file that cannot be read is ignored, and --mock never reads or writes it.

Within services, a drop-in's fields are merged over the same id's fields from earlier files, so one file can add regions to a service another file declared.

Service fields

FieldMeaning
nameDisplay name; defaults to the id
kindstatuspage, rss, slack, aws or link; required for a service not built in
urlThe status page; must be https:// for statuspage, rss and link
feedThe incident feed URL; required for rss
windowFor rss: hours a post counts as current, default 6
regionsFor aws: the regions to count; global events always count
aliasesOther words that name the service on the command line and in search
noteA line printed under the detail
timeoutMilliseconds per request for this service, overriding the global one
enabledfalse drops the service
pinnedtrue keeps the service at the top of the interactive view; p there overrides it

Kinds

KindReads
statuspageAtlassian Statuspage v2: <url>/api/v2/summary.json, history from <url>/history.rss
rssAn incident feed only; current state comes from how recent the last post is (window)
slackSlack's status API
awsAWS Health's public event list; regions narrows it, global events always count
linkNo machine-readable page: the row points at url and claims nothing

Built-in services

github, claude, openai, vercel, cloudflare, npm, docker, figma, linear, notion, gandi, todoist, bluesky, jira, confluence, bitbucket, sentry, harness, datadog, slack, aws.

Listing one with {} takes its built-in entry as it is; any fields you give override it.

Errors

list, services, watch and help are reserved words and cannot be a service id or alias. Loading fails with exit 2 and a message naming the file and the id. Any other configuration problem (an unknown kind, a missing https url, an rss service without a feed, a file that is not a YAML mapping) also exits 2 with the file named.

Environment

VariableEffect
INCIDENTS_CONFIGA single config file, replacing the default lookup
XDG_CONFIG_HOMEMoves the default config directory
XDG_STATE_HOMEMoves the file that remembers the last view
NO_COLORPlain output
CIForces the static output

Requests identify themselves as incidents-cli/<version>.