CLI Overview

The hiveguard CLI lets you manage every aspect of HiveGuard from your terminal — uploading data, exporting labels, managing API keys, configuring proxy rules, and more. It’s designed for automation: scripts, CI pipelines, and ML training workflows.

Installation

pip install hiveguard-cli
# or
pipx install hiveguard-cli

Authentication

The CLI uses two credential types:

Credential	Commands	How to provide
API key (X-HiveGuard-Key)	items, labels, challenge, health	HIVEGUARD_API_KEY env var or ~/.hiveguard/config.json
Dashboard token (HTTP Basic)	datasets, keys, config, proxy-rules, ml, metrics	HIVEGUARD_DASHBOARD_TOKEN env var or ~/.hiveguard/config.json

Configure both at once:

hiveguard auth configure

Config file

The CLI stores credentials in ~/.hiveguard/config.json (mode 0o600, directory mode 0o700):

{
  "base_url": "http://localhost:8000",
  "api_key": "hg_...",
  "dashboard_token": "base64(username:password)"
}

The raw API key is never passed as a CLI flag — only via env var or config file. This prevents the key from appearing in shell history or /proc.

Global options

Flag	Description
--base-url URL	Override the HiveGuard server URL
--output [table|json|jsonl|csv]	Output format (default: table)
--version	Show CLI version
--help	Show help

Command groups

Group	Description
auth	Configure credentials
health	Check server health
challenge	Generate test challenges
items	Upload and list ground-truth items
labels	List and export consensus labels
datasets	Manage datasets
keys	Manage API keys
metrics	View traffic metrics
config	Read and update runtime config
proxy-rules	Manage proxy routing rules
ml	Train and inspect the ML model

Output formats

Every list command accepts --output:

hiveguard datasets list --output json
hiveguard labels export --fmt csv --output labels.csv

table (default) uses Rich for formatted terminal output. json, jsonl, and csv are pipe-safe — no color codes, no borders.