← Back to ctrlpi-cli

ctrlPi API CLI

Platform: Cross-Platform Version 0.9.40 Python 3.9+ Auth: Api-Key License: MIT Status: Beta

A pure-Python command-line interface for interacting with ctrlPi agents (Raspberry Pi, Pico W, ESP32). Designed to be fast and portable with zero external dependencies.

Setup

No installation required, just Python 3 standard library.

git clone https://github.com/ctrlpi/ctrlpi-cli.git
cd ctrlpi-cli
chmod +x ctrlpi-cli.py

On Windows, run it through Python instead: python ctrlpi-cli.py <command>.

Discovery

Find agents on your local network:

./ctrlpi-cli.py scan

This probes your subnet for ctrlPi agents (port 8314) and automatically saves them to ~/.ctrlpi/agents-config.json. Once scanned, you can refer to agents by their name instead of typing out their IP address. A saved agent that took a new address is repaired on the next scan.

The table also lists other SSH devices on the network (usually a Pi that has no agent yet), with - in the ctrlPi column. Host names come from reverse DNS everywhere, plus Bonjour and SMB names on macOS.

Usage

Set your target agent context:

./ctrlpi-cli.py use garage-pi

(You can also optionally pass the host as the first argument to any command to temporarily override the context: ./ctrlpi-cli.py garage-pi gpio read)

A host is an agent name, a .local name or an IP address, optionally with a port (10.0.0.5:8314); an IPv6 address with a port goes in brackets ([fd00::5]:8314).

Results print to stdout (JSON, or the scan table), while errors and notes print to stderr, so a result can be piped straight into a tool such as jq.

Config files (the default host and the saved agents) live in ~/.ctrlpi/. To keep them in a different folder, pass --config <dir> anywhere on the command line:

./ctrlpi-cli.py --config ~/lab-ctrlpi use garage-pi

API keys

Every command sends the agent's Api-Key. For a saved agent it is the api_key stored in ~/.ctrlpi/agents-config.json; for anything else it is the agents' default key, your-secret-key. A scan saves each new agent on the default key, or with an empty api_key when the agent already has a key of its own; fill that in by hand.

To use a different key for one command, pass --api-key:

./ctrlpi-cli.py --api-key my-secret garage-pi config read

Changing the key or name with config update or config load also saves the new value in agents-config.json (updating the agent's existing entry, even one saved under an older address), so the next command still reaches the agent. An empty key changes nothing, on the agent or here. Keys, names, URLs and scripts are always sent as text, so webhook_key=007 stays "007".

Examples

The CLI covers every endpoint of the agent's REST API that needs a key. Below are some core examples, assuming you are in the context of an agent (./ctrlpi-cli.py use pi4).

1. Read a GPIO pin

./ctrlpi-cli.py gpio r 26

2. Set an output pin

./ctrlpi-cli.py gpio w 26 1

3. Send a brief pulse (write with duration)

# Writes a 1, then after 2.5 seconds the pin goes back to its previous state
./ctrlpi-cli.py gpio w 26 1 2.5

4. Configure a pin

./ctrlpi-cli.py gpio config 26 name=relay type=output reversed=true max=3600

5. Scan all hardware GPIO pins

./ctrlpi-cli.py gpio scan

6. Configure a watched input (fires a webhook on change)

./ctrlpi-cli.py gpio config 6 type=input watched=true

7. Change the webhook URL

./ctrlpi-cli.py config update webhook_url=https://example.com/webhook

8. Load a full configuration from a file

./ctrlpi-cli.py config load my-config.json

9. Configure a sensor

./ctrlpi-cli.py sensor config cpu_temp script=cpu-temp.sh

10. Read a sensor

./ctrlpi-cli.py sensor r cpu_temp

11. Manage the agent's scripts

The files in the agent's scripts/ folder, the one sensors run from (agents 0.9.28 or later). Writing and removing need an agent key other than the default your-secret-key, and are refused once a write.lock file is in the folder.

./ctrlpi-cli.py script list
./ctrlpi-cli.py script read cpu-temp.sh > cpu-temp.sh   # prints the file's text as is
./ctrlpi-cli.py script write weather.py ./weather.py    # upload a local file (creates or overwrites)
./ctrlpi-cli.py script run weather.py zone1             # {"name", "exit_code", "output"}
./ctrlpi-cli.py script rm weather.py

12. View watched pins and webhooks

./ctrlpi-cli.py gpio watched

13. View recent agent logs

./ctrlpi-cli.py logs

14. Restart or upgrade the agent

./ctrlpi-cli.py restart
# To physically reboot the device instead of just the agent:
./ctrlpi-cli.py restart reboot

./ctrlpi-cli.py upgrade

15. Test an agent

Runs 10 checks against the agent and prints PASS, FAIL or SKIP for each, then exits with 0 when none failed:

./ctrlpi-cli.py test
./ctrlpi-cli.py pi4 test
# Check What it does
1 Agent answers /hello answers with the agent's name
2 Key and config a wrong key is refused, and /config/read answers with gpios and the agent block
3 Read pins all pins, the first configured one, and 404 for a pin that does not exist
4 Write an output writes the first output pin's own value and reads it back (skipped with no output pin)
5 Scan pins /gpio/scan lists the pins (skipped on a platform with no GPIOs)
6 Configure a pin configures the highest free pin as an input, checks it, removes it and checks again
7 Sensors /sensor/read answers
8 Run a script runs the cpu-temp example (skipped when it is not there)
9 Write a script writes cli-test.sh, reads it back, then removes it (skipped while write.lock is in scripts/)
10 Logs /logs answers

The agent is left as it was: no output changes state, the test pin and the test script are removed again, and nothing is restarted. Webhooks are not tested. On the default key, check 9 sets a temporary key for the write (script writes need one), then puts the default back; if that fails, the CLI prints the temporary key.

Testing

The test suite starts its own mock agent (mock_agent.py), so no real agent is needed:

python3 test.py

Related projects

License

MIT