Configuration and CLI reference¶

For pool owners and operators running a release build of Aqualink Automate. This is the authoritative reference for every command-line flag and config-file key. Building from source lives in INSTALL.md.

Aqualink Automate is configured entirely at startup, through command-line flags and an optional configuration file. There is no runtime settings file that the app writes back to; what you pass at launch is what it runs with.

This page documents:

• How options are provided
• Config file format and example
• The 13 option areas, one section each
• Non-obvious behaviors and gotchas
• Conflict and dependency matrix
• Worked examples

How options are provided¶

You can set every option two ways: on the command line, or as a key in a configuration file. The two are merged at startup.

Command line vs config file¶

• Command line: options use their long name with a leading -- (for example --mqtt-host 192.168.1.100). Six options also have a short form: -c -d -h -v -s -r.
• Config file: select a file with --config <path> (or -c <path>). Keys are the option long name without dashes (for example mqtt-host, not --mqtt-host). This long-name-equals-config-key equivalence holds for every option in this document.

Precedence: the command line wins¶

Command-line arguments are parsed first; the config file is read second and merged into the same option set. Merging is first-write-wins — a value already set on the command line is never overwritten by the config file. So if an option appears in both places, the command-line value is used.

Flat-INI config format¶

The config file is a flat INI file: one key = value per line, no [sections]. See Config file format and example for the exact rules.

Flag truthiness¶

Some options are flags — they take no value on the command line (for example --debug, --mqtt, --disable-https). In a config file, write them as key = <truthy-or-falsy>:

• Truthy (true, yes, on, 1, case-insensitive) enables the flag.
• Anything else (including false, no, 0, or an empty value) omits the flag entirely, leaving it at its default.

Non-flag options always take a value in the config file (mqtt-host = 192.168.1.100).

Unknown arguments vs unknown keys¶

The two input paths treat unrecognized entries differently:

• An unknown command-line argument is fatal. The app logs the unrecognized argument and exits without starting.
• An unknown config-file key only produces a warning. The app logs Config file: unrecognized option '<key>' and continues. This means a typo in a config key silently has no effect — check the log if a setting does not take.

Important: If you pass --config <path> but the file does not exist, parsing fails and the app exits. A missing --config flag is fine (the app just runs with defaults and command-line flags).

Inspecting the live option set¶

Every registered option, with its long name, short name, and description, is exposed at runtime as JSON at GET /api/diagnostics/options. Use it to confirm exactly which options a given build accepts.

Config file format and example¶

Rules, as parsed:

• One key = value pair per line. Whitespace around the key and value is trimmed.
• Blank lines are ignored.
• Lines beginning with # are comments and are ignored.
• A line with no =, or with an empty key, is skipped with a warning.
• Keys are option long names without the leading dashes. There are no sections.
• Flag keys follow the truthiness rule above.

Four ready-to-copy example files ship in the repo. Start from the one that matches your wiring, or from the complete reference if you want to see every option in one place:

A minimal physical-serial config looks like this:

# config.conf — physical RS-485 on the host
serial-port = /dev/ttyUSB0
baudrate = 9600

jandy-device-type = onetouch
jandy-device-id = 0x41

address = 0.0.0.0       # bind the web UI on all interfaces (see the security note below)
disable-https = true    # serve plain HTTP only

Run it with:

aqualink-automate --config config.conf

App options¶

General application options. Lives in the Application settings area.

--help, --version, and --version-detail print and exit immediately. They are checked before option validation, so --help still works even if the rest of the command line has a conflict (for example --debug --trace --help).

Serial and connectivity options¶

How the app reaches the RS-485 bus — a physical port or a network bridge. Lives in the Serial settings area.

Default serial port is platform-specific: /dev/ttyS0 on Linux/macOS, COM1 on Windows.

Use a physical port unless --remote-serial-port is set; any non-empty --remote-serial-port switches the app to the network transport. RFC2217 is on by default for remote ports — pass --no-rfc2217 for a plain socket, or --rawtcp for raw TCP.

Note: The physical serial line is fixed at 9600 baud, no parity, 8 data bits, 1 stop bit, no flow control (9600 8N1). --baudrate exists for completeness; standard Aqualink hardware runs at 9600.

Conflicts (each pair is mutually exclusive): --serial-port vs --remote-serial-port; --rfc2217 vs --rawtcp; --rfc2217 vs --no-rfc2217; --no-rfc2217 vs --rawtcp.

Web server and security options¶

The built-in HTTP/HTTPS server that hosts the web UI and the REST/WebSocket API. Lives in the Web settings area.

