> 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
rather than 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. |
| `-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](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. 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](https://jaque.sh/docs/api/command-and-query-service.md)
for what `-api-token` protects and what it does not, and [Security
considerations](../deployment/security.md) 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|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. |
| `-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](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/`. |
| `-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](../api/command-and-query-service.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`, `-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.