CLI Reference

Entry point: caddy-analyze [flags] [source...] — sources resolved via Log Sources or caddy-analyzer.json. Below: every flag, its scope, and whether it touches the system.

Operational guide

For step-by-step explanations, use cases and subcommand-specific flags, see All commands.

Global flags — Scope & root

all = persistent on every subcommand. root only = only on the root command (not on tail etc.). No flag itself requires root; subcommands guard/block/unban do (see their pages).

Persistent — all subcommands

Flag	Short	Default	Scope	Description
`--from`			all	Entries after time (RFC3339 or `5m`, `1h`, `2d`)
`--to`			all	Entries before time (RFC3339)
`--status`	`-s`		all	Filter by status code(s) e.g. `-s 200,404`
`--method`	`-m`		all	Filter by HTTP method
`--path`	`-p`		all	Path glob (`/api/*` → regex)
`--host`			all	Filter by Host substring
`--ip`			all	Client IP / CIDR
`--exclude-ip`			all	Exclude IP / CIDR
`--country`			all	Keep countries (ISO or name, needs GeoIP)
`--exclude-country`			all	Drop countries (needs GeoIP)
`--asn`			all	Keep ASNs (needs GeoIP)
`--exclude-asn`			all	Drop ASNs
`--grep`			all	Regex (fallback substring) on URI/UA/IP
`--2xx / --3xx / --4xx / --5xx`		false	all	Status class shortcut
`--errors-only`	`-e`	false	all	5xx only
`--slow`			all	Slower than duration
`--max-latency`			all	Faster than duration
`--min-size / --max-size`			all	Bytes with k/mb/gb suffix
`--no-bots / --bots-only`		false	all	Bot classifier
`--level`			all	Operational level (`error,warn,info,debug`)
`--ops-only`		false	all	Non-HTTP events only
`--top`	`-t`	10	all	Top N (0 disables)
`--format`	`-f`	table	all	Root reports: `table\|json\|csv\|html`; `top`/`diff`: `table\|json\|csv`
`--output`	`-o`		all	Write to file
`--compact`	`-c`	false	all	Compact table
`--defang`		false	all	`.`→`[.]` for IOC sharing
`--trust-forwarded`		false	all	Trust X-Forwarded-For last public hop
`--max-cardinality`		100k	all	Cap per counter (0 unlimited)
`--geo-cache-ttl`		24h	all	GeoIP cache TTL
`--geo-cache-size`		50k	all	GeoIP cache size
`--ua-rotation`		10	all	UA rotation threshold
`--namespace`	`-n`		all	K8s namespace
`--geoip-db`			all	GeoIP mmdb path (auto-discovery)
`--no-auto-download`		false	all	Disable GeoIP auto-download
`--against`			all	Compare with a baseline JSON file
`--threshold`		20	all	Regression threshold percentage
`--custom-patterns`			all	Load validated custom detection JSON; repeatable
`--remote-url`			all	Elasticsearch/OpenSearch bulk or Loki endpoint
`--remote-index`		caddy-analyzer	all	Elasticsearch/OpenSearch index
`--remote-user/password/token`			all	Remote Basic or Bearer authentication
`--remote-batch-size/retries/backoff/timeout`			all	Remote delivery tuning

Root only

Flag	Short	Scope	Description
`--follow`	`-F`	root only	Follow new logs (fan-in)
`--interval`	`-i`	root only	Re-aggregate every duration (e.g. `10s`)
`--watch`	`-w`	root only	Live TUI dashboard (8 tabs)
`--detect`	`-d`	root only	26-category threat detection
`--version`	`-v`	root only	Print version and exit

Root required?

No flag requires root by itself. The subcommands guard, block, unban require sudo because they modify firewall rules — see their pages for modifies firewall vs read-only.

Subcommands

Command	Scope	Description
`tail`	read-only	Stream and colorize (local `--detect`)
`top`	read-only	Ranked inspector (10 dimensions)
`diff`	read-only	Compare two logs
`baseline`	writes file	Save versioned analysis baselines
`guard`	modifies firewall	Auto-block via iptables/nftables/Docker
`block` / `unban`	modifies firewall	Manual firewall
`blocklist`	writes cache/config	8 feeds, refresh/list/config/init
`config`	writes config	Persist default source
`export-sigma`	writes file/stdout	23 Sigma rules
`update`	replaces binary	Self-update (cosign + SHA256)
`whitelist`	writes allowlist	Never-block CIDRs

Details per subcommand: see sidebar Guard, Blocklist, Block / Unban, Top.