zbxctl

README

zbxctl - Open Source Zabbix 7 CLI & Automation Engine

zbxctl is an open-source CLI and automation engine for Zabbix 7.0+ LTS. Inspired by kubectl (Kubernetes CLI) and dtctl (Dynatrace CLI), its core goal is to transition developers and AI agents from heavyweight Model Context Protocol (MCP) server daemons to direct CLI execution—accelerating automation workflow development.

Website | Wiki | Contributing | Security | Code of Conduct

---

Why Shift from MCP to the CLI?

• Lower Context Overhead: MCP tool definitions and RPC envelopes bloat prompt turns. zbxctl emits token-optimized outputs (-o toon, --brief) directly over stdout, saving context tokens.
• Universal Agent & Tooling Support: Every AI coding assistant (Gemini, Claude, Cursor, Aider, custom scripts) and CI/CD runner natively supports shell execution out-of-the-box without running background MCP server daemons.
• Accelerated Automation Workflows: Fast, interactive shell feedback loops allow testing Zabbix queries, composing Unix pipes (| jq), and building scripts without writing custom Go or Python API wrappers.
• Deterministic Client Guardrails: Safety middleware (readonly, readwrite-mine) runs directly in compiled code before sending HTTP requests to Zabbix.

---

Key Features

• Tiered Command Architecture: High-frequency ergonomic verbs (get, describe, edit, apply, delete, query, exec, wait, diff, doctor, cluster-info) paired with a Tier 2 Universal Raw JSON-RPC engine (zbxctl raw).
• Client-Side Safety Middleware: Prevents accidental production outages with granular safety enforcement (readonly, readwrite-mine, readwrite-all, dangerously-unrestricted).
• Credential Redaction: Automatic redaction of sensitive API tokens, passwords, and HTTP headers in terminal/JSON output to keep credentials out of LLM contexts and logs.
• LLM Native Context Loading: Compact self-discovery tree (zbxctl commands --brief) and Token-Optimized Object Notation (-o toon) to optimize prompt token usage.
• Universal Authentication: Native support for API Tokens, Username/Password, HTTP Basic Auth, SSO custom headers (X-Remote-User), and mTLS client certificates.
• Open Source (Apache 2.0): Released under the permissive Apache License 2.0. Contributions, issue reports, and feedback are warmly welcomed!

---

1. Installation

zbxctl is distributed as a single static binary with zero external runtime dependencies. You do not need to install the Go toolchain to use it.

Precompiled Binaries (Linux, macOS, Windows)

Precompiled binaries for Linux, macOS, and Windows are published with every release on the GitHub Releases page.

Linux (x86_64 / ARM64)

