CLI flags

This is the complete flag surface of the jaque binary, one table per subsystem, transcribed from the flag definitions themselves. Every flag has exactly one default: no conditional default, no flag whose meaning changes depending on another flag. Role-specific requirements (which flags -target engine requires, which -target worker requires) are enforced separately and documented in Topologies. Every flag also works as an environment variable, by a mechanical naming rule stated in section 1.

1. Precedence and env vars

Precedence is flag > env > default. Any flag -foo-bar has an env var JAQUE_FOO_BAR: uppercase the flag name, - becomes _, prefix JAQUE_. The mapping is mechanical, derived by walking the flag set rather than hand-maintained, so a newly added flag gets env var support without anyone remembering to wire it up.

JAQUE_LISTEN=0.0.0.0:8080 jaque -config jaque.cue

2. Core

Flag	Default	Env var	What it does
`-config`	`""`	`JAQUE_CONFIG`	Path to the CUE config file.
`-realms-config`	`""`	`JAQUE_REALMS_CONFIG`	Path to the CUE realms document. Its presence selects the aggregator flavour: the process serves a pane of glass over the declared deployments and runs no checks of its own. Mutually exclusive with `-config`.
`-config-profile`	`full`	`JAQUE_CONFIG_PROFILE`	Schema profile the CUE loader validates against: `full` or `demo`.
`-listen`	`127.0.0.1:8080`	`JAQUE_LISTEN`	Address for the dashboard, the command/query API and `/metrics`; empty disables all three.
`-log-level`	`info`	`JAQUE_LOG_LEVEL`	`debug`, `info`, `warn`, `error`. `debug` logs every check result and a failing legacy plugin's stderr/exit detail.
`-log-format`	`text`	`JAQUE_LOG_FORMAT`	`text` or `json`. `text` is for a person at a terminal (coloured only when stderr is one). `json` writes one object per line with `level`, `time`, `message` and the record's own fields, for a collector or a dogfood artifact.
`-global-concurrency`	`50`	`JAQUE_GLOBAL_CONCURRENCY`	Maximum checks running at once, process-wide.
`-host-concurrency`	`4`	`JAQUE_HOST_CONCURRENCY`	Maximum checks running at once per host.

-config-profile demo narrows the schema the loader accepts: command checks, command contacts, exec and file sinks, and any non-empty commands block are all rejected, so an untrusted operator can shape hosts, checks and notifications but cannot make the process run a command or write to the filesystem. The profile applies wherever a document is loaded against the schema: at boot, on a SIGHUP reload, and through ValidateConfig/ApplyConfig on the admin API. A process started with -config-profile demo never accepts a restricted document through any of those paths. The demo profile also caps object counts (25 hosts, 10 services per host, 10 contacts, 3 sinks, 3 datasources, 5 processes) and restricts check and retry intervals to a fixed set of values, with 30s and 15s floors.

3. Event log

Flag	Default	Env var	What it does
`-eventlog`	`memory`	`JAQUE_EVENTLOG`	Transport: `memory`, `file://<path>` (embedded, durable), `nats://<host:port>` (external log server).
`-eventlog-codec`	`json`	`JAQUE_EVENTLOG_CODEC`	Wire codec (`json` is the only one shipped).
`-retain`	`false`	`JAQUE_RETAIN`	Require the event log to survive a restart; fails fast at startup if `-eventlog` doesn't guarantee persistence.
`-eventlog-retain-check-executed`	`168h` (7d)	`JAQUE_EVENTLOG_RETAIN_CHECK_EXECUTED`	Retention for `check_executed` events; `0` means unbounded.
`-eventlog-retain-state-changed`	`0`	`JAQUE_EVENTLOG_RETAIN_STATE_CHANGED`	Retention for `state_changed`; `0` (unbounded) is what Nagios-style history retention needs.
`-eventlog-retain-reachability-changed`	`0`	`JAQUE_EVENTLOG_RETAIN_REACHABILITY_CHANGED`	Retention for `reachability_changed`; `0` unbounded.
`-eventlog-retain-handler-executed`	`0`	`JAQUE_EVENTLOG_RETAIN_HANDLER_EXECUTED`	Retention for `handler_executed` events; `0` means unbounded.
`-compaction-interval`	`1h`	`JAQUE_COMPACTION_INTERVAL`	How often the embedded transport's retention pass runs.
`-events-out`	`""`	`JAQUE_EVENTS_OUT`	Path to write the event log as JSON lines; empty disables it.
`-snapshot-out`	`""`	`JAQUE_SNAPSHOT_OUT`	Path to write the final status snapshot at shutdown, one object per row; empty disables it.

See Event log schema for the wire shape -events-out writes and the archive reads back.

4. Ingest and API

