pp-hayward-omnilogic

name	pp-hayward-omnilogic
description	Take control of every Hayward OmniLogic feature, plus a local store, schedule diffs, chemistry trends, and a morning... Trigger phrases: `is the pool ready`, `what's the pool temperature`, `show me the pool chemistry log`, `why isn't the pool pump running`, `preheat the pool for tonight`, `run the morning pool sweep`, `use hayward-omnilogic`, `run hayward-omnilogic`.
author	Rob Zehner
license	Apache-2.0
argument-hint	<command> [args] | install cli|mcp
allowed-tools	Read Bash
metadata	{"openclaw":{"requires":{"bins":["hayward-omnilogic-pp-cli"]}}}

Hayward OmniLogic — Printing Press CLI

Prerequisites: Install the CLI

This skill drives the hayward-omnilogic-pp-cli binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to $HOME/.local/bin on macOS/Linux and %LOCALAPPDATA%\Programs\PrintingPress\bin on Windows:

   npx -y @mvanhorn/printing-press-library install hayward-omnilogic --cli-only
   

2. Verify: hayward-omnilogic-pp-cli --version
3. Ensure the reported install directory is on $PATH for the agent/runtime that will invoke this skill.

If the npx install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.5 or newer):

go install github.com/mvanhorn/printing-press-library/library/devices/hayward-omnilogic/cmd/hayward-omnilogic-pp-cli@latest

If --version reports "command not found" after install, the runtime cannot see the binary directory on $PATH. Do not proceed with skill commands until verification succeeds.

Pool sensor capabilities — configure once per site

Not every OmniLogic install has every sensor. Common variants:

• No pH or ORP probe (most basic salt-pool installs)
• No salt cell (chlorine-tab or liquid-chlorine pools)
• Water-temp sensor that only reads while the pump is running (a quirk of certain pump/sensor pairings)

When sensors are absent, Hayward's API returns -1 or null for those fields. Without telling the CLI which sensors actually exist, status will report "caution" for a perfectly healthy pool simply because chemistry comes back as unknown. The chemistry get, telemetry get, and status commands include a setup_hint field in the JSON output when this is detected.

Configure once per site:

# Example: pool without pH/ORP probes, no salt cell, temp sensor needs pump flow
hayward-omnilogic-pp-cli capabilities set \
  --has-ph false --has-orp false --has-salt false --temp-needs-flow true

# Inspect:
hayward-omnilogic-pp-cli capabilities get --json

Stored in the local SQLite store per MspSystemID. After configuration: status correctly excludes the missing sensors from its verdict, chemistry get returns not_equipped instead of unknown for sensors that don't exist, and water_temp = -1 while the pump is idle is reported as "n/a (pump off)" instead of "sensor offline".

Agents seeing setup_hint in CLI output should surface the suggested capabilities set command to the user as a one-time setup step before relying on chemistry/temp verdicts.

When to Use This CLI

Pick this CLI when an agent needs to read or control a Hayward OmniLogic pool/spa system over the partner cloud API: pool owners managing one pool, integrators wiring OmniLogic into agentic workflows, and pool-service businesses managing many sites. The CLI replaces ad-hoc Python scripts on top of omnilogic-api, the Hayward mobile app for diagnostics and trends, and the per-site click-through pool-service operators do every morning.

Unique Capabilities

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
  

Command Reference

alarms — Active alarms across the OmniLogic system

• hayward-omnilogic-pp-cli alarms — 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 — Current chemistry snapshot: pH, ORP, salt, water temp, with safe-range verdict.

chlorinator — Salt chlorinator configuration

• hayward-omnilogic-pp-cli chlorinator — Set chlorinator config (op mode, timed percent, ORP timeout, etc). Defaults to current MSP values for any flag you...

config — Equipment inventory (MSP config tree) per site

• hayward-omnilogic-pp-cli config — 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 <pump_name> — 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 every site registered under your Hayward account.

spillover — Spillover control (pool-to-spa overflow)

• hayward-omnilogic-pp-cli spillover — 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...

telemetry — Live state of every equipment item at one site

• hayward-omnilogic-pp-cli telemetry — Snapshot live state: chemistry (pH/ORP/salt), water and air temperature, pump speeds, heater enable, light state,...

Finding the right command

When you know what you want to do but not which command does it, ask the CLI directly:

hayward-omnilogic-pp-cli which "<capability in your own words>"

which resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code 0 means at least one match; exit code 2 means no confident match — fall back to --help or use a narrower query.

Recipes

Is the pool ready for guests?

