amtool: Usage, Options & Common CI Errors
amtool inspects and validates Alertmanager config, alerts, and silences.
amtool is the companion CLI to Alertmanager. In CI its main use is check-config, validating alertmanager.yml before it ships; operationally it also lists alerts and manages silences.
What it does
amtool validates Alertmanager configuration, queries active alerts, and creates or expires silences against a running Alertmanager. amtool check-config is the lint command suitable for a pre-merge CI gate.
Common usage
amtool check-config alertmanager.yml
amtool config routes test --config.file=alertmanager.yml severity=critical
amtool alert query --alertmanager.url=http://am:9093
amtool silence add alertname=HighCPU --alertmanager.url=http://am:9093
amtool silence query --alertmanager.url=http://am:9093Options
| Subcommand / flag | What it does |
|---|---|
| check-config <file> | Validate one or more config files |
| config routes test | Show which route a label set matches |
| alert query | List currently firing alerts |
| silence add / query / expire | Manage silences |
| --alertmanager.url <url> | Target Alertmanager (or $ALERTMANAGER_URL) |
Common errors in CI
check-config fails with "Checking '<file>' FAILED: ..." and a non-zero exit on a bad config (e.g. an undefined receiver referenced by a route, or a malformed regex). Runtime subcommands need a reachable server: "Post \"http://.../api/v2/silences\": dial tcp ... connection refused" means --alertmanager.url is wrong or Alertmanager is down. Set --alertmanager.url or the ALERTMANAGER_URL env var; omitting both defaults to localhost:9093 and fails in most CI runners.