# One-line auto-installer (detects latest release & architecture)
TAG=$(curl -s https://api.github.com/repos/ErKatta/zbxctl/releases/latest | grep '"tag_name":' | cut -d'"' -f4)
ARCH=$(uname -m | sed 's/x86_64/amd64/' | sed 's/aarch64/arm64/')
curl -sL "https://github.com/ErKatta/zbxctl/releases/download/${TAG}/zbxctl_${TAG#v}_linux_${ARCH}.tar.gz" | tar -xz
sudo mv zbxctl /usr/local/bin/

macOS (Apple Silicon M-Series / Intel)

# One-line auto-installer (detects latest release & architecture)
TAG=$(curl -s https://api.github.com/repos/ErKatta/zbxctl/releases/latest | grep '"tag_name":' | cut -d'"' -f4)
ARCH=$(uname -m | sed 's/x86_64/amd64/' | sed 's/arm64/arm64/')
curl -sL "https://github.com/ErKatta/zbxctl/releases/download/${TAG}/zbxctl_${TAG#v}_darwin_${ARCH}.tar.gz" | tar -xz
sudo mv zbxctl /usr/local/bin/

Windows (x86_64)

Download the latest zbxctl_*_windows_amd64.zip from GitHub Releases, extract the archive, and add zbxctl.exe to your PATH. Or install via PowerShell:

$tag = (Invoke-RestMethod -Uri "https://api.github.com/repos/ErKatta/zbxctl/releases/latest").tag_name
$ver = $tag.TrimStart('v')
Invoke-WebRequest -Uri "https://github.com/ErKatta/zbxctl/releases/download/$tag/zbxctl_${ver}_windows_amd64.zip" -OutFile "zbxctl.zip"
Expand-Archive zbxctl.zip -DestinationPath "$HOME\bin"

---

Alternative Installation Methods

Go Install (For Go Developers)

If you already have Go 1.22+ installed:

go install github.com/ErKatta/zbxctl@latest

Build From Source

git clone https://github.com/ErKatta/zbxctl.git
cd zbxctl
go build -o zbxctl main.go
sudo mv zbxctl /usr/local/bin/

---

2. Quickstart & Configuration

Initialize your configuration file (~/.zbxctl/config.yaml):

zbxctl config init

Log in and register a context:

zbxctl login https://zabbix.example.com/api_jsonrpc.php \
 --token="zabbix_api_token_here" \
 --name="prod-us" \
 --safety-level="readonly"

Verify connectivity and system diagnostics:

zbxctl doctor

Inspect current active configuration (with automatic credential redaction):

zbxctl config current-config

---

3. Supported Authentication Mechanisms

zbxctl supports all authentication models present in Zabbix 7:

active_context: prod
contexts:
 prod:
 url: "https://zabbix.company.com/api_jsonrpc.php"
 api_token: "zabbix_api_token_here"
 safety_level: "readonly"
 internal-ldap:
 url: "https://zabbix.internal/api_jsonrpc.php"
 username: "Admin"
 password: "secret_password"
 safety_level: "readwrite-mine"
 proxy-basic:
 url: "https://zabbix-proxy.net/api_jsonrpc.php"
 http_user: "proxy_user"
 http_password: "proxy_password"
 api_token: "zabbix_api_token"
 safety_level: "readwrite-all"
 sso-headers:
 url: "https://zabbix-sso.company.com/api_jsonrpc.php"
 api_token: "zabbix_api_token"
 http_headers:
 X-Remote-User: "admin@company.com"
 secure-mtls:
 url: "https://zabbix-mtls.company.com/api_jsonrpc.php"
 api_token: "zabbix_api_token"
 tls_cert_file: "/etc/ssl/client.crt"
 tls_key_file: "/etc/ssl/client.key"
 tls_ca_file: "/etc/ssl/custom_ca.crt"

---

4. Safety Middleware & Enforcement

Every API call passes through client-side safety middleware enforced by the active context's safety_level:

Safety Level	Permitted Operations	Blocked Operations
readonly	Read-only operations (*.get, describe, query, doctor, cluster-info, commands)	Any mutation (*.create, *.update, *.delete, exec)
readwrite-mine	Read-only + mutations on resources tagged zbxctl=true or managed-by=zbxctl	Un-tagged or instance-wide destructive edits
readwrite-all	Full API mutations	Destructive bulk deletes without explicit --force
dangerously-unrestricted	All operations enabled without safety checks	None

When a safety violation occurs, zbxctl emits a structured JSON error envelope on stderr with Exit Code 2:

{
  "error": {
    "code": "SAFETY_LEVEL_VIOLATION",
    "method": "host.delete",
    "message": "Operation blocked by safety-level 'readonly' on context 'prod'.",
    "resolution": "Switch context or update safety-level in ~/.zbxctl/config.yaml."
  }
}

---

5. Command Reference

Tier 1 Ergonomic Commands

# Cluster & instance sizing overview (hosts, problems, items, triggers)
zbxctl cluster-info

# Count resources directly (low-token output)
zbxctl get host --count
zbxctl get problem --count
zbxctl get item --host="Zabbix server" --count

# List hosts or filter problems
zbxctl get host
zbxctl get problem --filter='{"severity": 4}' -o json

# Fetch metric telemetry for a duration window (e.g. last 4h)
# (Note: 'metric', 'metrics', 'telemetry', and 'history' are zero-overhead aliases pointing to history.get)
zbxctl get metric 23253 --since=4h -o table
zbxctl get telemetry 23253 --since=4h -o table

# Get items belonging to a host with specific fields
zbxctl get item --host="Zabbix server" --fields=itemid,name,description

# Inspect detailed metadata for a resource (including full inventory block)
zbxctl describe host 10001
zbxctl describe inventory 10001

# Query hardware and asset CMDB inventory records
# (Aliases: 'inv', 'host-inventory', 'inventories')
zbxctl get inventory
zbxctl get inventory -f hostid,name,vendor,model,macaddress_a -o table
zbxctl get inv --search="Dell" -o json

# Advanced query search
zbxctl query item --search="key_=system.cpu" --limit=5
zbxctl query inventory --search="Linux" --sort=name

# Interactive resource editing in default text editor (kubectl edit style)
zbxctl edit host web-prod-01
zbxctl edit host/10001
zbxctl edit template 40001
zbxctl edit -f host-manifest.yaml

# Declarative creation/update from YAML/JSON manifest (or stdin)
zbxctl apply -f host-manifest.yaml
zbxctl apply -f inv-manifest.yaml

# Stream manifest directly via stdin (Unix pipe or Python subprocess)
cat inv-manifest.yaml | zbxctl apply -f -
python3 -c 'import subprocess; subprocess.run(["zbxctl", "apply", "-f", "-"], input=open("inv-manifest.yaml").read(), text=True)'

# Compare local manifest with live resource (supports -f - from stdin)
zbxctl diff -f manifest.yaml --id=10001
cat manifest.yaml | zbxctl diff -f - --id=10001

# Delete resources (requires non-readonly safety level)
zbxctl delete host 10003
zbxctl delete host 10001 10002 --force

# Execute Zabbix script on host
zbxctl exec 1 --hostid=10001

# Wait for problem resolution or metric condition
zbxctl wait problem 12345 --for=resolved --timeout=60s

Tier 2 Universal Raw Engine (100% API Coverage)

zbxctl raw proxygroup.get --params='{"output": "extend"}' -o json
zbxctl raw history.push --params='[{"itemid": 10001, "value": "42.0"}]' -o json
zbxctl raw ha.get --params='{}' -o json
### Version, Self-Update & Diagnostics
```bash
# Print client version, build commit, date, and platform
zbxctl version

# Print machine-readable JSON version metadata
zbxctl version -o json

# Print only the version string
zbxctl version --short

# Check if a newer version of zbxctl is available
zbxctl update --check

# Self-update zbxctl binary in-place to the latest GitHub release
zbxctl update

# Run connectivity and health diagnostics against target Zabbix instance
zbxctl doctor

Configuration & Context Commands

# Display active context configuration (with [REDACTED] credential masking)
zbxctl config current-config

# List all configured contexts
zbxctl config get-contexts

# Switch active context
zbxctl config use-context prod-us

# Update context safety level
zbxctl config set-safety readwrite-mine

AI Agent Skill Commands

# List available built-in skills
zbxctl skill list

# Install all built-in skills to agent configuration (~/.gemini/config/skills)
zbxctl skill install --all

# Show content of a specific skill
zbxctl skill show zabbix-automation

# Export skill to workspace repository (.agents/skills)
zbxctl skill export zabbix-troubleshooting

---

6. Output Formats

Pass -o or --output:

• json: Pretty-printed JSON object/array output.
• table: Auto-formatted terminal table with ANSI color coding for problem severities.
• toon: Token-Optimized Object Notation for LLM prompts.
• yaml: Standard YAML representation.
• auto: Automatically selects table when stdout is TTY, and json when non-TTY.

---

7. License & Commercial Usage

zbxctl is licensed under the Apache License 2.0. This allows free commercial usage, modification, distribution, and private use without copyleft restrictions, making it 100% compatible with Zabbix ecosystem tooling and commercial enterprise deployments.

---

8. Acknowledgements & Citations

zbxctl draws inspiration from the design patterns and contributions of existing open-source tools:

• dtctl (Dynatrace OSS): For introducing ergonomic CLI verbs and structured observability workflows. If referencing dtctl, please see their CITATION.cff.
• kubectl (Kubernetes Authors / CNCF): For declarative resource management (apply/diff), standard verbs, and multi-context configuration patterns.
• zabbix-cli (University of Oslo / unioslo): For providing a dedicated terminal administration tool for the Zabbix community since 2014.

Citing zbxctl

If you use zbxctl in your work, please cite it using the following citation file CITATION.cff.