- Rust 99.8%
- Dockerfile 0.1%
|
All checks were successful
Build and Push / build (push) Successful in 3m20s
|
||
|---|---|---|
| .gitea/workflows | ||
| completions | ||
| crates/column_aliases | ||
| doc | ||
| src | ||
| tests | ||
| .dockerignore | ||
| .gitignore | ||
| AGENTS.md | ||
| Cargo.lock | ||
| Cargo.toml | ||
| Dockerfile | ||
| HISTORY.md | ||
| ICINGA-API-SCHEMA.md | ||
| LICENSE | ||
| modulefile | ||
| README.md | ||
IcingaQuery
icq is a CLI client for the Icinga 2 REST API (with an optional Icinga Web 2 / IcingaDB backend). It queries and manages hosts, services, check commands, groups, users, zones, and more, and renders results as a table, CSV, TSV, JSON, or markdown. It also streams live events (events watch / events live) and ships an interactive TUI (icq tui).
Installation
cargo install icq
The TUI is built by default. Build a CLI-only binary with cargo install icq --no-default-features.
Quick Start
Configure the API connection
Write your Icinga 2 API credentials to the config file (icq config icinga prompts for the password on stdin):
icq config icinga \
--icinga-api-base-url https://icinga.example.com:5665/ \
--icinga-api-username icingaadmin \
--icinga-api-password-prompt
For the Icinga Web 2 / IcingaDB backend (disabled by default — see Configuration):
icq config icinga-web \
--icingaweb-api-base-url https://icingaweb.example.com/ \
--icingaweb-api-username admin \
--icingaweb-api-password-prompt \
--icingaweb-api-persist-cookie
Or pass credentials directly on the command line instead of using the config file:
icq --icinga-api-base-url https://icinga.example.com:5665/ \
--icinga-api-username icingaadmin \
--icinga-api-password-prompt \
list service
First query
icq is verb-first: the verb comes first, then the object type.
icq list service
Status: {Z,C,I,-}{P,A,D,-}{H,S}{F,f,-}suffix — Z=paused C=force_check I=in_progress P=problem A=acknowledged D=downtime H=hard S=soft F=flapping f=flapping_enabled a=active p=passive n=notifications v=volatile c=past_due
Host Service State Status LastChange CheckAge Output
e.gt0.ca chrony_sync ✓ OK --H-apn 2026-08-04 ✓ 00:12 chrony OK: System Time 0.000083s fast of NTP time, Stratum 3
e.gt0.ca disk_home (/home) ✓ OK --H-apn 2026-07-14 ✓ 00:07 DISK OK - free space: /home 44772MiB (99% inode=99%);
e.gt0.ca disk_root (/) ! WARNING -PH-apn 2026-09-09 ✓ 00:47 DISK WARNING - free space: / 44773MiB (19% inode=91%);
e.gt0.ca load ✓ OK --H-apn 2026-08-04 ✓ 00:56 LOAD OK - total load average: 1.20, 1.05, 1.22
The columns shown above are the built-in Default preset. Change them with --preset, --full, --short, or --format (Column Control). The legend line above the table decodes the Status flags (Status Column); suppress it with --no-legend.
The Verb-First Command Model
Every action is a verb applied to an object type. The verbs are:
| Verb | Alias | Purpose |
|---|---|---|
list |
ls |
Query and display a set of objects |
show |
get |
Show every attribute of one object |
update |
put |
Run an action: acknowledge, comment, downtime, notify |
force |
— | Force an immediate check |
reschedule |
— | Reschedule a check (optionally forced) |
Plus utility commands: status, dump, events, tui, config, completion.
Object types
The type argument is one of these (lowercase; matching is case-insensitive and aliases are accepted — node for host, svc for service, and the plurals):
| Type | Alias(es) | List | Show | Update | TUI |
|---|---|---|---|---|---|
host |
node, hosts |
✓ | ✓ | ✓ | ✓ |
service |
svc, services |
✓ | ✓ | ✓ | ✓ (default) |
check |
checks |
✓ | ✓ | ||
host-group |
host-groups |
✓ | ✓ | ✓ | |
service-group |
service-groups |
✓ | ✓ | ✓ | |
zone |
zones |
✓ | ✓ | ✓ | |
endpoint |
endpoints |
✓ | ✓ | ✓ | |
time-period |
time-periods |
✓ | ✓ | ||
user |
users |
✓ | ✓ | ✓ | |
user-group |
user-groups |
✓ | ✓ | ✓ | |
dependency |
dependencies |
✓ | ✓ | ✓ | |
notification-command |
notification-commands |
✓ | ✓ | ||
event-command |
event-commands |
✓ | ✓ | ||
api-user |
api-users |
✓ | ✓ | ||
api-listener |
— | ✓ | |||
downtime |
downtimes |
✓ | |||
comment |
comments |
✓ | |||
notification |
notifications |
✓ | |||
event |
events |
✓ | |||
tactical |
— | ✓ | |||
health |
— | ✓ | |||
history |
— | ✓ |
list works for the 15 Icinga-API-backed types except api-listener (a singleton, so it is show-only). show works for all 15. update, force, and reschedule work for host and service only. The TUI-only views (downtime, comment, notification, event, tactical, health, history) have no list/show/update form.
Querying
List
icq list <type> [selector]... [options]
All services (default columns and sort from the active preset):
icq list service
Problem services (any warning / critical / unknown):
icq list service state=problem
Switch column presets — --full (every column), --short (a reduced set), or a named preset:
icq list service --full
icq list service --short
icq list service --preset Problems # a custom preset defined in the config file
Services on a host and matching a name pattern (client-side regex):
icq list service host=monitor01
icq list service name=~"disk.*"
Sort — one or more comma-separated columns; a - suffix is descending, + (or none) is ascending:
icq list service --sort state-,hostname+
Choose which columns to show with --format (a column name plus key=value options like width):
icq list service --format "Host,width=15,Service,width=20,State,Output"
Switch column presets — --full (every column), --short (a reduced set), or a named preset:
icq list service --full
icq list service --short
icq list service --preset Problems # a custom preset defined in the config file
Hosts, check commands, and the rest
The same verb-and-selectors form works for every listable type:
icq list host
icq list host state=down
icq list host command=hostalive
icq list check
icq list check name=~"disk.*"
icq list zone
icq list user email=~"ops.*"
Show — single-object detail
show prints every attribute of one object as a two-column table (or JSON with --output json). The identifier format depends on the type:
host—host=x,name=x, or a bare hostname:icq show host monitor01service—host=x service=y,name=x/y, or a barex/y:icq show service monitor01/chrony_syncapi-listener— a bare name (defaults to the well-knownnagios)- everything else —
name=xor a bare name:icq show check disk,icq show zone director
icq show service e.gt0.ca/chrony_sync
Field Value
Name e.gt0.ca!chrony_sync
Acknowledgement 0
Active True
CheckAttempt 1
CheckCommand chrony_sync
CheckInterval 60
CommandEndpoint e.gt0.ca
DisplayName chrony_sync
DowntimeDepth 0
...
Selectors & Filtering
list (and force / reschedule) take positional selectors in key<op>value form. Operators are matched longest-first:
=~ Regex match name =~ "disk.*"
== Equal state == "ok"
!= Not equal state != "ok"
> Greater than checkattempt > 1
>= Greater/equal checkattempt >= 3
< Less than interval < 60
<= Less/equal checkinterval <= 60
The bare = is shorthand for ==. =~ is applied as a client-side post-filter, so the key must also resolve to a column.
Selector keys
A selector key is a column name or alias — not an Icinga API attribute name — and it must be a valid column for that type. Run icq list <type> --show-columns for the complete list. The common ones:
| Type | Common selector keys (name / alias) |
|---|---|
| service | name (ServiceName, service), host (HostName), command (Command, check), displayname (DisplayName, display), state, zone, package, group, checkattempt, checkinterval |
| host | name (HostName, host), state, command (check), displayname (display), address, zone, package, group, checkattempt, checkinterval |
| check | name, command (cmd), timeout, zone, package |
| host-group / service-group | name, displayname, groups, notes, zone, package |
| zone | name, parent, endpoints, global, package |
| endpoint | name, host, port, connected, icingservers, capabilities |
| time-period | name, displayname, ranges, includes, excludes, zone, package |
| user | name, displayname, email, groups, zone, package |
| user-group | name, displayname, groups, zone, package |
| dependency | name, displayname, childhost, childservice, parenthost, parentservice, zone, package |
| notification-command / event-command | name, command (cmd), timeout, zone, package |
| api-user | name, clientcn, permissions, zone, package |
Every column is a usable selector key, so this table is only a starting point — for example flapping=true, downtime!=0, and acknowledged=1 all work on service and host.
Useful combinations
All HTTP checks that have a problem:
icq list service command=http state=problem
Disk checks that are not reporting OK (the API doesn't parse output metrics, so grep it):
icq list service command=disk --output tsv | grep -v "DISK OK"
Flapping services on a host:
icq list service host=monitor01 flapping=true
Systemd checks, worst state first:
icq list service command=systemd --sort state-,servicelabel+
Acknowledged, or in downtime, services on a host:
icq list service host=monitor01 acknowledged=1
icq list service host=monitor01 downtime!=0
State filters
The state key accepts named values that expand to the Icinga state constants:
# Services
icq list service state=ok
icq list service state=warning
icq list service state=critical
icq list service state=unknown
icq list service state=problem # warning + critical + unknown
# Hosts
icq list host state=up
icq list host state=down
icq list host state=problem # down + unreachable
(There is no separate unreachable or pending value; both fold into problem.)
Output Formats
--output is available on list, show, status, and events.
| Format | Flag | Description |
|---|---|---|
table |
--output table (default) |
Human-readable, colorized table with a status legend |
md-table |
--output md-table |
Markdown table |
csv |
--output csv |
Comma-separated values |
tsv |
--output tsv |
Tab-separated values |
json |
--output json |
Compact JSON (one object per line for list) |
json-pretty |
--output json-pretty |
Pretty-printed JSON |
icq list service host=monitor01 --output csv
icq list service name=load host=monitor01 --output json
icq show service monitor01/chrony_sync --output json-pretty
Column Control
All of these flags are on list:
# Show the columns available for this type (name, aliases, type, description)
icq list service --show-columns
# Show the presets available for this type (name, columns, sort, selectors)
icq list service --show-presets
# Use a built-in column set
icq list service --full
icq list service --short
# Choose a named preset (built-in or from the config `presets` section)
icq list service --preset Problems
# Choose exactly which columns appear, with per-column options
icq list service --format "Host,width=15,Service,width=20,State,Output"
# Sort; - = descending, + = ascending (default)
icq list service --sort laststatechange-
icq list service --sort state-,hostname+
# Suppress the header row and/or the status legend
icq list service --no-header
icq list service --no-legend
# Cap how many lines a multi-line text cell (e.g. Output) shows before it is
# truncated. Applies to table/md-table/csv/tsv; json is never truncated.
# A positive value overrides the config; 0 uses the config value.
icq list service --output-line-limit 5
Time Display
Both list and show take TimeOptions:
# Show timestamps in local time instead of UTC
icq list service --localtime
# Show time fields relative to now, e.g. +05:30 or -1d-03:20:00
icq list service --relative-time
--localtime and --relative-time apply to list and show. The --icon-set and --color flags are global (they also affect the TUI and other display).
Local time follows the TZ environment variable (or the system timezone when TZ is unset). The CLI and the TUI resolve TZ through the same shared chrono-tz source, so they always agree on the zone and it is honored without any zone files on disk (chrono-tz ships the zone data compiled in). The prebuilt Docker image also bundles /usr/share/zoneinfo, which is only needed for the --log-file timestamps (tracing's time-based logger uses the C library's local offset).
Status Column
The Status column is a fixed-width set of single-letter flags:
Position 1: Z=paused C=force_check I=in_progress -=none
Position 2: P=problem A=acknowledged D=downtime -=none
Position 3: H=hard S=soft
Position 4: F=flapping f=flapping_enabled -=none
Suffix: a=active p=passive n=notifications v=volatile c=past_due
Examples:
--H-apn— No state severity, hard, active + passive + notifications-PH-apn— Problem, hard, active + passive + notifications-AH-apn— Acknowledged, hard, active + passive + notifications-DH-apn— In downtime, hard, active + passive + notifications
Commands
list — Query objects
icq list <type> [selector]... [options]
Options:
--preset <NAME>— use a named preset (built-inDefault/Full/Short, or a config-file preset)--output <FMT>— output format (defaulttable)--output-line-limit <N>— max lines per multi-line text cell before truncation (default1;0uses the configdefaults.output_line_limit)--full/--short— use the built-inFull/Shortcolumn sets--show-columns— print the type's columns (name, aliases, type, description) and exit--show-presets— print the presets available for this type and exit--sort <COLS>— sort columns, comma-separated, with a+/-direction suffix--format <SPEC>— choose which columns appear:"Host,width=15,Service,State,Output"--no-header/--no-legend— omit the header row / status legend
With no preset flags the built-in Default preset's columns, sort order, and selectors are used. --all drops the preset's selectors but keeps its columns and sort.
show — Single-object detail
icq show <type> <id> [--output FMT]
<id> is host=x service=y, name=x/y, a bare x/y (service), a bare name (host and the other types), or name=x. See Show — single-object detail.
update — Run an action
icq update <type> <id> set <key=value>...
<type> is host or service. The identifier is the same form as show. The literal set separates the identifier from the action keys. Exactly one action is performed per invocation; the action is chosen by the first matching key in this precedence order: remove_downtime > downtime_* > ack/unack > notify > comment. Every key must belong to the selected action (a mixed set is rejected).
| Action | Defining key(s) | Other accepted keys |
|---|---|---|
acknowledge-problem |
ack=true |
comment, author, sticky, notify, expiry |
remove-acknowledgement |
ack=false or unack |
author |
add-comment |
comment=<text> |
author, expiry |
schedule-downtime |
downtime_duration, downtime_start/downtime_end, downtime_fixed, or all_services |
comment, author |
remove-downtime |
remove_downtime |
author |
send-custom-notification |
notify=true |
comment, author, force |
Value types: booleans are true/false; expiry, downtime_duration, downtime_start, and downtime_end are Unix seconds or a duration (300, 300s, 5m, 1h). author defaults to defaults.author (or $USER@<host>). all_services is valid only for host downtime.
icq update service e.gt0.ca/disk_root set ack=true comment="maintenance" author=ops
icq update host monitor01 set ack=true sticky=true
icq update host monitor01 set downtime_duration=1h comment="upgrade"
icq update service e.gt0.ca/load set comment="flapping, investigating"
icq update host monitor01 set remove_downtime
icq update service e.gt0.ca/http_app set notify=true comment="paged on-call"
force — Force an immediate check
icq force <type> [selector]...
Runs the reschedule-check action (immediate) on every matching host or service, ignoring time-period restrictions:
icq force host monitor01
icq force service host=monitor01 command=disk
reschedule — Reschedule checks
icq reschedule <type> [selector]... [--force] [--next-check <unix-ts>]
Reschedules the next check for every matching host or service:
--force— ignore time-period restrictions and disabled checks--next-check <unix-ts>— target time (default: now)
icq reschedule host monitor01
icq reschedule service host=monitor01 --force
icq reschedule service host=monitor01 command=disk --next-check 1700000000
status — Icinga 2 status and statistics
icq status [--name <type>] [--output FMT]
Queries the status endpoint and renders the available components (IcingaApplication, ApiListener, and more) as Component / Field / Value rows. --name filters to one component (e.g. IcingaApplication).
icq status
icq status --name IcingaApplication
dump — Raw JSON from any endpoint
icq dump <endpoint> [key=value]...
<endpoint> is a path under the API (e.g. v1/objects/services, v1/status, or an IcingaDB path like icingadb/services). Query parameters are passed as unencoded key=value pairs — icq URL-encodes them for you, so do not pre-encode values. Note the API returns HTTP 404 (not an empty list) when a filter matches nothing.
icq dump v1/objects/services "filter=host.name==\"monitor01\"" limit=5
icq dump v1/status
events — Stream events
Icinga 2 API only.
events watch streams raw events, one JSON object per line:
icq events watch [--types <list>] [--filter <expr>] [--max-events <N>] [--max-time <dur>] [--output FMT]
--types— comma-separated event types to subscribe to. Default (all 15 the server emits):AcknowledgementCleared, AcknowledgementSet, CheckResult, CommentAdded, CommentRemoved, DowntimeAdded, DowntimeRemoved, DowntimeStarted, DowntimeTriggered, Flapping, Notification, ObjectCreated, ObjectDeleted, ObjectModified, StateChange.--filter— an Icinga filter expression applied to the stream.--max-events— stop after N events (0= no limit, the default).--max-time— stop after a duration: seconds (60) orminutes:seconds(1:30);0(the default) = no limit.--output—json(default),json-pretty, or a compact summary.
icq events watch
icq events watch --types CheckResult,StateChange --max-time 30
icq events watch --filter 'host.name == "monitor01"' --max-events 5
events live seeds a local cache from a full snapshot of hosts and services, then patches it in place as events arrive, printing each updated object:
icq events live [--types <list>] [--filter <expr>] [--max-events <N>] [--max-time <dur>] [--output FMT]
It subscribes to the live-cache event set by default (CheckResult, StateChange, Flapping, and the acknowledgement, downtime, and comment events). --output json (default) prints one line per updated object.
icq events live --max-time 60
tui — Interactive terminal interface
icq tui [<type> [selector]...] [--preset <name>] [--refresh-interval <S>] [--live] [--live-refresh-interval <D>] [--mouse]
The type and selectors are positional (there are no --view / --filter flags). The initial view defaults to service; any TUI view may be selected: host, host-group, service-group, zone, endpoint, user, user-group, dependency, downtime, comment, notification, event, tactical, health, history. Selectors (key<op>value) are honored only by the host/service/group/user views.
--refresh-interval <S>— seconds between refreshes (default30, ortui.refresh_interval)--preset <name>— apply a named preset to the starting view at launch (e.g.--preset Unhandledloads the Unhandled preset's columns, sort, and selectors on the defaultserviceview, or the view given as the positional type). The positional selectors still take precedence over the preset's; an unknown name warns and falls back to the view'sDefaultpreset--live— maintain a local cache patched by the event stream instead of re-querying--live-refresh-interval <D>— live cache full re-fetch interval (default15:00; e.g.900s)--mouse— enable mouse capture (scroll wheel, click-to-select); off by default (tui.mouse)--debug-snapshot-file <NAME>— override the debug-snapshot filename (written to the XDG data dir;icq_<host>_<pid>.jsonby default)--debug-snapshot-after <D>— auto-save a debug snapshot after<D>(e.g.5s) and then quit — for capturing live-mode state without interaction
icq tui
icq tui host
icq tui host state=problem
icq tui service host=monitor01
icq tui host --preset Unhandled
icq tui --live
Keyboard shortcuts
Press ? in the TUI for the full reference; the most useful bindings:
| Key | Action |
|---|---|
↑/j, ↓/k |
Move selection down / up |
PgDn/PgUp, g/G |
Page / first / last row |
←/h, →/l |
Scroll columns left / right |
Tab |
Cycle focus (menu bar / table / detail) |
Alt-<key> |
Jump to a view (hosts, services, zones, endpoints, …) |
Enter |
Actions menu (host/service views) |
d / M-Enter |
Toggle the detail pane |
m / M |
Mark / unmark the row and move down / up — bulk-target a contiguous run |
⇧↑ / ⇧↓ |
Toggle the row's mark and move down / up — same as m/M with Shift held; repeats copy the mark state |
n / N |
Next / previous problem |
/ |
Filter — edit a selector (Enter commits, Esc cancels) |
r |
Refresh |
L |
Toggle live mode (event-stream cache) |
⇧Z |
Toggle timestamps UTC / local time |
F12 / ~ |
Toggle the debug window (server, live, rendering, cache, API-call stats + save snapshot) |
F10 |
Focus the menu bar |
q / Ctrl-c |
Quit |
The detail pane, the ? keyboard-shortcuts popup, and the F12 debug window each render their logical groups as bordered cards in a responsive grid: the number of card columns grows with terminal width (1 column at narrow widths, up to 3 at wide ones), and each card's content wraps minimally to its column. In the detail pane the check-output section is always a full-width card so the whole block can be cut & pasted cleanly; each grid is one scrollable unit.
Actions in the menu carry their own hot keys (d details, f force check, a/u ack/unack, s/r downtime, c/m comment, e reschedule, n notify, p process result, g features); pressing one runs it on the marked set (or the selected row when nothing is marked).
completion — Shell completion
icq completion <shell>
Supported shells: bash, zsh, fish, elvish, powershell (csh/tcsh are not supported). See Shell Completion & Environment Modules.
config — Manage the config file
| Subcommand | Description |
|---|---|
get <path> |
Get a config value by dot-notation path (e.g. icinga_api.base_url) |
set <path> <value> |
Set a config value (auto-parsed to the field's type) |
icinga |
Write the icinga_api section to the config file |
icinga-web |
Write the icingaweb_api section to the config file |
show |
Show the fully merged effective configuration (file + environment + defaults) with passwords masked |
See Configuration for the full reference.
Configuration
icq reads its configuration from a single YAML file:
XDG_CONFIG_HOME/icq/icq.yml (default: ~/.config/icq/icq.yml)
The path can be overridden with the global --config flag (alias --config-file), which must appear before the subcommand (e.g. icq --config /path/to/icq.yml config show). The file is written with 0600 permissions when created by config icinga, config icinga-web, or config set. If it is owned by another user or has group/world permissions, icq warns at startup. The global --ignore-config-presets flag (before the subcommand) skips the config file's presets section for that invocation, falling back to the built-in Default/Full/Short presets in both the CLI list commands and the TUI; it does not affect the other config sections (defaults, tui, API settings).
Every section and every field is optional — omitted keys fall back to the built-in default. A minimal file can contain just what you need; icq config show prints the fully merged effective configuration (file + environment + defaults) with passwords masked, and its output is re-parseable YAML.
icinga_api — Icinga 2 REST API backend
The default backend (enabled by default).
| Key | Default | Description |
|---|---|---|
enabled |
true |
Enable the Icinga 2 API backend (set false to disable it, e.g. when using only IcingaWeb2) |
base_url |
http://localhost:5665/ |
Icinga 2 API base URL |
username |
— | API username (required for authentication) |
password |
— | API password (see Password Resolution) |
insecure |
false |
Ignore TLS certificate errors. Use only in trusted/isolated networks |
icingaweb_api — Icinga Web 2 (IcingaDB) backend
An alternative backend that authenticates via the Icinga Web 2 session form and queries the IcingaDB web-module endpoints. Disabled by default — it only takes effect when a command supports it (list/show/update/force/reschedule for hosts and services, and the TUI).
| Key | Default | Description |
|---|---|---|
enabled |
false |
Enable the IcingaWeb2 backend |
base_url |
http://localhost/ |
Icinga Web 2 base URL |
username |
— | Web UI username (required for authentication) |
password |
— | Web UI password (see Password Resolution) |
insecure |
false |
Ignore TLS certificate errors. Use only in trusted/isolated networks |
persist_cookie |
false |
Persist the authenticated session cookie to disk so subsequent commands skip re-login. Stored at XDG_DATA_HOME/icq/icingaweb-cookie.json (default ~/.local/share/icq/icingaweb-cookie.json) with 0600 permissions |
defaults — Display defaults
| Key | Default | Description |
|---|---|---|
author |
<username>@<hostname> |
Author name used by actions (ack, comment, downtime, …). Fallback is the $USER/$USERNAME environment variable plus the machine hostname |
output_line_limit |
1000 |
Max lines shown for multi-line text cells (e.g. output) before truncation. Used when --output-line-limit 0 is passed; a positive --output-line-limit (default 1) otherwise wins |
localtime |
true |
Format timestamps in local time instead of UTC |
relative_time |
false |
Render time fields relative to now (e.g. +02:05:00, -1d-03:20:00) |
icon_set |
utf8 |
Icon glyph set for icon columns: utf8, nerd (Nerd Fonts), or none |
color |
auto |
CLI color/styling mode: auto (style only on a TTY), true (always), or false (never). The TUI is always colored |
tui — Interactive TUI
| Key | Default | Description |
|---|---|---|
refresh_interval |
30 |
Seconds between auto-refreshes in the TUI |
mouse |
false |
Enable mouse capture in the TUI (scroll wheel, click-to-select) |
presets — Per-view column, sort, and selector presets
Each list view has a built-in Default, Full, and Short preset (columns, sort order, and optional API selectors). You can add custom presets or override built-in ones per view. Config presets are matched to built-ins case-insensitively and merge field-level: an omitted field (e.g. sort_order) inherits from the built-in preset with the same name, full is reserved and cannot be overridden, and a preset whose name doesn't match a built-in is treated as a new custom preset.
Select a preset with --preset <NAME> (or the shorthands --full / --short). Available view keys:
hosts services zones endpoints host_groups service_groups
check api_listener api_user dependency event event_command
notification_command time_period user user_group
comments downtimes notifications health history
presets:
hosts:
# Override the built-in "Default" preset: pick columns, title them, set a sort.
- name: "Default"
sort_order:
- column: HostName # sort columns (add reverse: true for descending)
columns:
- column: HostLabel # required; a column name (see --show-columns)
title: "Host" # optional display title override
- column: StateLabel
title: "State"
- column: Status
- column: LastStateChange
title: "LastChange"
- column: CheckAgeLabel
title: "CheckAge"
- column: Output
# A custom preset: same columns as Default, but pre-filtered to the
# interesting objects. Selectors are AND-ed, so this shows unhandled,
# non-paused problems. Select with `icq list host --preset Problems`.
- name: "Problems"
sort_order:
- column: HostName
columns:
- column: HostLabel
title: "Host"
- column: StateLabel
title: "State"
- column: Status
- column: LastStateChange
title: "LastChange"
- column: CheckAgeLabel
title: "CheckAge"
- column: Output
selectors: # optional API query selectors applied to list
- column: problems # a column name (same keys as the CLI), NOT an API attribute
value: true # boolean columns take a boolean value; operation defaults to ==
- column: paused
value: false
- column: handled
value: false
services:
# The service views sort by host then service; the time column is
# date-only (time_format "%F").
- name: "Default"
sort_order:
- column: HostName
- column: Service
columns:
- column: HostName
title: "Host"
- column: ServiceLabel
title: "Service"
- column: StateLabel
title: "State"
- column: Status
- column: LastStateChange
title: "LastChange"
time_format: "%F" # chrono format string for the timestamp column
- column: CheckAgeLabel
title: "CheckAge"
- column: Output
- name: "Problems"
sort_order:
- column: HostName
- column: Service
columns:
- column: HostName
title: "Host"
- column: ServiceLabel
title: "Service"
- column: StateLabel
title: "State"
- column: Status
- column: LastStateChange
title: "LastChange"
time_format: "%F"
- column: CheckAgeLabel
title: "CheckAge"
- column: Output
selectors:
- column: problems
value: true
- column: paused
value: false
- column: handled
value: false
Selector column values are column names or aliases (the same set you can use as positional CLI selectors, e.g. icq list host state=problem groups=web-servers; run --show-columns for the full list) — not Icinga API attribute names. The column is resolved to the column's underlying attribute (e.g. the Group column becomes host.groups, the State column becomes host.state) when the query is built. operation is optional and defaults to eq (==).
Selector operations: eq/== (default), ne/!=, gt/>, lt/<, gte/>=, lte/<=, match/=~ (regex). The state fields accept named values — hosts: up, down, problem; services: ok, warning, critical, unknown, problem — which expand to the Icinga state constants (e.g. state: "problem" for a host becomes (host.state == HostDown || host.state == HostUnreachable)). Boolean fields expand a bare == true/== false. match/=~ is applied as a client-side post-filter (Icinga's =~ operator is unreliable across versions), so the regex key must also resolve to a column. Multiple preset selectors are AND-ed; CLI selectors are appended after them (CLI wins for boolean fields, joins the same OR group otherwise); --all / -a drops the preset's selectors.
Note: the lowercase state key is special — for problem it expands to the full problem set (HostDown || HostUnreachable / ServiceWarning || ServiceCritical || ServiceUnknown). The State column (PascalCase) resolves problem to only its primary constant (HostDown / ServiceWarning). Use the state key to match all problem states.
Example: a full annotated config file.
icinga_api:
enabled: true
base_url: https://icinga.example.com:5665/
username: icingaadmin
password: "secret"
insecure: false
icingaweb_api:
enabled: false
base_url: https://icingaweb.example.com/
username: admin
password: "secret"
insecure: false
persist_cookie: true
defaults:
author: "ops@example.com"
output_line_limit: 5
localtime: true
relative_time: false
icon_set: utf8
color: auto
tui:
refresh_interval: 30
mouse: false
presets:
hosts:
# Same presets as shown in the presets section above (Default + Problems).
- name: "Default"
sort_order:
- column: HostName
columns:
- column: HostLabel
title: "Host"
- column: StateLabel
title: "State"
- column: Status
- column: LastStateChange
title: "LastChange"
- column: CheckAgeLabel
title: "CheckAge"
- column: Output
- name: "Problems"
sort_order:
- column: HostName
columns:
- column: HostLabel
title: "Host"
- column: StateLabel
title: "State"
- column: Status
- column: LastStateChange
title: "LastChange"
- column: CheckAgeLabel
title: "CheckAge"
- column: Output
selectors:
- column: problems
value: true
- column: paused
value: false
- column: handled
value: false
services:
- name: "Problems"
sort_order:
- column: HostName
- column: Service
columns:
- column: HostName
title: "Host"
- column: ServiceLabel
title: "Service"
- column: StateLabel
title: "State"
- column: Status
- column: LastStateChange
title: "LastChange"
time_format: "%F"
- column: CheckAgeLabel
title: "CheckAge"
- column: Output
selectors:
- column: problems
value: true
- column: paused
value: false
- column: handled
value: false
Config Commands
Manage the config file without editing it by hand:
# Write the Icinga 2 API section (prompts for password)
icq config icinga --icinga-api-base-url https://icinga.example.com:5665/ \
--icinga-api-username icingaadmin --icinga-api-password-prompt
# Write the IcingaWeb2 section (prompts for password)
icq config icinga-web --icingaweb-api-base-url https://icingaweb.example.com/ \
--icingaweb-api-username admin --icingaweb-api-password-prompt
# Show the fully merged effective configuration (passwords masked)
icq config show
# Get / set individual values by dot-notation
icq config get icingaweb_api.base_url
icq config set icingaweb_api.base_url https://new.example.com/
icq config set defaults.icon_set nerd
icq config set tui.mouse true
config icinga and config icinga-web resolve omitted values through the normal precedence (CLI flags > environment variables > existing config file > built-in defaults) before writing, so they can seed the file from flags or env. config show output is re-parseable YAML and can be reused as a new config file.
Environment Variables
Every config field has a corresponding environment variable, which takes priority over the config file and is itself overridden by explicit CLI flags.
| Variable | Description |
|---|---|
ICINGA_API_BASE_URL |
Icinga 2 API base URL |
ICINGA_API_USERNAME |
Icinga 2 API username |
ICINGA_API_PASSWORD |
Icinga 2 API password |
ICINGA_API_PASSWORD_FILE |
Path to file containing Icinga 2 API password |
ICINGA_API_INSECURE |
Ignore TLS certificate errors |
ICINGA_API_ENABLED |
Enable/disable Icinga 2 API backend |
ICINGAWEB_API_ENABLED |
Enable/disable IcingaWeb2 backend |
ICINGAWEB_API_BASE_URL |
IcingaWeb2 base URL |
ICINGAWEB_API_USERNAME |
IcingaWeb2 username |
ICINGAWEB_API_PASSWORD |
IcingaWeb2 password |
ICINGAWEB_API_PASSWORD_FILE |
Path to file containing IcingaWeb2 password |
ICINGAWEB_API_INSECURE |
Ignore TLS certificate errors |
ICINGAWEB_API_PERSIST_COOKIE |
Persist session cookie to disk |
ICQ_LOCALTIME |
Display timestamps in local time instead of UTC (defaults.localtime) |
ICQ_RELATIVE_TIME |
Display time fields relative to now (defaults.relative_time) |
ICQ_ICON_SET |
Icon glyph set: utf8, nerd, none (defaults.icon_set) |
ICQ_COLOR |
CLI color mode: auto, true, false (defaults.color) |
XDG_CONFIG_HOME |
Base directory for the config file (default ~/.config) |
XDG_DATA_HOME |
Base directory for the persisted IcingaWeb2 cookie (default ~/.local/share) |
RUST_LOG |
Override log level (e.g. debug, trace) |
ICQ_LOG_FILE |
Append log output to this file instead of stderr (see Logging) |
Precedence
Values are resolved with the following priority — first match wins:
- CLI flags (e.g.
--icinga-api-base-url,--localtime) - Environment variables (
ICINGA_API_*,ICINGAWEB_API_*,ICQ_*) - Config file (
~/.config/icq/icq.yml) - Built-in defaults
For display fields the CLI flag overrides the defaults config key; for API fields the CLI flag and env var both override the config file. Presets override the default column set, sort order, and selectors for a view; their per-column options (title, numeric clamp_min/clamp_max/printf) layer on top of the built-in column defaults.
Password Resolution
Priority order (first match wins):
--icinga-api-password/--icingaweb-api-password(CLI flag)ICINGA_API_PASSWORD/ICINGAWEB_API_PASSWORD(environment variable)- Config file
passwordfield (~/.config/icq/icq.yml) --icinga-api-password-prompt/--icingaweb-api-password-prompt(stdin prompt)--icinga-api-password-file/--icingaweb-api-password-file(file, safe for FIFOs)
The CLI flag, environment variable, and config-file value are "inline" sources that are folded together (CLI flag > env var > config file). The prompt and file are last-resort mechanisms, reached only when none of the three inline sources set a password.
Note
: Passing passwords via CLI flags (
--icinga-api-password,--icingaweb-api-password) exposes them in the process list (ps aux//proc/*/cmdline). In shared environments, prefer the prompt (*-password-prompt), password file (*-password-file), or environment variable instead.
Logging
Logging uses tracing. By default it writes to stderr (never stdout, so data streams stay clean) at icq=info and reqwest=warn.
--debug(global) — raise theicqcrate todebug(overridesRUST_LOG's level foricq).--log-file <path>(global; envICQ_LOG_FILE) — append log output to a file instead of stderr. The file is created if missing and never truncated, so repeated runs accumulate.
The RUST_LOG environment variable sets the base filter for all other targets (e.g. RUST_LOG=debug); the built-in icq/reqwest directives are layered on top and win for those targets.
API Backends
Icinga 2 API (direct)
The default backend. Connects directly to Icinga 2's REST API (:5665).
Note
: The
--insecureflag (orinsecure: truein the config) disables TLS certificate verification entirely, exposing traffic to man-in-the-middle attacks. Use it only in trusted/isolated networks or for testing.
IcingaWeb2 / IcingaDB
For IcingaDB-backed queries or IcingaWeb2 features, configure the IcingaWeb2 backend with --icingaweb-api-* flags or the icingaweb_api config section. It is disabled by default and, when enabled, applies to host/service list/show/update/force/reschedule and the TUI.
Shell Completion & Environment Modules
Tab completion is available for bash, zsh, fish, elvish, and powershell (csh/tcsh are not supported by the generator).
One-liner (add to your shell rc file)
# bash (~/.bashrc)
eval "$(icq completion bash)"
# zsh (~/.zshrc)
eval "$(icq completion zsh)"
# fish (write the completion file once)
icq completion fish > ~/.config/fish/completions/icq.fish
# elvish
icq completion elvish > ~/.config/elvish/lib/icq.elv
# powershell
icq completion powershell > icq.ps1 # then . .\icq.ps1
profile.d (system-wide, all users)
The repository ships loader scripts that regenerate the completion script from the
binary on every shell start, so they always track the installed version. Copy the
one for your shell into a profile.d-style directory:
cp /path/to/icq/completions/profile.bash /etc/profile.d/
cp /path/to/icq/completions/profile.zsh /etc/profile.d/
profile.bash sources the generated bash script; profile.zsh loads compinit
(if missing) and then sources the generated zsh script.
Environment modules (Lmod / environment-modules)
A TCL modulefile is provided at the repository root. Copy the repository (or just
the pieces below) into a directory named icq, then put that directory into a
path listed in your module path (e.g. /etc/modulefiles/icq). The directory must
hold bin/icq (the binary) and the completions/ directory:
module load icq
module load icq prepends bin/ to PATH and exports ICQ_COMPLETIONS
pointing at the completions/ directory. To enable completion, add to your
shell rc file (guarded, so it is a no-op when the module is not loaded):
# bash (~/.bashrc)
[ -n "$ICQ_COMPLETIONS" ] && source "$ICQ_COMPLETIONS/profile.bash"
# zsh (~/.zshrc)
[ -n "$ICQ_COMPLETIONS" ] && source "$ICQ_COMPLETIONS/profile.zsh"
License
See LICENSE file.