Security: --address defaults to 127.0.0.1 (loopback only) so a fresh install is not exposed to the network. Set --address 0.0.0.0 deliberately when you want LAN access.

Default paths are resolved at runtime, relative to the executable, not printed as a literal string:

• --cert, --cert-key, and --doc-root default to assets bundled next to (or near) the installed binary.
• --http-port and --https-port have no fixed boost default; the app falls back to 80 and 443 respectively when you do not set them.

API authentication is off by default (--api-auth-token unset). When you set a token, every API request and the WebSocket upgrade must carry Authorization: Bearer <token> or the server answers HTTP 401. See usage-and-api.md for how the token is sent on the wire.

--cert and --cert-key are mutually required: set both or neither.

Conflicts: --disable-http vs --http-port; --disable-https vs each of --https-port, --cert, --cert-key, --cachain-cert. Because the conflict checker ignores defaulted options, --disable-https is accepted even though --cert/--cert-key carry default values — only an explicit --cert collides with it.

Authentication and identity options¶

The opt-in identity system — subjects, entitlements, and the policy engine (see SECURITY.md for the enforcement model and auth-redesign.md for the design). Lives in the Authentication settings area. Slice 1 ships the framework only: login and user management arrive in a later slice, so the app cannot yet issue tokens itself.

An --auth-mode value other than disabled/enabled, or a --jwt-access-ttl of 0, fails validation and stops startup.

Headless first-admin bootstrap. --bootstrap-admin <username> creates the first administrator without the interactive setup screen — useful for containers and unattended installs. It only acts when --auth-mode enabled and no users exist yet; with any user already on file it is silently a no-op (so a stale flag can never mint a second admin). The password is never passed on the command line, where it would be visible in the process table. Instead it is read from the first line of the file named by --bootstrap-admin-password-file, or, if that is unset, from the AQUALINK_BOOTSTRAP_ADMIN_PASSWORD environment variable. If --bootstrap-admin is given but no password can be found from either source, no administrator is created and a startup warning is logged. The password must satisfy the same policy as everywhere else (at least 12 characters).

MQTT and Home Assistant options¶

Publishing pool state to an MQTT broker, optionally with Home Assistant auto-discovery. Lives in the MQTT settings area. This is a summary — for the full topic layout, entity types, and discovery payloads, see the MQTT and Home Assistant guide.

Security: Without --mqtt-tls, MQTT credentials (--mqtt-username / --mqtt-password) travel in cleartext. --mqtt-tls-skip-verify disables certificate validation and is not for production — it defeats the point of TLS.

When you enable --mqtt-tls and do not also set --mqtt-port explicitly, the port switches from 1883 to 8883 automatically.

Dependencies: --mqtt-client-cert and --mqtt-client-key are mutually required; --home-assistant requires --mqtt; --ha-device-id requires --home-assistant.

Alerting options¶

Fault detection and notifications. Lives in the Alerting settings area.

--alert-salt-low-ppm outside 0–6000, an --alert-webhook-url that is not an absolute http(s) URL, or --alert-comms-timeout-seconds of 0 each fail validation and stop startup.

History options¶

Time-series persistence for trends. Lives in the History settings area.

History is off until you set --history-db. With no database path, the history read API returns 503 and nothing is recorded.

Equipment options¶

Pool topology and the discovered-equipment cache. Lives in the Equipment settings area.

--pool-configuration maps to the internal body model:

Scheduling and preferences options¶

Persistence for schedules and user preferences. These are two separate areas (Scheduling and Preferences).

With no --schedules-file, the scheduler is disabled and the schedule CRUD routes return 503. With no --preferences-file, preferences stay in memory and reset on restart — the preferences API still works for the session.

Matter options¶

The Matter (smart-home) bridge sidecar. Lives in the Matter settings area.

Note: --matter is an opt-out flag, and it behaves unlike the other on/off flags. It takes a value:

• Absent, or bare --matter, leaves the bridge on (the default).
• --matter false (command line) or matter = false (config) turns it off.

The C++ app does not host the Matter stack itself; it launches a Node.js sidecar. For commissioning and the Docker host-networking requirement, see MATTER.md.

Jandy emulation options¶

Which Jandy/Zodiac devices the app emulates on the bus. Lives in the Jandy settings area.

When --jandy-device-type is not given, the app emulates OneTouch, IAQ, and SerialAdapter (OneTouch for menu scraping, IAQ for status data, SerialAdapter for commands).

Default device IDs, assigned per type when you do not give an explicit --jandy-device-id:

