No description
  • Rust 99.8%
  • Dockerfile 0.1%
Find a file
Andrew Phillips 4206b53750
All checks were successful
Build and Push / build (push) Successful in 3m20s
Release v0.55.2
2026-11-13 15:55:15 -04:00
.gitea/workflows ci: persist buildx builder across runs 2026-08-26 15:47:16 -03:00
completions feat: add shell completion and environment-modules support 2026-09-03 11:02:59 -03:00
crates/column_aliases feat: fully-async TUI live mode, live Downtimes/Comments, menu-bar rework 2026-08-28 22:28:11 -03:00
doc feat: shell completion, environment-modules support; fix live-mode handled semantics; drop --recurse 2026-09-04 09:20:51 -03:00
src fix: style table cell text only, not padding, so trailing whitespace trims 2026-11-13 15:53:33 -04:00
tests refactor: unify CLI and TUI on a single timezone source 2026-09-20 12:47:29 -03:00
.dockerignore Add Dockerfile and Gitea Actions workflow for OCI image builds 2026-07-14 12:17:44 -03:00
.gitignore feat: comprehensive column coverage, API refactor, and IcingaDB support 2026-07-26 12:30:38 -03:00
AGENTS.md docs: correct AGENTS.md symbol placements found on re-audit 2026-10-01 22:12:29 -03:00
Cargo.lock Release v0.55.2 2026-11-13 15:55:15 -04:00
Cargo.toml Release v0.55.2 2026-11-13 15:55:15 -04:00
Dockerfile refactor: unify CLI and TUI on a single timezone source 2026-09-20 12:47:29 -03:00
HISTORY.md Release v0.55.2 2026-11-13 15:55:15 -04:00
ICINGA-API-SCHEMA.md feat: shell completion, environment-modules support; fix live-mode handled semantics; drop --recurse 2026-09-04 09:20:51 -03:00
LICENSE license: adopt GPL-3.0 2026-07-31 12:16:59 -03:00
modulefile feat: add shell completion and environment-modules support 2026-09-03 11:02:59 -03:00
README.md feat(tui): --preset flag + unify selector struct across CLI/config/TUI 2026-10-06 15:45:12 -03:00

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 monitor01
  • service — host=x service=y, name=x/y, or a bare x/y: icq show service monitor01/chrony_sync
  • api-listener — a bare name (defaults to the well-known nagios)
  • everything else — name=x or 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-in Default/Full/Short, or a config-file preset)
  • --output <FMT> — output format (default table)
  • --output-line-limit <N> — max lines per multi-line text cell before truncation (default 1; 0 uses the config defaults.output_line_limit)
  • --full / --short — use the built-in Full / Short column 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) or minutes: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 (default 30, or tui.refresh_interval)
  • --preset <name> — apply a named preset to the starting view at launch (e.g. --preset Unhandled loads the Unhandled preset's columns, sort, and selectors on the default service view, 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's Default preset
  • --live — maintain a local cache patched by the event stream instead of re-querying
  • --live-refresh-interval <D> — live cache full re-fetch interval (default 15: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>.json by 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:

  1. CLI flags (e.g. --icinga-api-base-url, --localtime)
  2. Environment variables (ICINGA_API_*, ICINGAWEB_API_*, ICQ_*)
  3. Config file (~/.config/icq/icq.yml)
  4. 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):

  1. --icinga-api-password / --icingaweb-api-password (CLI flag)
  2. ICINGA_API_PASSWORD / ICINGAWEB_API_PASSWORD (environment variable)
  3. Config file password field (~/.config/icq/icq.yml)
  4. --icinga-api-password-prompt / --icingaweb-api-password-prompt (stdin prompt)
  5. --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 the icq crate to debug (overrides RUST_LOG's level for icq).
  • --log-file <path> (global; env ICQ_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 --insecure flag (or insecure: true in 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.