What it is
Control your Raspberry Pi, Pico W, and ESP32 agents from a terminal. ctrlpi-cli talks to their REST APIs using only the Python standard library. Discover boards once, select an agent by name, and use the same commands for GPIO, sensors, configuration, and logs.
Set up & discover
You need Python 3 and a reachable Pi, Pico, or ESP32 agent. Clone the package, then scan your local network:
git clone https://github.com/ctrlpi/ctrlpi-cli.git cd ctrlpi-cli chmod +x ctrlpi-cli.py ./ctrlpi-cli.py scan ./ctrlpi-cli.py use garage-pi
Discovery probes port 8314 and saves agents in ~/.ctrlpi/agents-config.json. The selected default agent is kept in ~/.ctrlpi/cli-config.json. You can override it for a single command by putting an agent name before the command.
Read, write & configure
Use a GPIO number appropriate for your board and wiring. Here GPIO 26 is configured as an output named relay, then read and pulsed for 2.5 seconds:
./ctrlpi-cli.py gpio config 26 name=relay type=output ./ctrlpi-cli.py gpio r 26 ./ctrlpi-cli.py gpio w 26 1 2.5 ./ctrlpi-cli.py garage-pi gpio r 26
Beyond GPIO
| Feature | What it does |
|---|---|
| Sensors | Configure a named sensor and read its value with sensor config and sensor r. |
| Watched inputs | Set watched=true on an input and inspect watched pins with gpio watched. |
| Configuration | Update individual settings or load a complete configuration from a JSON file. |
| Logs | Read recent agent logs directly in the terminal. |
| Maintenance | Restart an agent, reboot its device, or request an upgrade. |
./ctrlpi-cli.py sensor r cpu_temp ./ctrlpi-cli.py gpio watched ./ctrlpi-cli.py config load my-config.json ./ctrlpi-cli.py logs
In the family
Drives any mix of pi-gpio-api, pico-gpio-api, and esp32-gpio-api agents, and shares its agent list with every other ctrlPi tool. Put the same pins in Apple Home with homebridge-ctrlpi, or let an AI assistant drive them with mcp-bridge.
To test endpoints, watch webhook events and tail logs in the browser, open ctrlpi-lab.
To get an agent onto a board over USB, use pico-bay. It can install MicroPython,
manage the board's files and run code on a Pico and an ESP32. pi-bay, for a Raspberry Pi
over the network, is coming soon.