💻 CLI commands

Use the CLI when you want to run kwatch, validate a configuration, or replay a saved event. Most users can start with kwatch lint.

kwatch's binary accepts several commands and flags for runtime, validation, and diagnostics.

kwatch — run the monitor

Starts the full informer-based controller. Reads config from CONFIG_FILE environment variable (default /config/config.yaml).

kwatch

kwatch --version — print version

kwatch --version
# vX.Y.Z

kwatch lint — validate configuration

Validates your config file for common mistakes without running the monitor.

kwatch lint
# config OK

Flags

Flag	Description
--strict	Catches unknown/typo'd config fields (strict unmarshal)
--check	Validate config and verify credentials for providers that support checks

# Validate config
kwatch lint

# Strict mode — catches typos in field names
kwatch lint --strict

# Full validation + supported provider credential checks
kwatch lint --check
#   slack: OK
#   pagerduty: OK
#   email: FAIL — could not connect to SMTP server
# config OK

What lint checks

• At least one alert provider is configured
• healthCheck.port is valid when enabled
• maxRecentLogLines is non-negative
• PVC monitor thresholds are consistent (0 < threshold ≤ criticalThreshold ≤ 100)
• correlation.window and lifecycleInterval are positive
• pendingPodMonitor.threshold is positive when enabled
• workers is at least 1
• escalation.tiers are strictly ascending and positive
• resolveHoldDown ≤ correlation.window * 60
• maxBaseline doesn't exceed ConfigMap size limits
• No unknown provider names

The runtime can intentionally run in monitor-only mode with no alert providers; the lint command keeps the stricter requirement because it validates an alerting configuration.

kwatch replay — replay saved events

Reads JSONL-formatted events from stdin and sends them through the configured providers. This is useful for testing event formatting and delivery. Because the normal command sends real notifications, use --dry-run when you only want to preview the result.

kwatch replay < events.jsonl

# Preview without sending notifications
kwatch replay --dry-run < events.jsonl

Input format

# events.jsonl
{"resource":"pod","podName":"nginx-abc123","namespace":"default","reason":"OOMKilled","containerName":"nginx","logs":"...","events":"..."}
{"resource":"node","nodeName":"ip-10-0-0-1","reason":"NodeNotReady"}

Lines starting with # are ignored. Empty lines are skipped.

Output

$ kwatch replay --dry-run < events.jsonl
would replay to [slack pagerduty]: [replay] default/nginx-abc123 OOMKilled: ...
would replay to [slack pagerduty]: [replay] / NodeNotReady: ...

Safety note: kwatch replay sends real notifications unless --dry-run is set. Use lint --check to test provider connectivity without sending an event.

---

Environment variables

Variable	Default	Description
CONFIG_FILE	/config/config.yaml	Path to the YAML config file
POD_NAMESPACE	(auto-detected)	Namespace kwatch runs in (for ConfigMap state)

The config file supports ${VAR} for non-sensitive strings. Credentials must use an absolute file reference backed by a mounted Secret:

alert:
  slack:
    webhook: "${file:/config/slack-webhook}"

---

Exit codes

Code	Meaning
0	Success
1	Config error, lint failure, or runtime error

When kwatch receives SIGTERM/SIGINT, it shuts down gracefully:

1. Marks readiness false and stops accepting new work.
2. Cancels active monitoring and stops informer workers and watcher generations.
3. Stops delivery intake and drains or cancels provider workers.
4. Waits for persistence writers and performs one bounded final snapshot when leadership fencing still permits it.
5. Exits with code 0.