Take control of every Hayward OmniLogic feature, plus a local store, schedule diffs, chemistry trends, and a morning multi-site sweep no other tool offers.
Drives the same partner API the Hayward mobile app and Home Assistant integration use, but adds the historical chemistry log, the equipment diagnostic the cloud refuses to compute, the schedule-change detector for service techs, and the multi-site alarm sweep pool-service businesses ask for. Agent-native JSON throughout, with a local SQLite store that turns single-shot cloud reads into compound answers.
Authentication
OmniLogic uses a two-stage auth: a JSON login against services-gamma.haywardcloud.net returns a token + refresh token, then every operation POSTs an XML envelope to the legacy HAAPI endpoint with the token in the header. The CLI caches the token under your XDG state directory and refreshes it transparently. Set HAYWARD_USER (your account email) and HAYWARD_PW; the first call to any command logs in automatically.
Quick Start
# Verify auth + reachability + token cache before anything else.
hayward-omnilogic-pp-cli doctor
# Pull sites, equipment inventory, current telemetry, and alarms into the local store.
hayward-omnilogic-pp-cli sync --full
# One-shot pool-readiness composite — chemistry, temp, alarms, pump state with a traffic-light verdict.
hayward-omnilogic-pp-cli status --json
# Export the last week's pH/ORP/salt/temp readings for service records.
hayward-omnilogic-pp-cli chemistry log --since 7d --csv
# Enable the heater and compute when to start it so the pool reaches 84°F by 6pm.
hayward-omnilogic-pp-cli ready-by 18:00 --temp 84
Unique Features
These capabilities aren't available in any other tool for this API.
Pool readiness at a glance
-
status — One-shot "is the pool ready for guests?" view: chemistry in range, temp at setpoint, no active alarms, pump running, with a traffic-light verdict.
Reach for this when an agent or user wants a one-shot pool-state summary instead of correlating three commands.
hayward-omnilogic-pp-cli status --json
-
ready-by — Enables the heater and computes when to start it so the pool hits your target temperature by a specified arrival time, using the learned heat rate from telemetry history.
Use this instead of "set heater + setpoint and guess" when the user has a specific swim time.
hayward-omnilogic-pp-cli ready-by 18:00 --temp 84
Local state that compounds
-
chemistry log — Weekly/monthly pH, ORP, salt, and temperature history from the local store, exportable as CSV or JSON for HOA / service / insurance records.
Use this when an agent needs trend data or a compliance log over a date range.
hayward-omnilogic-pp-cli chemistry log --since 30d --csv
-
chemistry drift — Detects pH/ORP/salt drift versus a rolling baseline before Hayward's static thresholds fire; --forecast projects when each metric will leave the safe range.
Reach for this when the user wants early warning, not just "alarm is active."
hayward-omnilogic-pp-cli chemistry drift --forecast --json
-
runtime — Pump hours, heater hours, salt-cell hours derived from telemetry deltas — for maintenance planning, warranty, and end-of-season service.
Use this when a service-business agent needs maintenance projections or a warranty case-file.
hayward-omnilogic-pp-cli runtime --since 90d --json
-
command-log — Every Set* command issued via this CLI is logged with who/when/what/result. --replay re-issues a prior command for quick undo or redo.
Use this when an agent or operator needs to know what was changed recently or roll back a misfire.
hayward-omnilogic-pp-cli command-log --since 7d
Diagnostics the cloud can't do
-
why-not-running — Diagnose why a pump, heater, or light isn't running: correlates active alarms, current relay state, scheduled run windows, heater demand, and superchlor lockouts into one explanation.
Reach for this when an agent is asked to triage "X isn't running" instead of telling the user to open the app.
hayward-omnilogic-pp-cli why-not-running 'Main Pump'
-
schedule diff — Diffs today's MSP-config schedule tree against prior versioned snapshots; catches silent edits made by service techs or by other app users.
Use this when a user reports unexpected pool behavior and you need to know what changed.
hayward-omnilogic-pp-cli schedule diff --since yesterday
Multi-site operations
-
sweep — Across every site in the account, surface active alarms, out-of-range chemistry, and offline controllers in a single report — built for pool-service businesses doing route planning.
Use this when an agent is asked to prioritize the day's truck rolls across many pools.
hayward-omnilogic-pp-cli sweep --alarms --chemistry --json
Usage
Run hayward-omnilogic-pp-cli --help for the full command reference and flag list.
Commands
alarms
Active alarms across the OmniLogic system
hayward-omnilogic-pp-cli alarms list - List active alarms for a site or every site.
chemistry
Chemistry-only view of telemetry plus historical-store-backed readouts
hayward-omnilogic-pp-cli chemistry get - Current chemistry snapshot: pH, ORP, salt, water temp, with safe-range verdict.
chlorinator
Salt chlorinator configuration
hayward-omnilogic-pp-cli chlorinator set_params - Set chlorinator config (op mode, timed percent, ORP timeout, etc). Defaults to current MSP values for any flag you don't pass.
config
Equipment inventory (MSP config tree) per site
hayward-omnilogic-pp-cli config get - Fetch the equipment inventory for one site — pumps, heaters, chlorinator, lights, valves, relays, sensors.
equipment
Generic on/off + timed-run control for valves, relays, lights, and accessory pumps
hayward-omnilogic-pp-cli equipment off - Turn an equipment item off.hayward-omnilogic-pp-cli equipment on - Turn an equipment item on. Use --for to run for a bounded duration; otherwise stays on until you turn it off.
heater
Heater control (enable/disable + setpoint)
hayward-omnilogic-pp-cli heater disable - Turn a heater off.hayward-omnilogic-pp-cli heater enable - Turn a heater on. Heater stays on until set-temp is reached or you disable it.hayward-omnilogic-pp-cli heater set_temp - Set a heater's target setpoint in degrees Fahrenheit.
light
ColorLogic light shows
hayward-omnilogic-pp-cli light list_shows - List every available ColorLogic show with its numeric ID and human-readable name.hayward-omnilogic-pp-cli light show - Activate a ColorLogic show. V2 lights also accept --speed and --brightness.
pump
Variable-speed pump control
hayward-omnilogic-pp-cli pump set_speed - Set a pump's running speed in RPM or percent (range comes from the pump's MSP config).
sites
Hayward OmniLogic sites (one per backyard controller registered to your account)
hayward-omnilogic-pp-cli sites list - List every site registered under your Hayward account.
spillover
Spillover control (pool-to-spa overflow)
hayward-omnilogic-pp-cli spillover set - Set spillover speed and optional run duration.
superchlor
Manual superchlorination (one-shot)
hayward-omnilogic-pp-cli superchlor off - Stop superchlorination.hayward-omnilogic-pp-cli superchlor on - Start superchlorination on the body-of-water's salt chlorinator. Runs until the configured SCTimeout expires or you turn it off.
telemetry
Live state of every equipment item at one site
hayward-omnilogic-pp-cli telemetry get - Snapshot live state: chemistry (pH/ORP/salt), water and air temperature, pump speeds, heater enable, light state, alarm flags. Append-only-stored in telemetry_samples.
Output Formats
# Human-readable table (default in terminal, JSON when piped)
hayward-omnilogic-pp-cli alarms
# JSON for scripting and agents
hayward-omnilogic-pp-cli alarms --json
# Filter to specific fields
hayward-omnilogic-pp-cli alarms --json --select id,name,status
# Dry run — show the request without sending
hayward-omnilogic-pp-cli alarms --dry-run
# Agent mode — JSON + compact + no prompts in one flag
hayward-omnilogic-pp-cli alarms --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Explicit retries - add
--idempotent to create retries when a no-op success is acceptable
- Confirmable -
--yes for explicit confirmation of destructive actions
- Piped input - write commands can accept structured input when their help lists
--stdin
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 5 API error, 7 rate limited, 10 config error.
Health Check
hayward-omnilogic-pp-cli doctor
Verifies configuration and connectivity to the API.
Configuration
Config file: ~/.config/hayward-omnilogic/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Troubleshooting
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- 401 / "Failed Login" on first call — Confirm HAYWARD_USER is the email you log in with at haywardomnilogic.com (post-Oct-2025 the API rejects username-only); rerun
doctor to re-cache the token.
- Token works for a day then fails — Token cache TTL is 24h; the CLI auto-refreshes via /auth-service/v2/refresh. If refresh fails (e.g., laptop slept past expiry), delete
~/.local/state/hayward-omnilogic/auth.json and rerun any command.
- Schedule diff says "no baseline" on first run — Run
sync --full at least once so the CLI has a prior MSP-config snapshot to compare against.
- chemistry log returns empty — telemetry samples are appended by
sync (or any read-side call); after sync --full you have one point. Run sync periodically (cron / launchd / 30-60s minimum interval per community guidance).
Sources & Inspiration
This CLI was built by studying these projects and resources:
Generated by CLI Printing Press