CLI Reference

Global flags

These flags apply to all commands:

Flag	Default	Description
--config	consul-guardian.yaml	Path to config file
--consul-addr	http://127.0.0.1:8500	Consul HTTP address
--consul-token	(empty)	Consul ACL token
--consul-datacenter	(auto-detect)	Consul datacenter
--log-level	info	Log level: debug, info, warn, error
--log-format	text	Log format: text, json

Config file search paths (in order):

1. Path specified by --config
2. ./consul-guardian.yaml
3. /etc/consul-guardian/consul-guardian.yaml
4. $HOME/.consul-guardian/consul-guardian.yaml

---

watch

Start continuous KV-to-Git synchronization.

consul-guardian watch [flags]

Flags

Flag	Default	Description
--prefix	config/	KV prefixes to watch (comma-separated)
--git-repo	./consul-backup	Path to Git repository
--wait-time	5m	Blocking query wait time
--auto-push	false	Push commits to remote
--commit-author	consul-guardian	Git commit author name
--commit-email	guardian@consul.local	Git commit author email
--exclude-prefix	(empty)	KV prefixes to exclude (comma-separated)

Examples

# Watch multiple prefixes
consul-guardian watch --prefix "config/,env/,flags/"

# Watch with auto-push and custom author
consul-guardian watch \
  --prefix "config/" \
  --auto-push \
  --commit-author "backup-bot" \
  --commit-email "bot@example.com"

# Watch with exclusions
consul-guardian watch \
  --prefix "config/" \
  --exclude-prefix "config/temp/,config/cache/"

# JSON logs for production
consul-guardian watch --prefix "config/" --log-format json --log-level info

---

dashboard

Start the web dashboard with integrated watcher.

consul-guardian dashboard [flags]

Flags

Flag	Default	Description
--listen	:9090	HTTP listen address
--git-repo	./consul-backup	Path to Git repository
--prefix	config/	KV prefixes to watch (comma-separated)
--static-dir	(embedded)	Path to frontend build directory

Examples

# Basic dashboard
consul-guardian dashboard --prefix "config/"

# Custom port with multiple prefixes
consul-guardian dashboard \
  --listen :8080 \
  --prefix "config/,env/,feature-flags/"

# With external frontend build
consul-guardian dashboard \
  --static-dir ./frontend/dist \
  --listen :9090

---

drift

Detect configuration drift between Git and Consul.

consul-guardian drift [flags]

Exits with code 0 if no drift is detected, code 1 if drift exists. This makes it suitable for CI/CD pipelines.

Flags

Flag	Default	Description
--prefix	config/	KV prefix to check
--git-repo	./consul-backup	Path to Git repository

Examples

# Check drift for a single prefix
consul-guardian drift --prefix "config/"

# Check drift for feature flags
consul-guardian drift --prefix "feature-flags/" --git-repo ./consul-backup

# CI/CD: fail pipeline on drift
consul-guardian drift --prefix "config/" || exit 1

---

restore

Restore KV data from Git history.

consul-guardian restore [flags]

Flags

Flag	Default	Description
--prefix	config/	KV prefix to restore
--git-repo	./consul-backup	Path to Git repository
--dry-run	false	Preview changes without applying

Examples

# Preview restore plan
consul-guardian restore --prefix "config/" --dry-run

# Execute restore for a specific prefix
consul-guardian restore --prefix "config/database/"

# Restore a single key
consul-guardian restore --prefix "config/database/host"

# Full prefix restore
consul-guardian restore \
  --consul-addr http://consul:8500 \
  --consul-token my-token \
  --prefix "config/" \
  --git-repo ./consul-backup

---

snapshot save

Take a full cluster snapshot and store it.

consul-guardian snapshot save [flags]

Flags

Flag	Default	Description
--storage-type	local	Storage backend: local, s3
--storage-path	./snapshots	Local storage directory
--bucket	(empty)	S3 bucket name
--s3-prefix	(empty)	S3 key prefix
--s3-region	(empty)	AWS region
--stale	true	Allow stale reads
--retention-count	30	Keep last N snapshots

Examples

# Local snapshot
consul-guardian snapshot save --storage-path /data/snapshots

# S3 snapshot
consul-guardian snapshot save \
  --storage-type s3 \
  --bucket consul-backups \
  --s3-prefix "production/" \
  --s3-region us-east-1

# Consistent snapshot with custom retention
consul-guardian snapshot save --stale=false --retention-count 90

---

version

Print version information.

consul-guardian version

Output:

consul-guardian v0.1.0 (commit: a1b2c3d, built: 2026-04-04T12:00:00Z)

---

Environment variables

Every config value can be set via environment variables with the CONSUL_GUARDIAN_ prefix:

Variable	Equivalent
CONSUL_GUARDIAN_CONSUL_ADDRESS	--consul-addr
CONSUL_GUARDIAN_CONSUL_TOKEN	--consul-token
CONSUL_GUARDIAN_CONSUL_DATACENTER	--consul-datacenter
CONSUL_GUARDIAN_LOGGING_LEVEL	--log-level
CONSUL_GUARDIAN_LOGGING_FORMAT	--log-format
CONSUL_GUARDIAN_GIT_REPO_PATH	--git-repo
CONSUL_GUARDIAN_GIT_AUTO_PUSH	--auto-push
CONSUL_GUARDIAN_WATCH_PREFIXES	--prefix
CONSUL_GUARDIAN_WATCH_POLL_INTERVAL	--wait-time
CONSUL_GUARDIAN_DASHBOARD_LISTEN	--listen
CONSUL_GUARDIAN_SNAPSHOT_STORAGE_TYPE	--storage-type
CONSUL_GUARDIAN_SNAPSHOT_STORAGE_PATH	--storage-path
CONSUL_GUARDIAN_SNAPSHOT_STORAGE_BUCKET	--bucket
CONSUL_GUARDIAN_SNAPSHOT_RETENTION_COUNT	--retention-count

Precedence (highest to lowest):

1. Command-line flags
2. Environment variables
3. Config file
4. Defaults