Both --jandy-device-type and --jandy-device-id are multi-value: list types space-separated, then list IDs in the same order. Any type without a matching ID gets its default from the table above.

Conflicts and dependencies: --jandy-device-id requires --jandy-device-type; --jandy-disable-emulation conflicts with both --jandy-device-type and --jandy-device-id.

Pentair options¶

The Pentair settings area is registered but contributes no command-line options. Pentair protocol support is auto-detected from the wire; there is nothing to configure here.

Developer and replay options¶

Diagnostics, capture recording, and deterministic replay. Lives in the Developer settings area. The full record/replay workflow is in RECORD_REPLAY.md.

There is one --loglevel-<channel> option per logging channel. The 18 channels are:

certificates  coroutines  developer   devices     equipment  exceptions
main          messages    mqtt        navigation  options     platform
profiling     protocol    scraping    serial      signals     web

Each takes a severity (case-insensitive): Trace, Debug, Info, Notify, Warning, Error, Fatal. For example --loglevel-protocol Debug.

Audit is not a log channel. The security audit trail (auth decisions, privileged actions) is a separate subsystem, not an operational log channel, so there is deliberately no --loglevel-audit. See Security → Audit trail for where audit events are routed.

Where on-demand captures are written¶

--capture-directory is the one directory the runtime recording feature is allowed to touch. The filename supplied by POST /api/diagnostics/recording is jailed into it as a bare *.cap basename — path separators, drive letters, leading separators, .., control characters, and quotes are all rejected — and GET /api/diagnostics/recording/captures/{filename} serves back out of that same jail, so neither endpoint can reach a file elsewhere on the host.

The default (captures, relative to the working directory) keeps existing installs unchanged. Point it somewhere the operator can actually reach when the app runs somewhere they cannot get a shell — this is exactly what the Home Assistant add-on does, mapping it onto its user-browsable app_config share (see Home Assistant add-on).

--record-serial is unaffected: it is an operator-supplied path on the command line, so it is used as given.

Logging sinks¶

Where operational log records are delivered is configured by the Logging options. By default (--log-sinks auto) the destination is derived from the run environment: an interactive terminal or a container gets the console; under systemd the console additionally carries sd-daemon <N> priority prefixes so journalctl -u aqualink-automate -p warning works.

