> Section: [10. Reference](https://jaque.sh/docs/reference/cli-flags.md)
> Next: reference/event-log-schema
> Index: https://jaque.sh/llms.txt


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](https://jaque.sh/docs/deployment/topologies.md).
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,
not hand-maintained -- so a newly added flag gets env var support without
anyone remembering to wire it up.

```sh
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. |
| `-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`. |
| `-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. |

## 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. |
| `-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, same shape as `/status.json`; empty disables it. |

See [Event log schema](https://jaque.sh/docs/reference/event-log-schema.md) 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. |
| `-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. |

See [Command and query service](https://jaque.sh/docs/api/command-and-query-service.md)
for what `-api-token` protects and what it does not.

## 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|all`, events on `-target engine|all`); empty runs every sink the role allows. |

## 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. |

## 7. Cluster and roles

| Flag | Default | Env var | What it does |
|---|---|---|---|
| `-target` | `all` | `JAQUE_TARGET` | Process role: `all`, `engine`, `worker`, `ui`, `sink`, `notifier`. See [Topologies](https://jaque.sh/docs/deployment/topologies.md). |
| `-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/`. |

## 8. 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. |

## 9. Security considerations

`-listen` exposes the dashboard, the command/query API and `/metrics` on
one address; the default binds loopback only, and widening it to `0.0.0.0`
or a routable address is an operator decision, not 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 `/status.json` are never gated by `-api-token` --
see [Command and query service](https://jaque.sh/docs/api/command-and-query-service.md) and
[Status JSON](https://jaque.sh/docs/api/status-json.md). `-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` and `-telegram-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.