Command reference¶
Every command also takes the global options (-v, -q, --debug,
--color, --config, --isolated and --no-input), before or after the
command’s name. zabgrab COMMAND --help shows the same help in a terminal.
zabgrab¶
Retrieve data from Zabbix servers.
The global options (-v, -q, –debug, –color, –config, …) can be given before or after the command.
Usage
zabgrab [OPTIONS] COMMAND [ARGS]...
Options
- -V, --version¶
Show the version and exit.
- -v, --verbose¶
Show more output (repeat for even more).
- -q, --quiet¶
Show less output (repeat for less).
- --debug¶
Show debug messages and full tracebacks for errors.
- --color, --no-color¶
Force coloured output on or off. Default: on for terminals, unless $NO_COLOR is set.
- -c, --config <config>¶
Extra config file, applied on top of all others.
- --isolated¶
Ignore the system, user and project config files.
- --no-input¶
Never prompt; fail with instructions instead. Also enabled by $ZABGRAB_NO_INPUT or $CI.
Environment variables
- ZABGRAB_CONFIG
Provide a default for
-c
config¶
Show and edit the configuration.
Usage
zabgrab config [OPTIONS] COMMAND [ARGS]...
Options
- -v, --verbose¶
Show more output (repeat for even more).
- -q, --quiet¶
Show less output (repeat for less).
- --debug¶
Show debug messages and full tracebacks for errors.
- --color, --no-color¶
Force coloured output on or off. Default: on for terminals, unless $NO_COLOR is set.
- -c, --config <config>¶
Extra config file, applied on top of all others.
- --isolated¶
Ignore the system, user and project config files.
- --no-input¶
Never prompt; fail with instructions instead. Also enabled by $ZABGRAB_NO_INPUT or $CI.
Environment variables
- ZABGRAB_CONFIG
Provide a default for
-c
edit¶
Open a config file in your editor, creating it if needed.
Usage
zabgrab config edit [OPTIONS]
Options
- --target <target>¶
Which config file to edit. ‘project’ is the nearest zabgrab.toml, or a new one in the current directory.
- Default:
'user'- Options:
user | project | system
- -v, --verbose¶
Show more output (repeat for even more).
- -q, --quiet¶
Show less output (repeat for less).
- --debug¶
Show debug messages and full tracebacks for errors.
- --color, --no-color¶
Force coloured output on or off. Default: on for terminals, unless $NO_COLOR is set.
- -c, --config <config>¶
Extra config file, applied on top of all others.
- --isolated¶
Ignore the system, user and project config files.
- --no-input¶
Never prompt; fail with instructions instead. Also enabled by $ZABGRAB_NO_INPUT or $CI.
Environment variables
- ZABGRAB_CONFIG
Provide a default for
-c
paths¶
List the config files zabgrab reads, and which exist.
Usage
zabgrab config paths [OPTIONS]
Options
- -v, --verbose¶
Show more output (repeat for even more).
- -q, --quiet¶
Show less output (repeat for less).
- --debug¶
Show debug messages and full tracebacks for errors.
- --color, --no-color¶
Force coloured output on or off. Default: on for terminals, unless $NO_COLOR is set.
- -c, --config <config>¶
Extra config file, applied on top of all others.
- --isolated¶
Ignore the system, user and project config files.
- --no-input¶
Never prompt; fail with instructions instead. Also enabled by $ZABGRAB_NO_INPUT or $CI.
Environment variables
- ZABGRAB_CONFIG
Provide a default for
-c
show¶
Print the effective configuration (all files merged) as TOML.
Usage
zabgrab config show [OPTIONS]
Options
- --sources¶
Prefix each line with the file its value came from.
- -v, --verbose¶
Show more output (repeat for even more).
- -q, --quiet¶
Show less output (repeat for less).
- --debug¶
Show debug messages and full tracebacks for errors.
- --color, --no-color¶
Force coloured output on or off. Default: on for terminals, unless $NO_COLOR is set.
- -c, --config <config>¶
Extra config file, applied on top of all others.
- --isolated¶
Ignore the system, user and project config files.
- --no-input¶
Never prompt; fail with instructions instead. Also enabled by $ZABGRAB_NO_INPUT or $CI.
Environment variables
- ZABGRAB_CONFIG
Provide a default for
-c
export¶
Write the data in FILE (.mat or .h5) to a new file, as one group.
The data of every fetch group is merged (repeated points are kept once), so this flattens a file that has been updated many times, or converts it to another format.
Usage
zabgrab export [OPTIONS] FILE
Options
- -o, --output <outputs>¶
Required File to write (.mat, .h5, .tsv or .csv). Repeat to write several files, e.g. in several formats.
- --format <format_>¶
Output format (default: from the output file name).
- Options:
h5 | mat | tsv | csv
- -i, --item <items>¶
Only these items, selected as for fetch (repeat for several); e.g. ‘12345’, ‘host=myhost,name=CPU*’ or ‘key=system.cpu.load[*]’.
- -m, --match <PATTERN>¶
Only items whose whole ID, name, key or ‘host: name’ matches this pattern, in any case, with Python’s fnmatch wildcards: ‘*’ (any text), ‘?’ (any character), ‘[seq]’ and ‘[!seq]’ (repeat for several).
- --from <TIME>¶
Only data from this time, e.g. ‘now’, ‘24 hours ago’, ‘yesterday’, ‘2026-10-14 09:00’ or ‘14/10/2026’.
- --to <TIME>¶
Only data up to this time.
- --group <NAME>¶
Only these fetch groups (repeat for several; default all).
- --overwrite¶
Replace an existing output file.
- --allow-large-text¶
Don’t warn about writing lots of text to a .mat file.
- -v, --verbose¶
Show more output (repeat for even more).
- -q, --quiet¶
Show less output (repeat for less).
- --debug¶
Show debug messages and full tracebacks for errors.
- --color, --no-color¶
Force coloured output on or off. Default: on for terminals, unless $NO_COLOR is set.
- -c, --config <config>¶
Extra config file, applied on top of all others.
- --isolated¶
Ignore the system, user and project config files.
- --no-input¶
Never prompt; fail with instructions instead. Also enabled by $ZABGRAB_NO_INPUT or $CI.
Arguments
- FILE¶
Required argument
Environment variables
- ZABGRAB_CONFIG
Provide a default for
-c
fetch¶
Fetch data from Zabbix: a template’s items and/or items given with –item.
Settings come from the command line, then the template, then [defaults] in your config. Anything missing is asked for.
Usage
zabgrab fetch [OPTIONS]
Options
- -t, --template <NAME>¶
Template to fetch.
- -i, --item <items>¶
Item to fetch as well (repeat for several), e.g. ‘12345’ or ‘host=myhost,name=CPU*’.
- -s, --server <NAME|URL>¶
Server to fetch from; overrides the template’s server.
- --from <TIME>¶
Start time, e.g. ‘now’, ‘24 hours ago’, ‘yesterday’, ‘2026-10-14 09:00’ or ‘14/10/2026’.
- --to <TIME>¶
End time (as for –from).
- --resolution <resolution>¶
raw history, or Zabbix’s hourly trends (1h).
- Options:
raw | 1h
- --agg <agg>¶
Hourly trend statistic to save (repeat for several).
- Options:
min | avg | max | count
- -o, --output <PATH>¶
Save the data: to PATH, to a directory ending in ‘/’, or with no value to an automatic name. Repeat to save to several files, e.g. in several formats.
- --format <format_>¶
Output format (default: from the output file name).
- Options:
h5 | mat | tsv | csv
- --output-dir <DIR>¶
Directory for automatic names.
- --output-pattern <PATTERN>¶
Pattern for automatic names.
- --timezone <TZ>¶
‘local’ or e.g. ‘Europe/London’.
- --jobs <jobs>¶
Items to download at once.
- --max-items <max_items>¶
Ask before fetching more items than this.
- --overwrite¶
Replace an existing output file.
- --append¶
Add the data to an existing .mat/.h5 file as a new group.
- --group <NAME>¶
Name of the new group (default fetch_NNNN).
- --in-place¶
Append without the safety copy (faster for very large files).
- --allow-large-text¶
Don’t warn about writing lots of text to a .mat file.
- --plot¶
Plot the data (without saving it, unless –output is given). Needs matplotlib: pip install ‘zabgrab[plot]’.
- --log-y¶
With –plot: use log scales for the vertical axes.
- -y, --yes¶
Fetch however many items match.
- --dry-run¶
Show what would be fetched, then stop.
- --explain¶
Show the settings and where each came from, then stop.
- --save-template <NAME>¶
Save this fetch (with any answers to questions) as a template.
- --save-to <user|project|system|PATH>¶
Config file to save the template to. [default: user]
- --force¶
Replace an existing template.
- -v, --verbose¶
Show more output (repeat for even more).
- -q, --quiet¶
Show less output (repeat for less).
- --debug¶
Show debug messages and full tracebacks for errors.
- --color, --no-color¶
Force coloured output on or off. Default: on for terminals, unless $NO_COLOR is set.
- -c, --config <config>¶
Extra config file, applied on top of all others.
- --isolated¶
Ignore the system, user and project config files.
- --no-input¶
Never prompt; fail with instructions instead. Also enabled by $ZABGRAB_NO_INPUT or $CI.
Environment variables
- ZABGRAB_CONFIG
Provide a default for
-c
hosts¶
List hosts, optionally only those whose name matches PATTERN.
Patterns match the whole technical or visible name, ignoring case, as in the Zabbix API; ‘*’ matches any text, so ‘lab*’ finds hosts starting with ‘lab’.
Usage
zabgrab hosts [OPTIONS] [PATTERN]
Options
- -g, --group <group>¶
Only hosts in host groups matching this pattern.
- -s, --server <NAME|URL>¶
Server to query (repeat for several). Default: [defaults] server in your config, otherwise you’re asked.
- --limit <limit>¶
Maximum number of results per server.
- Default:
500
- -v, --verbose¶
Show more output (repeat for even more).
- -q, --quiet¶
Show less output (repeat for less).
- --debug¶
Show debug messages and full tracebacks for errors.
- --color, --no-color¶
Force coloured output on or off. Default: on for terminals, unless $NO_COLOR is set.
- -c, --config <config>¶
Extra config file, applied on top of all others.
- --isolated¶
Ignore the system, user and project config files.
- --no-input¶
Never prompt; fail with instructions instead. Also enabled by $ZABGRAB_NO_INPUT or $CI.
Arguments
- PATTERN¶
Optional argument
Environment variables
- ZABGRAB_CONFIG
Provide a default for
-c
info¶
List the items in FILE (.mat or .h5).
Shows each item’s ID, host, name, key, units, resolution, number of points and time range, merged across the file’s fetch groups. –item, –match, –from, –to and –group select as for plot and export, so this shows what they would select. With –groups, lists the fetch groups instead. With –overlaps, the groups list also counts each group’s points that another group holds too (they’re kept once when the file is read; export flattens the file to store them once).
Usage
zabgrab info [OPTIONS] FILE
Options
- -i, --item <items>¶
Only these items, selected as for fetch (repeat for several); e.g. ‘12345’, ‘host=myhost,name=CPU*’ or ‘key=system.cpu.load[*]’.
- -m, --match <PATTERN>¶
Only items whose whole ID, name, key or ‘host: name’ matches this pattern, in any case, with Python’s fnmatch wildcards: ‘*’ (any text), ‘?’ (any character), ‘[seq]’ and ‘[!seq]’ (repeat for several).
- --from <TIME>¶
Only data from this time, e.g. ‘now’, ‘24 hours ago’, ‘yesterday’, ‘2026-10-14 09:00’ or ‘14/10/2026’.
- --to <TIME>¶
Only data up to this time.
- --group <NAME>¶
Only these fetch groups (repeat for several; default all).
- --groups¶
List the fetch groups instead of the items.
- --overlaps¶
List the fetch groups with how many of each one’s points another group also holds (implies –groups).
- -v, --verbose¶
Show more output (repeat for even more).
- -q, --quiet¶
Show less output (repeat for less).
- --debug¶
Show debug messages and full tracebacks for errors.
- --color, --no-color¶
Force coloured output on or off. Default: on for terminals, unless $NO_COLOR is set.
- -c, --config <config>¶
Extra config file, applied on top of all others.
- --isolated¶
Ignore the system, user and project config files.
- --no-input¶
Never prompt; fail with instructions instead. Also enabled by $ZABGRAB_NO_INPUT or $CI.
Arguments
- FILE¶
Required argument
Environment variables
- ZABGRAB_CONFIG
Provide a default for
-c
items¶
List items, optionally only those whose name matches PATTERN.
Patterns match the whole value, ignoring case, as in the Zabbix API; ‘*’ matches any text, so ‘CPU’ finds names containing ‘CPU’. All of PATTERN, –host, –key and –tag must match; each –item adds further items.
Usage
zabgrab items [OPTIONS] [PATTERN]
Options
- -H, --host <host>¶
Only items on hosts matching this pattern.
- -k, --key <key>¶
Only items whose key matches this pattern.
- --tag <tag>¶
Only items with this tag (‘name’ or ‘name:value’).
- -i, --item <items>¶
Item spec to include (repeat for several); e.g. ‘12345’, ‘host=myhost,name=CPU*’ or ‘key=system.cpu.load[*]’.
- --sort <COLUMN>¶
Sort by this column, named as in the table header, in any case (e.g. ‘last value’): Server, Item ID, Host, Name, Key, Type, Units, Last value, Age. Ties are sorted by item ID.
- Default:
'Item ID'- Options:
Server | Item ID | Host | Name | Key | Type | Units | Last value | Age
- -s, --server <NAME|URL>¶
Server to query (repeat for several). Default: [defaults] server in your config, otherwise you’re asked.
- --limit <limit>¶
Maximum number of results per server.
- Default:
500
- -v, --verbose¶
Show more output (repeat for even more).
- -q, --quiet¶
Show less output (repeat for less).
- --debug¶
Show debug messages and full tracebacks for errors.
- --color, --no-color¶
Force coloured output on or off. Default: on for terminals, unless $NO_COLOR is set.
- -c, --config <config>¶
Extra config file, applied on top of all others.
- --isolated¶
Ignore the system, user and project config files.
- --no-input¶
Never prompt; fail with instructions instead. Also enabled by $ZABGRAB_NO_INPUT or $CI.
Arguments
- PATTERN¶
Optional argument
Environment variables
- ZABGRAB_CONFIG
Provide a default for
-c
plot¶
Plot the data in FILE (.mat or .h5).
The data of every fetch group is merged, and lines only break over times that no fetch covered. Items share an axis when they have the same units. Hourly trends are drawn as the average, with the minimum and maximum as a band. Text items can’t be plotted.
Needs matplotlib: pip install ‘zabgrab[plot]’.
Usage
zabgrab plot [OPTIONS] FILE
Options
- -i, --item <items>¶
Only these items, selected as for fetch (repeat for several); e.g. ‘12345’, ‘host=myhost,name=CPU*’ or ‘key=system.cpu.load[*]’.
- -m, --match <PATTERN>¶
Only items whose whole ID, name, key or ‘host: name’ matches this pattern, in any case, with Python’s fnmatch wildcards: ‘*’ (any text), ‘?’ (any character), ‘[seq]’ and ‘[!seq]’ (repeat for several).
- --from <TIME>¶
Only data from this time, e.g. ‘now’, ‘24 hours ago’, ‘yesterday’, ‘2026-10-14 09:00’ or ‘14/10/2026’.
- --to <TIME>¶
Only data up to this time.
- --group <NAME>¶
Only these fetch groups (repeat for several; default all).
- -o, --output <outputs>¶
Save the plot to this image file (e.g. .png, .pdf or .svg) instead of showing it. Repeat to save it to several files, e.g. in several formats.
- --log-y¶
Use log scales for the vertical axes.
- -v, --verbose¶
Show more output (repeat for even more).
- -q, --quiet¶
Show less output (repeat for less).
- --debug¶
Show debug messages and full tracebacks for errors.
- --color, --no-color¶
Force coloured output on or off. Default: on for terminals, unless $NO_COLOR is set.
- -c, --config <config>¶
Extra config file, applied on top of all others.
- --isolated¶
Ignore the system, user and project config files.
- --no-input¶
Never prompt; fail with instructions instead. Also enabled by $ZABGRAB_NO_INPUT or $CI.
Arguments
- FILE¶
Required argument
Environment variables
- ZABGRAB_CONFIG
Provide a default for
-c
token¶
Manage API tokens stored in your system keyring.
When connecting, zabgrab uses the token in a server’s token_env environment variable if set, otherwise the token stored here.
Usage
zabgrab token [OPTIONS] COMMAND [ARGS]...
Options
- -v, --verbose¶
Show more output (repeat for even more).
- -q, --quiet¶
Show less output (repeat for less).
- --debug¶
Show debug messages and full tracebacks for errors.
- --color, --no-color¶
Force coloured output on or off. Default: on for terminals, unless $NO_COLOR is set.
- -c, --config <config>¶
Extra config file, applied on top of all others.
- --isolated¶
Ignore the system, user and project config files.
- --no-input¶
Never prompt; fail with instructions instead. Also enabled by $ZABGRAB_NO_INPUT or $CI.
Environment variables
- ZABGRAB_CONFIG
Provide a default for
-c
add¶
Store an API token for a server.
The token is read from FILE (‘-’ for standard input) if given, otherwise asked for. Avoid putting tokens on the command line itself.
Usage
zabgrab token add [OPTIONS] [NAME|URL] [FILE]
Options
- --no-check¶
Store the token without checking it first.
- -v, --verbose¶
Show more output (repeat for even more).
- -q, --quiet¶
Show less output (repeat for less).
- --debug¶
Show debug messages and full tracebacks for errors.
- --color, --no-color¶
Force coloured output on or off. Default: on for terminals, unless $NO_COLOR is set.
- -c, --config <config>¶
Extra config file, applied on top of all others.
- --isolated¶
Ignore the system, user and project config files.
- --no-input¶
Never prompt; fail with instructions instead. Also enabled by $ZABGRAB_NO_INPUT or $CI.
Arguments
- [NAME|URL]¶
Optional argument
- FILE¶
Optional argument
Environment variables
- ZABGRAB_CONFIG
Provide a default for
-c
delete¶
Delete a stored token (asks which, if not given).
Usage
zabgrab token delete [OPTIONS] [NAME|URL]
Options
- -y, --yes¶
Don’t ask for confirmation.
- -v, --verbose¶
Show more output (repeat for even more).
- -q, --quiet¶
Show less output (repeat for less).
- --debug¶
Show debug messages and full tracebacks for errors.
- --color, --no-color¶
Force coloured output on or off. Default: on for terminals, unless $NO_COLOR is set.
- -c, --config <config>¶
Extra config file, applied on top of all others.
- --isolated¶
Ignore the system, user and project config files.
- --no-input¶
Never prompt; fail with instructions instead. Also enabled by $ZABGRAB_NO_INPUT or $CI.
Arguments
- [NAME|URL]¶
Optional argument
Environment variables
- ZABGRAB_CONFIG
Provide a default for
-c
list¶
List servers and their tokens (tokens themselves are never shown).
Usage
zabgrab token list [OPTIONS]
Options
- --check¶
Check each token against its server.
- -v, --verbose¶
Show more output (repeat for even more).
- -q, --quiet¶
Show less output (repeat for less).
- --debug¶
Show debug messages and full tracebacks for errors.
- --color, --no-color¶
Force coloured output on or off. Default: on for terminals, unless $NO_COLOR is set.
- -c, --config <config>¶
Extra config file, applied on top of all others.
- --isolated¶
Ignore the system, user and project config files.
- --no-input¶
Never prompt; fail with instructions instead. Also enabled by $ZABGRAB_NO_INPUT or $CI.
Environment variables
- ZABGRAB_CONFIG
Provide a default for
-c
reset¶
Delete all stored tokens, leaving nothing of zabgrab’s in your keyring.
Usage
zabgrab token reset [OPTIONS]
Options
- -y, --yes¶
Don’t ask for confirmation.
- -v, --verbose¶
Show more output (repeat for even more).
- -q, --quiet¶
Show less output (repeat for less).
- --debug¶
Show debug messages and full tracebacks for errors.
- --color, --no-color¶
Force coloured output on or off. Default: on for terminals, unless $NO_COLOR is set.
- -c, --config <config>¶
Extra config file, applied on top of all others.
- --isolated¶
Ignore the system, user and project config files.
- --no-input¶
Never prompt; fail with instructions instead. Also enabled by $ZABGRAB_NO_INPUT or $CI.
Environment variables
- ZABGRAB_CONFIG
Provide a default for
-c
update¶
Add the data since the last fetch to FILE (.mat or .h5).
The fetch is repeated from where the file’s last group ended, with the same items, server and settings, and appended as a new group.
Usage
zabgrab update [OPTIONS] FILE
Options
- --to <TIME>¶
Fetch up to this time (default now), e.g. ‘now’, ‘24 hours ago’, ‘yesterday’, ‘2026-10-14 09:00’ or ‘14/10/2026’.
- -s, --server <NAME|URL>¶
Fetch from this server instead of the one(s) used before.
- --rematch¶
Look the items up again from the original template and patterns, picking up new items, instead of reusing the item IDs fetched before.
- --dry-run¶
Show what would be fetched, then stop.
- --in-place¶
Append without the safety copy (faster for very large files).
- --allow-large-text¶
Don’t warn about writing lots of text to a .mat file.
- -v, --verbose¶
Show more output (repeat for even more).
- -q, --quiet¶
Show less output (repeat for less).
- --debug¶
Show debug messages and full tracebacks for errors.
- --color, --no-color¶
Force coloured output on or off. Default: on for terminals, unless $NO_COLOR is set.
- -c, --config <config>¶
Extra config file, applied on top of all others.
- --isolated¶
Ignore the system, user and project config files.
- --no-input¶
Never prompt; fail with instructions instead. Also enabled by $ZABGRAB_NO_INPUT or $CI.
Arguments
- FILE¶
Required argument
Environment variables
- ZABGRAB_CONFIG
Provide a default for
-c