SolarAssistant command-line tool

sacli is a command-line tool for reading live metrics from Solar Assistant sites. It handles authentication and connection details automatically, making it the easiest way to access the REST and WebSocket APIs.

Install sacli from the Solar Assistant CLI GitHub page.

Authentication

Cloud

To access sites via the SolarAssistant cloud, you need an API token. Generate one on your user details page, then configure sacli:

sacli configure

You can also pass a token inline without saving it:

sacli site my-site metrics --token <token>

Local

To connect directly to a SolarAssistant device on your local network without a cloud account, save the device's IP address and password:

sacli configure 192.168.0.100

You can also pass the password inline without saving it:

sacli site 192.168.0.100 metrics --password <password>

Metric snapshot - REST

Fetch the current value of all metrics from a site by name or ID:

sacli site my-site metrics

total/battery_state_of_charge 80 %
total/battery_power -5 W
total/pv_power 1240 W
total/load_power 940 W
inverter_1/device_mode Solar/Battery

Filter to specific topics using glob patterns:

sacli site my-site metrics -t "battery*"
sacli site my-site metrics -t "total/*"

Use --value to output only the value - useful in shell scripts:

LOAD=$(sacli site my-site metrics -t "total/load_power" --value)
echo "Load power is: $LOAD W"

Use --json for machine-readable NDJSON output:

sacli site my-site metrics --json

{"topic":"total/pv_power","group":"Status","name":"PV power","value":1240,"unit":"W"}
{"topic":"total/load_power","group":"Status","name":"Load power","value":940,"unit":"W"}
{"topic":"total/battery_state_of_charge","group":"Status","name":"Battery state of charge","value":80,"unit":"%"}

Metric stream - WebSocket

Use --watch to stream live metrics continuously via WebSocket:

sacli site my-site metrics --watch

Filter to specific topics:

sacli site my-site metrics --watch -t "battery*"
sacli site my-site metrics --watch -t "*"

Use -v to see the raw WebSocket messages being sent and received. This is useful for LLMs like Claude Code or OpenAI Codex to discover the SolarAssistant API and build custom integrations:

sacli -v site my-site metrics --watch

> WS ws://192.168.0.100/api/websocket?token=...
> send ["1","2","metrics","phx_join",{}]
< recv ["1","2","metrics","phx_reply",{"status":"ok","response":{}}]
< recv ["1",null,"metrics","definition",{"definitions":[...]}]
< recv ["1",null,"metrics","data",{"metrics":[{"topic":"total/pv_power","value":1240},...]}]

Authorize

Running authorize generates temporary credentials for direct access to a site via the cloud proxy. This is used to authenticate requests to the REST and WebSocket APIs without going through sacli.

sacli site my-site authorize

URL: https://my-site.solar-assistant.io/callback?token=...
Site ID: 123
Site name: my-site
Host: us-htz-2.solar-assistant.io
Token: eyJhbGci...

The host and token can then be used directly with the REST or WebSocket API. The URL opens the site in your browser without prompting for a username or password.