poolctl 🌊🤖🔱

A terminal-first Pentair ScreenLogic control tool for interrogating and nudging a mildly cursed pool box over the LAN.

poolctl is part of the same small-tool family as lightctl and hottubctl: sharp commands, readable output, no app-shaped nonsense.

What it does

• discovers ScreenLogic adapters on the local network
• shows current pool/spa status in a compact CLI format
• inspects circuits, bodies, and pumps
• checks and controls the cleaner
• checks and cancels system delay state

Install

git clone git@github.com:your-user/poolctl.git
cd poolctl
just install

That installs poolctl with pipx so it behaves like a normal command, not a repo you have to babysit.

Useful just targets:

just status
just circuits
just bodies
just pumps
just raw

Local config

poolctl stores discovered adapter config here:

• ~/.config/poolctl/config.json

That file is local machine state, not repo content.

Commands

Core inspection:

• poolctl discover
• poolctl status
• poolctl circuits
• poolctl bodies
• poolctl pumps

Cleaner control:

• poolctl cleaner status
• poolctl cleaner on --yes
• poolctl cleaner off --yes

Delay control:

• poolctl delay status
• poolctl delay cancel --yes

Debugging / direct host override:

• poolctl --host 192.168.1.50 status

Default output is compact and human-readable. Use --json for structured output. Use poolctl status --raw when you want the raw payload.

Example status output:

Model: EasyTouch2 4P
Air: 64°F
Salt: 2750 ppm
Bodies:
- Pool: 66°F, heat_mode=Solar, setpoint=85°F, heat_state=Off
- Spa: 65°F, heat_mode=Off, setpoint=100°F, heat_state=Off

Development

For early development or protocol poking:

python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
pip install pytest
PYTHONPATH=. pytest -q
python poolctl.py status

Once the CLI is useful, prefer the installed command shape via just install / just reinstall.

Why this repo exists

The goal is not to build a giant pool platform. The goal is to make the useful 90% easy:

• inspect the system quickly
• script common actions
• avoid phone-app friction
• keep the interface boring enough to trust

Extra docs

• AGENTS.md — project principles and engineering intent
• SKILL.md — lets an agent/chat workflow drive the CLI directly

Built with

This repo was created with:

• OpenClaw 2026.3.28 (f9b1079)
• OpenAI GPT 5.4

Current shape

This repo is the most mature of the three *ctl siblings. It already covers the everyday useful stuff and serves as the pattern for the others:

• installable CLI
• compact human-readable output
• local config outside the repo
• explicit commands instead of magical orchestration

Agent-first repo notes

This repo is intended to be agent-friendly as well as human-friendly. The standard agent-first files live at the repo root:

• README.md — human-facing overview
• AGENTS.md — project principles and working conventions
• SKILL.md — direct agent usage guidance