Examples: --log-sinks console,native --log-syslog-facility local0 (console plus a syslog local0 operational sink); --log-file /var/log/aqualink/app.log --log-format json (console and a rotating JSON file, since auto adds the file sink when a path is given); --log-file /var/log/aqualink/app.log --log-file-format json (readable text console plus a timestamped JSON file — what the Home Assistant add-on's log_to_file option does); --log-sinks console --log-format json (JSON to the console only, ideal behind a container log driver).

Platform-native sinks. On Linux, when libsystemd.so.0 is present (it is on any systemd host), journald delivers records to the journal with structured fields (query with e.g. journalctl AA_CHANNEL=Web), and auto selects it when running under systemd. libsystemd is loaded at runtime (dlopen), so it is neither a build nor a hard runtime dependency — if it is absent, logging falls back to the console. On macOS the native sink uses the unified logging system (os_log; view with Console.app or log show). On Windows, the Event Log source is registered once, elevated, with --register-log-source (and removed with --unregister-log-source); the running service never needs elevation because the sink itself does not write the registry. --install-service performs this registration too, so a service install is clean in one step. The executable embeds a message-table resource matching the sink's event IDs, so once the source is registered Event Viewer renders each entry verbatim; until that one-time registration, events still appear in the Application log, just wrapped in a generic description.

Running as a Windows service¶

On Windows the application can run as a managed service (the analogue of the Linux systemd unit): auto-start at boot, survives logoff, restarts on failure, and logs to the Windows Event Log. Install it from an elevated prompt:

aqualink-automate.exe --install-service --config "C:\ProgramData\Aqualink Automate\aqualink-automate.conf"

--install-service registers an auto-starting (delayed) service running as the built-in least-privilege NT AUTHORITY\LocalService account, sets restart-on-failure recovery, and registers the Event Log source. Any flags you pass alongside --install-service (--config, ports, --mqtt-*, …) are baked into the service command line, mirroring the systemd unit's ExecStart — so that is where the service reads its configuration from. If you omit --config, it defaults to %ProgramData%\Aqualink Automate\aqualink-automate.conf, creating that folder and a starter file. Use absolute paths: a service's working directory is System32.

Manage it with the standard tools — sc start Aqualink-Automate / Start-Service Aqualink-Automate, Stop-Service, Get-Service, sc qc Aqualink-Automate (shows the baked-in command line) — and remove it with an elevated aqualink-automate.exe --uninstall-service (which also removes the Event Log source). Run from a normal console (no --install-service) the application behaves exactly as before — a foreground process that shuts down cleanly on Ctrl-C.

Important — the big replay gotcha: --replay-filename has hard dependencies. A bare --dev-mode --replay-filename file.cap fails validation. --replay-filename requires all of:

• --dev-mode
• --profiler <tool>
• every --loglevel-<channel> option (all 18 must be present)

It also conflicts with --record-serial. A complete, validation-passing replay invocation is in the Worked examples.

Non-obvious behaviors and gotchas¶

• The command line wins over the config file. Merging is first-write-wins, and the command line is parsed first. A flag on the command line cannot be overridden by the config file.
• A missing --config file is fatal; a missing --config flag is fine. If you point --config at a path that does not exist, the app exits.
• Unknown config keys are silently warned, not fatal. A typo'd key has no effect and only shows up in the log. Unknown command-line arguments, by contrast, stop startup.
• The real default is the settings-struct default, not always the boost default. Each option is only written into settings when it is present on the command line or in the config; otherwise the value initialized in the settings struct's constructor applies. For most options these match, but --serial-port is a known case: the struct initializes /dev/ttyUSB0, yet the option carries a platform default (/dev/ttyS0 / COM1) that wins because the option is always present via its default value.
• --matter is opt-out and value-bearing. Unlike the on/off flags, it takes a value; use --matter false to disable.
• Disable flags invert their setting. --disable-http and --disable-https turn the respective server off; both servers are on by default.
• Empty-string settings disable subsystems. --history-db, --schedules-file, and --equipment-cache-file each disable their feature when left empty (the default). History and scheduling routes then return 503.
• Defaulted options never trigger conflict or dependency checks. See the matrix below — a check fires only when the relevant option is explicitly set, not when it is sitting at its default.

Conflict and dependency matrix¶

Two validation rules run after parsing:

• Conflict: two options that cannot be set together. The check fires only when both are present and neither is defaulted — so two defaulted options, or one explicit plus one defaulted, never conflict.
• Dependency: option A requires option B. The check fires when A is present-and-not-defaulted while B is absent or sitting at its default.

Worked examples¶

Remote serial over RFC2217¶

Connect to an Aqualink RS controller through a serial-to-Ethernet bridge, emulating a OneTouch device, with the web UI on all interfaces over plain HTTP:

aqualink-automate \
  --remote-serial-port 192.168.1.50:8899 \
  --rfc2217 \
  --jandy-device-type onetouch --jandy-device-id 0x41 \
  --address 0.0.0.0 \
  --disable-https

The same thing as a config file:

remote-serial-port = 192.168.1.50:8899
rfc2217 = true
jandy-device-type = onetouch
jandy-device-id = 0x41
address = 0.0.0.0
disable-https = true

aqualink-automate --config config-network.conf

MQTT with Home Assistant discovery¶

Publish to a broker and advertise entities to Home Assistant:

aqualink-automate \
  --serial-port /dev/ttyUSB0 \
  --mqtt --mqtt-host 192.168.1.100 --mqtt-port 1883 \
  --mqtt-username pool --mqtt-password secret \
  --home-assistant --ha-discovery-prefix homeassistant

Security: without --mqtt-tls, those credentials cross the network in cleartext. For the full topic and entity reference, see mqtt-home-assistant.md.

Developer replay¶

--replay-filename requires --dev-mode, --profiler, and every --loglevel-<channel>. This invocation passes validation (it mirrors the one the UI end-to-end tests boot with):

aqualink-automate \
  --dev-mode \
  --replay-filename test/fixtures/sample_session.cap \
  --profiler tracy \
  --http-port 18080 --address 127.0.0.1 --disable-https \
  --doc-root assets/web \
  --jandy-disable-emulation \
  --loglevel-certificates info --loglevel-coroutines info \
  --loglevel-developer info --loglevel-devices info \
  --loglevel-equipment info --loglevel-exceptions info \
  --loglevel-main info --loglevel-messages info \
  --loglevel-mqtt info --loglevel-navigation info \
  --loglevel-options info --loglevel-platform info \
  --loglevel-profiling info --loglevel-protocol info \
  --loglevel-scraping info --loglevel-serial info \
  --loglevel-signals info --loglevel-web info

Dropping any one --loglevel-<channel>, --profiler, or --dev-mode makes the command fail validation at startup. See RECORD_REPLAY.md for recording fixtures and the replay workflow.