hayward-omnilogic-pp-cli status --json --select verdict,chemistry,water_temp,active_alarms

One call, structured answer. Use --select to keep the JSON tight when piping to an LLM.

Weekly chemistry log for the service record

hayward-omnilogic-pp-cli chemistry log --since 7d --csv > pool-chem-$(date +%Y-%m-%d).csv

Cron this every Sunday and the binder writes itself.

Why isn't the main pump running right now?

hayward-omnilogic-pp-cli why-not-running 'Main Pump' --json

Returns the explanation as structured fields: active_alarms, scheduled_window, current_state, heater_demand, superchlor_lockout.

Morning sweep across every site

hayward-omnilogic-pp-cli sweep --alarms --chemistry --json | jq '.sites[] | select(.alarms != [] or .chemistry_out_of_range == true)'

Pool-service operators: this collapses 12 in-app site-checks into one piped command.

Preheat for an evening swim with ETA from learned heat rate

hayward-omnilogic-pp-cli ready-by 19:30 --temp 86 --dry-run

Pass --dry-run first to see when the heater would start; drop the flag to actually enable it.

Auth Setup

No authentication required.

Run hayward-omnilogic-pp-cli doctor to verify setup.

Agent Mode

Add --agent to any command. Expands to: --json --compact --no-input --no-color --yes.

• Pipeable — JSON on stdout, errors on stderr

• Filterable — --select keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs:

  hayward-omnilogic-pp-cli alarms --agent --select id,name,status
  

• Previewable — --dry-run shows the request without sending

• Non-interactive — never prompts, every input is a flag

• Explicit retries — use --idempotent only when an already-existing create should count as success

Agent Feedback

When you (or the agent) notice something off about this CLI, record it:

hayward-omnilogic-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
hayward-omnilogic-pp-cli feedback --stdin < notes.txt
hayward-omnilogic-pp-cli feedback list --json --limit 10

Entries are stored locally at ~/.hayward-omnilogic-pp-cli/feedback.jsonl. They are never POSTed unless HAYWARD_OMNILOGIC_FEEDBACK_ENDPOINT is set AND either --send is passed or HAYWARD_OMNILOGIC_FEEDBACK_AUTO_SEND=true. Default behavior is local-only.

Write what surprised you, not a bug report. Short, specific, one line: that is the part that compounds.

Output Delivery

Every command accepts --deliver <sink>. The output goes to the named sink in addition to (or instead of) stdout, so agents can route command results without hand-piping. Three sinks are supported:

Sink	Effect
stdout	Default; write to stdout only
file:<path>	Atomically write output to <path> (tmp + rename)
webhook:<url>	POST the output body to the URL (application/json or application/x-ndjson when --compact)

Unknown schemes are refused with a structured error naming the supported set. Webhook failures return non-zero and log the URL + HTTP status on stderr.

Named Profiles

A profile is a saved set of flag values, reused across invocations. Use it when a scheduled agent calls the same command every run with the same configuration - HeyGen's "Beacon" pattern.

hayward-omnilogic-pp-cli profile save briefing --json
hayward-omnilogic-pp-cli --profile briefing alarms
hayward-omnilogic-pp-cli profile list --json
hayward-omnilogic-pp-cli profile show briefing
hayward-omnilogic-pp-cli profile delete briefing --yes

Explicit flags always win over profile values; profile values win over defaults. agent-context lists all available profiles under available_profiles so introspecting agents discover them at runtime.

Exit Codes

Code	Meaning
0	Success
2	Usage error (wrong arguments)
3	Resource not found
5	API error (upstream issue)
7	Rate limited (wait and retry)
10	Config error

Argument Parsing

Parse $ARGUMENTS:

1. Empty, help, or --help → show hayward-omnilogic-pp-cli --help output
2. Starts with install → ends with mcp → MCP installation; otherwise → see Prerequisites above
3. Anything else → Direct Use (execute as CLI command with --agent)

MCP Server Installation

Install the MCP binary from this CLI's published public-library entry or pre-built release, then register it:

claude mcp add hayward-omnilogic-pp-mcp -- hayward-omnilogic-pp-mcp

Verify: claude mcp list

Direct Use

1. Check if installed: which hayward-omnilogic-pp-cli If not found, offer to install (see Prerequisites at the top of this skill).
2. Match the user query to the best command from the Unique Capabilities and Command Reference above.
3. Execute with the --agent flag:

   hayward-omnilogic-pp-cli <command> [subcommand] [args] --agent
   

4. If ambiguous, drill into subcommand help: hayward-omnilogic-pp-cli <command> --help.