Flag	Default	Env var	What it does
`-command-file`	`""`	`JAQUE_COMMAND_FILE`	Path to the Nagios-compatible FIFO for passive results; created if absent; empty disables it.
`-api-token`	`""`	`JAQUE_API_TOKEN`	Bearer token required on `CommandService`; empty means writes are open. Refused at startup when `-auth-config` is also set.
`-auth-config`	`""`	`JAQUE_AUTH_CONFIG`	Path to the CUE auth document declaring identities (name, role, credential); read once at boot, changing identities requires a restart. Requires `-session-secret`.
`-session-secret`	`""`	`JAQUE_SESSION_SECRET`	Secret signing session cookies; required when `-auth-config` is set, and changing it invalidates every existing session. With `-auth-config` set, setting `-api-token` as well is refused at startup.
`-read-only`	`false`	`JAQUE_READ_ONLY`	Serve queries and the dashboard only; refuse all command surfaces. Refused at startup together with `-api-token` (the token only authorizes commands, which `-read-only` removes) or `-command-file` (the FIFO is a write surface). `-auth-config` is unaffected: people can still sign in and browse.
`-livestatus-listen`	`""`	`JAQUE_LIVESTATUS_LISTEN`	TCP address for the Livestatus server; empty disables it.
`-livestatus-socket`	`""`	`JAQUE_LIVESTATUS_SOCKET`	UNIX socket path for the Livestatus server; empty disables it.
`-livestatus-log-cache`	`500000`	`JAQUE_LIVESTATUS_LOG_CACHE`	Entries the Livestatus log table keeps in memory; the ring is refilled from the event log at start.

See Command and query service for what -api-token protects and what it does not, and Security considerations for the identities -auth-config and -session-secret gate.

5. Perfdata and archive

Flag	Default	Env var	What it does
`-sinks`	`""`	`JAQUE_SINKS`	Comma-separated names of configured sinks this process runs, narrowed further by the role each sink's `input` belongs to (metrics on `-target sink

6. Notifications

Flag	Default	Env var	What it does
`-notify-workers`	`4`	`JAQUE_NOTIFY_WORKERS`	Delivery shards, hashed per object.
`-notify-queue`	`64`	`JAQUE_NOTIFY_QUEUE`	Bounded buffer per shard; a full shard blocks, never drops.
`-notify-delivery`	`embedded`	`JAQUE_NOTIFY_DELIVERY`	`embedded` (this process delivers) or `external` (a `-target notifier` does).
`-smtp-host`	`""`	`JAQUE_SMTP_HOST`	SMTP relay host; empty falls back to the system `mail` binary.
`-smtp-port`	`25`	`JAQUE_SMTP_PORT`	SMTP relay port.
`-smtp-user`	`""`	`JAQUE_SMTP_USER`	SMTP auth username; empty disables auth.
`-smtp-pass`	`""`	`JAQUE_SMTP_PASS`	SMTP auth password.
`-smtp-from`	`""`	`JAQUE_SMTP_FROM`	SMTP envelope-from address.
`-telegram-token`	`""`	`JAQUE_TELEGRAM_TOKEN`	Telegram bot token; empty makes every `telegram` contact fail permanently.
`-incidentio-token`	`""`	`JAQUE_INCIDENTIO_TOKEN`	incident.io API token; empty makes every `incidentio` contact fail permanently.

7. Event handlers

Flag	Default	Env var	What it does
`-eventhandler-execution`	`embedded`	`JAQUE_EVENTHANDLER_EXECUTION`	`embedded` (this process's `-target all`/`engine` runs handlers) or `external` (a `-target eventhandler` does).
`-eventhandler-workers`	`4`	`JAQUE_EVENTHANDLER_WORKERS`	Event handler execution shards, hashed per object.

8. Cluster and roles

Flag	Default	Env var	What it does
`-target`	`all`	`JAQUE_TARGET`	Process role: `all`, `engine`, `worker`, `ui`, `sink`, `notifier`, `eventhandler`. See Topologies.
`-queue`	`""`	`JAQUE_QUEUE`	Work queue (`memory` or `nats://<host:port>`); required for `-target engine`/`worker`.
`-zones`	`default`	`JAQUE_ZONES`	Comma-separated zones a worker serves (`-target worker` only).
`-coordination`	`memory`	`JAQUE_COORDINATION`	Coordination store: `memory` (single engine) or `nats://<host:port>` (shared by every engine).
`-heartbeat-ttl`	`10s`	`JAQUE_HEARTBEAT_TTL`	Membership key lifetime; each engine heartbeats at a third of it.
`-engine-id`	hostname	`JAQUE_ENGINE_ID`	This engine's identifier on the work queue (its reply subject).
`-sink-id`	hostname	`JAQUE_SINK_ID`	This `-target sink` instance's identifier on `sink/membership/`.
`-notifier-id`	hostname	`JAQUE_NOTIFIER_ID`	This `-target notifier` instance's identifier on `notifier/membership/`.
`-eventhandler-id`	hostname	`JAQUE_EVENTHANDLER_ID`	This `-target eventhandler` instance's identifier on `eventhandler/membership/`.

9. Shutdown

Flag	Default	Env var	What it does
`-ui-shutdown-timeout`	`5s`	`JAQUE_UI_SHUTDOWN_TIMEOUT`	How long to wait for the UI server to shut down gracefully once the loop stops.
`-shutdown-drain-timeout`	`10s`	`JAQUE_SHUTDOWN_DRAIN_TIMEOUT`	How long to wait for followers to catch up to the event log before closing it.

10. Security considerations

-listen exposes the dashboard, the command/query API, /metrics and /healthz on one address; the default binds loopback only, and widening it to 0.0.0.0 or a routable address is an operator decision rather than a default. -api-token gates CommandService writes with a constant-time bearer comparison; empty means every write is open to anyone who can reach -listen. QueryService reads and /healthz are never gated by -api-token; see Command and query service. -command-file accepts untrusted input from anything that can write to the FIFO's path; file permissions on that path are the only access control. -smtp-pass, -telegram-token and -incidentio-token are process secrets passed as flags or env vars, so they are visible in the process environment and, for flags, in /proc/<pid>/cmdline on a shared host. Prefer the env var form and a restricted environment over the flag form where that matters.