---
name: "icli"
section: "1p"
platform: "linux"
package: "icli"
version: "0.48-1"
release: "Debian 10 (Buster)"
platforms: ["linux"]
url: "https://new.carta.tech/icli"
---

# icli(1p)

Icinga Command Line Interface

## NAME

icli - Icinga Command Line Interface

## SYNOPSIS

**icli** \[**-v**\|**-vv**\|**-vvv**\] \[**-z** *filter*\] \[**-h** *hosts*\] \[**-g** *hostgroups*\] \[**-s** *services*\] \[**-c** *config*\] \[**-C**\] \[**-f** *status-file*\] \[**-F** *rw-file*\] \[**-lh**\|**-ls**\|**-lq**\|**-ld**\] \[**-a** *action*\[**:***args*\]\] \[*host*/*service* *...*\]

## VERSION

version 0.48

## DESCRIPTION

**icli** is a command line interface to **Icinga**. By default it lists all services and their states.

Note that when supplying custom config and status file paths, **icli** also works with **Nagios**.  100% compatibility is not guaranteed, however.

**icli** only works when executed on the host running the **Icinga** daemon.  To use it on another host, shell aliases (like `"alias icli='ssh $icingahost` `icli'"`) or similar are recommended.

You can narrow down the list of services you want displayed either using **filters** (like `"icli -z!o"`), the **-h**/**-s** arguments (`"icli -h` `aneurysm -s Libraries,Websites"`) or commandline args (`"icli` `aneurysm/{Libraries,Websites}"` with shell expansion).

## OPTIONS

- **-a**\|**--action** *action*\[:*args*\]

  Run *action* on all matching hosts or services. *args* is a comma-separated list of action arguments and depends on the action in question. *action* may also be a one or two letter shortcut.

  The following actions are supported:

  - a\|acknowledge *comment*

    Acknowledge service problems with string *comment*. This creates a sticky acknwoledgment with notification and no expire time. The comment will not be persistent.

    Note: Acknowledgement of host problems is not yet supported.

  - d\|downtime *start*,*stop*,*duration*,*comment*\[,*opts*\]

    Schedule a non-triggered host or service (depending on the filter arguments) downtime.  *start* and *stop* are timestamps and must be formatted as YYYY-MM-DDTHH:MM:SS, where the "T" is literal. The timestamp is assumed to be in the same time zone as the system running icli.

    If *duration* is 0 (zero), a fixed downtime between *start* and *stop* is scheduled. Otherwise, a flexible downtime which will start between *start* and *stop* and last *duration* is scheduled. In this case, *duration* must be a real number appended with an optional unit (s for seconds, m for minutes, h for hours, d for days, w for weeks). If no unit is specified, seconds are used.

    If a host is selected and *opts* contains "children", a downtime for all of its children will be scheduled with the same parameters as the host's. Likewise, if *opts* contains "trigger\_children", a triggered downtime for all of the host's children will be scheduled.

    *comment* refers to the downtime's comment field and must not contain the "," (comma) character.

  - r\|recheck

    Schedule an immediate recheck

  - R\|force\_recheck

    Schedule a forced, immediate recheck

- **-c**\|**--config** *config*

  Read config from *file*

- **-C**\|**--no-colours**

  Disable colours in output

- **-f**\|**--status-file** *file*

  Read the status from *file*

- **-F**\|**--rw-file** *file*

  Use *file* as external commands file.

- **-g**\|**--hostgroup** *hostgroup*

  Limit selection to hosts in *hostgroup* (comma separated list)

- **-h**\|**--host** *hosts*

  Limit selection to *hosts* (comma separated list)

- **-l**\|**--list** **downtimes**\|**hosts**\|**services**\|**queue**

  List either services (the default) or hosts. Note that only the first character of the argument is checked, so `"icli` `-lh"`, `"icli -ls"` etc. are also fine.

- **-m**\|**--match** *regex*

  Limit selection to hosts/services whose plugin output matches *regex* (perl regular expression, case insensitive. see perlre).

- **-o**\|**--overview**

  Display "tactical overview"-style overview. By default (or when used with `"-ls"`) the number of all hosts and services (both total and divided by their state) is shown.

  When used with `"-lh"`, lists all hosts with the number of ok / warning / ... checks on each host.

- **-U**\|**--as-contact** *name*

  Only operate on service visible to *name*. Doesn't work for **-lh** yet, most useful for **-ls**.

  NOTE: This is meant to help find out which services a user has access to. It is NOT intended as a way to restrict access and should never be used that way.

- **-s**\|**--service** *services*

  Limit selection to *services* (comma separated lists).  Can be combined with **-h**/**-g** to further narrow down the selection, but may also be used stand-alone.

- **-v**\|**--verbose**

  Increase output verbosity.  Can be combined up to **-vvv**

- **-V**\|**--version**

  Show version information

- **-x**\|**--cut-mode** *mode*

  What to do with lines which are too long for the terminal: **n**othing, **c**ut off, line **b**reak (with proper indentation).  The default is line **b**reaks

- **-z**\|**--filter** *expression*

  Limit selection to hosts/services passing the filter.  *expression* is a comma separated list of filters, only hosts/services to which all filters apply are selected.  See also "FILTER EXPRESSIONS"

## OUTPUT

### SERVICE LISTING

This is the standard output method. It contains the following:

- •

  Service description

- •

  \-v: Service Flags (**A**cknowledged, **F**lapping, **P**assive, **!**no checks)

- •

  Service state (ok / warning / critical / unknown)

- •

  \-v: Current attempt / Max attempts

- •

  Plugin output

### HOST LISTING

Enabled with -ld

- •

  Host name

- •

  Host state (ok / down / unreachable)

- •

  \-v: Current attempt / Max attempts

- •

  Plugin output

### QUEUE LISTING

Enabled with -lq

- •

  Host name

- •

  Service name

- •

  Last check

- •

  Next check

## FILTER EXPRESSIONS

Each expression can be negated with an exclamation mark, e.g. "!A" for all non-acknowledged services.

- **A**

  Check state has been acknowledged

- **D**

  The host this service belongs to is Down or Unreachable

- **F**

  Service is flapping between states

- **N**

  Notifications for this service are disabled

- **P**

  Only passive checks are enabled.  Note that **!P** simply means that active checks are enabled, no matter the status of passive checks

- **S**

  Check state is soft.  For instance, it used to be OK and is now critical, but has not reached its maximum number and caused a notification yet.  Good to find (or ignore) service problems which might just be temporary, non-critical glitches.

- **o**

  Host/Service state is OK

- **w**

  Service state is Warning

- **c**

  Service state is Critical

- **u**

  Service state is Unknown

- **p**

  Host or service state is Pending

- **d**

  Host state is Down

- **x**

  Host state is Unreachable

## EXIT STATUS

Zero, unless errors occured.

## CONFIGURATION

None.

## DEPENDENCIES

- •

  autodie (included with perl \>= 5.10.1)

- •

  DateTime

- •

  DateTime::Format::Strptime

- •

  DateTime::TimeZone

- •

  Term::Size

## BUGS AND LIMITATIONS

It is probably not clear from the documentation when an action will operate on hosts and when on services.

Note that this software is not yet stable. Command line options may be changed / removed and thus break backwards compatibility at any time.

### REPORTING BUGS

Either via mail to \<derf@finalrewind.org\> or on \<http://github.com/derf/icinga-cli/issues\>.

## EXAMPLES

- "icli -r -s 'APT Updates'"

  Schedule a check of the "APT Updates" service on all hosts having it

- "icli -lq -h aneurysm -g chaosdorf-hosts"

  List check queue for all hosts in the hostgroup "chaosdorf-hosts", plus the host aneurysm

- "icli -z!o,!A,!S,!D"

  Show all service problems which are already hard states and have not yet been acknowledged.  Also weed out problem services on hosts which are down anyways

## AUTHOR

Copyright (C) 2010 by Daniel Friesel \<derf@finalrewind.org\>

## LICENSE

```
  0. You just DO WHAT THE FUCK YOU WANT TO.
```