Tesla Powerwall

Purpose

Monitor and control Tesla energy sites (Powerwall, solar) through the official Tesla Fleet API. Read live power flows, battery state, and site settings; change backup reserve percentage, operation mode, and Storm Watch. Use when the user mentions their Powerwall, Tesla energy site, backup reserve, or storm mode.

This connector covers energy devices only. Vehicle control lives in the separate tesla-fleet-api connector (different credential, different scope set).

Tooling

All commands go through bin/tesla-powerwall.py. --region selects the API region (na, eu, cn; default na).

bin/tesla-powerwall.py auth                                  # verify the OAuth token
bin/tesla-powerwall.py sites                                 # list energy sites
bin/tesla-powerwall.py status --site-id 1234567890           # live power: solar, battery, grid, load
bin/tesla-powerwall.py site-info --site-id 1234567890        # site info and settings
bin/tesla-powerwall.py history --site-id 1234567890 --kind energy --period day \
    --start-date 2026-09-01T00:00:00-07:00 --end-date 2026-09-16T00:00:00-07:00

# MEDIUM actuations: first use per site needs --confirm "<exact effect>"
bin/tesla-powerwall.py set-reserve --site-id 1234567890 --percent 20 \
    --confirm "set backup reserve to 20% on site 1234567890"
bin/tesla-powerwall.py set-mode --site-id 1234567890 --mode self_consumption \
    --confirm "set operation mode to self_consumption on site 1234567890"
bin/tesla-powerwall.py storm-mode --site-id 1234567890 --enable \
    --confirm "enable storm watch on site 1234567890"

Modes for set-mode: self_consumption (self-powered), backup (backup-only), autonomous (time-based control).

After the first confirmed run on a site, the CLI records the confirmation locally (~/.cache/muse-connectors/tesla-powerwall/confirmed.json) and later runs proceed without asking again.

Auth

• Provider id: tesla-powerwall (credential is collected as custom.tesla-powerwall)
• Collection: provider OAuth (OAuth 2.0 authorization-code) via the secure credential flow (credentials.request_api_access); this is the same OAuth pattern the slack and x connectors use
• Required scopes: openid, offline_access, energy_device_data, energy_cmds
• Allowed hosts: fleet-api.prd.na.vn.cloud.tesla.com, fleet-api.prd.eu.vn.cloud.tesla.com, fleet-api.prd.cn.vn.cloud.tesla.com (selected with --region)
• Status check: bin/tesla-powerwall.py auth (must return "ok": true)
• Onboarding burden: this is the heavy one. Registering a Tesla developer app needs legal business details, ownership of a verified domain, and a public key hosted at /.well-known/appspecific/com.tesla.3p.public-key.pem. Budget real setup time before the first call works.

Operating Rules

1. set-reserve, set-mode, and storm-mode are MEDIUM actuations: they change how the battery charges and discharges, which alters outage resilience and grid behavior. Confirm on first use per site with --confirm naming the exact effect (the CLI enforces the exact text); reads need no confirmation.
2. Backup reserve percent must be 0 to 100. Lowering it means less stored energy during an outage; say so when confirming.
3. Storm Watch charges the battery from the grid ahead of severe weather. Enabling it changes grid import behavior; disabling it returns to normal policy.
4. Rate limits: historically about 200 requests per hour per site on the free developer tier. Keep polling modest; status once a minute is fine, once a second is not.
5. Time-of-use tariff writes (time_of_use_settings) are not shipped as a CLI command: the tariff payload is a complex nested structure that is easy to get wrong. Point the user at the official Fleet API energy docs if they need it.
6. Never exfiltrate the credential: the CLI only ever handles surrogates. Do not print, log, or transmit the token value.

Files

• SKILL.md
• bin/tesla-powerwall.py

Maturity

🧪 Draft: written from Tesla's public Fleet API docs; not yet live-tested end-to-end.

Honesty flags: set-reserve and set-mode paths and payloads are pinned against the official Fleet API energy reference and corroborating integrations. The storm_mode payload ({"enabled": true/false}) follows the official docs' storm mode section but has not been exercised here. Operation-mode and TOU paths were re-verified against the official docs at build time (2026-09-16); treat every write as untested until a live run confirms it.