Every Tesla mobile-app feature, plus a charging-cost ledger and supercharger queue watcher no other Tesla CLI ships.
The Tesla owner-API as JSON-first commands, with a local SQLite that remembers every vehicle state. Get a single ready yes/no for departure, a tariff-aware charging cost ledger that replaces TeslaMate's Docker stack, and a supercharger queue watcher you can subscribe to from an agent. For 2018+ Models S/X and pre-2021 Models 3/Y, commands route end-to-end on plain REST; newer vehicles get a clear shim message via tesla reachability.
Learn more at Tesla.
Printed by @mvanhorn (Matt Van Horn).
Authentication
Run tesla auth login and the CLI opens Tesla's real login page in your browser. Log in there (Tesla owns MFA, captcha, SMS codes - we never see them), Tesla redirects you to a 404 page on auth.tesla.com after success, you paste that URL back here. The CLI extracts the auth code via PKCE, exchanges it for tokens, and stores them in ~/.config/tesla-pp-cli/config.toml (mode 0600). Bearer tokens last 8h; the CLI silently re-mints them on 401 using the long-lived refresh token, so once you log in you don't need to think about it. Headless / CI fallbacks: auth login --paste reads a pre-captured refresh token from stdin, auth login --refresh-token <tok> skips stdin, and auth login --via tesla-auth subprocesses into adriankumpf/tesla_auth (if you have it installed and prefer the native window). Newer vehicles on Tesla's signed-command protocol need separate key enrollment - see tesla reachability for diagnosis.
Signed-command paths overview
Teslas built in 2021 and later (Model 3/Y from 2021, Model S/X from late 2022, Cybertruck, all Model 3 Highland) do not accept plain REST commands at the owner-API endpoint. They require Tesla's Vehicle Command Protocol (VCP), where every command is signed with an ECDSA key the car has explicitly enrolled. The signing happens client-side; only the signed request reaches Tesla's edge.
VCP has three transports, and this CLI supports all three. Pick the one that matches your hardware, network position, and budget.
| Transport | Reach | Cost | Command coverage | Setup time |
|---|
| BLE | within roughly 30ft of the car | $0 | every signed command | 10 min |
| Hermes (signaling.vn.teslamotors.com) | anywhere with internet | $0 (uses iOS-app OAuth) | infotainment only (charge, climate, honk, media) | 5 min |
| Fleet API (developer.tesla.com) | anywhere with internet | roughly $0/mo inside Tesla's $10/mo personal-use credit | every signed command including unlock/lock/trunk | 30 min |
BLE needs a laptop, Raspberry Pi, or other Linux/macOS host that can sit within Bluetooth range of the parked car. Hermes is Tesla's own mobile-app signaling backend, the same backbone the iOS app uses for push commands; this CLI reuses your iOS-app OAuth bearer to reach it. Fleet API is Tesla's official partner-app surface, registered through developer.tesla.com.
Officially supported vs pragmatic
Fleet API is Tesla's official developer surface, documented, billed, and stable. The Hermes path uses an iOS-app bearer credential reaching Tesla's mobile-app signaling backend. The Hermes path works today but is unofficial; Tesla could change or remove it without notice. Use Fleet for commands you depend on (unlock, lock, daily automations). Use Hermes for routine infotainment commands where you would rather not pay per call.
Quick start: Hermes free path
Free internet control for charge, climate, honk, and media commands. Uses your iOS-app OAuth, no Fleet registration, no per-call billing.
-
tesla auth login --via tesla-auth
iOS-app PKCE flow. Stores the bearer this CLI needs for both REST and Hermes.
-
tesla auth ble-pair --vin <your-vin>
Enroll this CLI's public key on the car over BLE. Run from a laptop within roughly 30ft of the car. The car prompts for an NFC tap to confirm.
-
Install and run tesla-http-proxy:
go install github.com/teslamotors/vehicle-command/cmd/tesla-http-proxy@latest
tesla-http-proxy -key-file ~/.config/tesla-pp-cli/private.pem -port 4443 -cert auto
-
tesla relay start && tesla command set-charge-limit --vehicle <name> --percent 80 --send
The relay forwards signed commands through Hermes. Replace <name> with the friendly name the CLI prints under tesla products.
Quick start: Fleet API path
Full coverage including unlock, lock, trunk, and any other signed command, callable from anywhere with internet. Roughly $0/mo for typical hobbyist use after the $10/mo personal-use credit.
-
tesla auth fleet-template --gen-key --dest ./tesla-keys-host
Scaffolds the public-key host (a Vercel project that serves /.well-known/appspecific/com.tesla.3p.public-key.pem) and generates an ECDSA P-256 keypair under ~/.config/tesla-pp-cli/.
-
cd tesla-keys-host && vercel deploy --prod
Deploys the host. Vercel returns the public hostname (something like <your-host>.vercel.app). Tesla resolves that hostname to fetch your public key during partner registration and during every signed command.
-
Register your app at developer.tesla.com.
On the partner account dashboard, register a new app with allowed origin and redirect set to https://<your-host>.vercel.app, and copy the client_id and client_secret Tesla shows you.
-
tesla auth fleet-register --public-key-domain <your-host>.vercel.app --client-id <id> --client-secret-file <secret-file>
Registers your partner_accounts entry with Tesla. After this, Tesla's API recognizes your public key for signed commands.
-
tesla auth fleet-login
Browser-based user OAuth, callback on localhost:8585. Saves the Fleet user bearer token alongside the REST bearer.
-
tesla command unlock --vehicle <name> --send
Signed remote unlock from anywhere with internet.
Choosing your path
| Situation | Path |
|---|
| Pre-2021 Tesla | REST (existing default, no extra setup) |
| Want $0 cost and your car is at home | BLE (run from a laptop or Pi within Bluetooth range) |
| Want $0 and remote control of infotainment commands only | Hermes |
| Want full coverage including unlock from anywhere | Fleet API |
| Want to deploy your agent to a cloud Mac mini | Fleet plus tesla auth export then tesla auth import |
Costs
Quoted from developer.tesla.com, May 2026.
- Fleet API: $0.001 per command, $0.02 per wake
- $10/month personal-use credit covers roughly 100 commands plus 2 wakes per day for two vehicles
- Hermes: $0 (uses your iOS-app OAuth)
- BLE: $0 (free forever)
A typical hobbyist driving one or two vehicles lands under $1/mo gross, $0 net after the personal-use credit.
Brokers (Teslemetry, Tessie, TeslaFi) are listed here only for completeness. They are not in the default path. Each broker holds your signing key on your behalf, which the CLI avoids by design; the BYOK (bring your own key) model in this CLI keeps the private key on your host.
BLE virtual-key enrollment
tesla auth ble-pair --vin <your-vin> runs the full BLE handshake: it subprocesses into tesla-control (from teslamotors/vehicle-command), points it at the keypair under ~/.config/tesla-pp-cli/, and waits for the car to prompt for an NFC tap. Bring a Tesla-issued NFC card or the phone key from the iOS app, tap the center console when prompted, and the car records this CLI's public key as a virtual key.
You need the laptop within roughly 30ft of the car for this one-time enrollment. Once enrolled, the same key signs commands over BLE (proximity) and over Fleet API (internet). Hermes uses the same key once fleet-register has uploaded it.
Multi-machine deployments
When you want the same CLI usable from your laptop and from a cloud Mac mini (or a Raspberry Pi, or both), export the credentials and the enrolled key as one bundle and import on the second host.
-
tesla auth export --out tesla-bundle.enc
Produces a passphrase-encrypted bundle (Argon2id KDF, AES-256-GCM cipher). The bundle contains the REST bearer, the Fleet bearer if present, and the ECDSA keypair.
-
Copy tesla-bundle.enc to the remote (scp over Tailscale, or any other secure channel).
-
tesla auth import tesla-bundle.enc on the remote, then enter the passphrase.
The same Fleet creds and the same enrolled key now work on both machines. The car still recognizes the key because key identity is on the keypair, not the host.
Quick Start
# Confirm auth and list your vehicle_id / VINs / energy sites. Run 'tesla auth login' first if needed (see Auth section above).
tesla products --json
# Confirm auth works and list your vehicle_id / VINs / energy site IDs.
tesla products --json
# Classify each vehicle: REST-OK (legacy) or signed-command-required (newer).
tesla reachability --json
# Capture a vehicle_data snapshot for every car; populates the local store for analytics.
tesla snap --all --json
# Single yes/no "can I leave?" with the blocker list.
tesla ready 5YJ3E1EA6XXXXXXXX --json
# Last 30 days of charging cost, home vs Supercharger split.
tesla cost ledger --since 30d --json
Unique Features
These capabilities aren't available in any other tool for this API.
Composite truth from local state
-
ready — Single yes/no answer to "can I leave in 5 minutes?" with reasoned blocker list - SOC vs trip distance, plugged-in, doors closed, sentry off, cabin within 3F of target, no mid-install update
Most-asked Tesla owner question; the iOS app makes it a 6-tap diagnostic, agents need a one-call truth
tesla ready 5YJ3E1EA6XXXXXXXX --json
Local analytics that beat the dashboard
-
cost ledger — Per-session cost, monthly spend, home-vs-Supercharger ratio with tariff-window aware $/kWh
Charging cost is the #1 Tesla-owner spreadsheet exercise; this is the first pure-CLI replacement for the TeslaMate dashboard
tesla cost ledger --since 2026-04-01 --group supercharger --json
-
cost what-if — "If you had only charged at home you would have saved $X over the last 90 days." Re-runs charge rows with home $/kWh substituted for Supercharger sessions
Most Tesla owners suspect they could save by charging at home but lack proof; this puts a dollar figure on it
tesla cost what-if --only-home --since 90d --json
-
timeline — Stitched drives + charges from synced vehicle_states polls - start/end, distance, energy, efficiency, address-resolved lat/lng
Lets agents reason over the same data TeslaMate exposes, without standing up Docker+Postgres+Grafana
tesla timeline --since "last week" --json
-
vampire — SOC delta vs idle time, flags suspicious sentry sessions or app-wake events
Warranty-dispute evidence and rogue-sentry detection; TeslaMate dashboard only otherwise
tesla vampire --threshold 1.5pct/24h --since 30d --json
Charging intelligence nobody else exposes
-
supercharger watch — Single-poll snapshot of free stalls at a saved Supercharger; --watch repeats every N seconds with JSON-lines transitions
Avoids the I-90 Issaquah queue at peak; pageable from an agent on a drive
tesla supercharger watch 1000 --free-stalls 2 --watch --json
Security audit nobody else does
-
keys audit — Lists every enrolled key with last-seen, role, form-factor; flags keys not seen >90d as stale candidates for removal
Security-minded owners worry about old phones and abandoned NFC cards still pairing with their car; this is the quarterly review
tesla keys audit --stale-after 90d --json
Reachability mitigation
-
doctor — Detects signed-command-required errors, classifies the vehicle as REST-friendly vs signed-command-required, prints tesla-control enrollment URL when needed
Tesla's 2024-2026 signed-command rollout is the #1 user-facing landmine for any Tesla CLI; this is the only one that surfaces it clearly
tesla doctor --json
Usage
Run tesla-pp-cli --help for the full command reference and flag list.
Commands
charging
Supercharger queue position and charging status
tesla-pp-cli charging - Current Supercharger queue position (which stall, ETA)
diagnostics
Vehicle diagnostic feature config
tesla-pp-cli diagnostics - Vehicle diagnostic feature flags
energy_sites
Powerwall and solar energy site config
tesla-pp-cli energy_sites create-set-backup-reserve - Set Powerwall backup reserve percenttesla-pp-cli energy_sites create-set-operation - Set Powerwall operation modetesla-pp-cli energy_sites get-calendar-history - Historical energy data per day/monthtesla-pp-cli energy_sites get-live-status - Real-time Powerwall solar/grid/battery powertesla-pp-cli energy_sites get-rate-tariffs - Utility rate plans for Powerwall schedulingtesla-pp-cli energy_sites get-site-info - Energy site config (capacity, type, address)tesla-pp-cli energy_sites get-site-status - Backup-reserve and operation mode
logs
Client-side telemetry sink
tesla-pp-cli logs - Forward client-side log events (mostly internal use)
notification_preferences
Push notification settings
tesla-pp-cli notification_preferences - Update push notification preferences
products
Vehicles, Powerwalls, and solar products owned by the user
tesla-pp-cli products - List vehicles, Powerwalls, and solar products owned
users
Account config, feature flags, orders, and key/credential management
tesla-pp-cli users create-keys - Add a virtual phone key or BLE keytesla-pp-cli users get-app-config - Mobile app feature flags and runtime configtesla-pp-cli users get-feature-config - Account-level feature gatingtesla-pp-cli users get-orders - Tesla orders (new vehicle deliveries, accessory purchases)
vehicles
Per-vehicle data, climate, locks, remote start, and Hermes telemetry token
tesla-pp-cli vehicles create-actuate-trunk - Open/close trunk or frunk; which_trunk = front | reartesla-pp-cli vehicles create-add-charge-schedule - Add a charging schedule (location + time window)tesla-pp-cli vehicles create-add-precondition-schedule - Add a preconditioning scheduletesla-pp-cli vehicles create-adjust-volume - Set volume to specific leveltesla-pp-cli vehicles create-auto-conditioning-start - POST /api/1/vehicles/{vehicle_id}/command/auto_conditioning_starttesla-pp-cli vehicles create-auto-conditioning-stop - POST /api/1/vehicles/{vehicle_id}/command/auto_conditioning_stoptesla-pp-cli vehicles create-bioweapon-mode - Toggle bioweapon defense mode (HEPA recirculation)tesla-pp-cli vehicles create-cancel-software-update - Cancel pending software updatetesla-pp-cli vehicles create-charge-max-range - Set charge limit to Max Range (100%)tesla-pp-cli vehicles create-charge-port-door-close - Close the charge porttesla-pp-cli vehicles create-charge-port-door-open - Open the charge porttesla-pp-cli vehicles create-charge-standard - Set charge limit to Standard (~90%)tesla-pp-cli vehicles create-charge-start - Start chargingtesla-pp-cli vehicles create-charge-stop - Stop chargingtesla-pp-cli vehicles create-climate-keeper-mode - Climate keeper mode: 0=off, 1=on, 2=dog, 3=camptesla-pp-cli vehicles create-door-lock - POST /api/1/vehicles/{vehicle_id}/command/door_locktesla-pp-cli vehicles create-door-unlock - POST /api/1/vehicles/{vehicle_id}/command/door_unlocktesla-pp-cli vehicles create-erase-user-data - Erase guest-session user datatesla-pp-cli vehicles create-flash-lights - Flash headlightstesla-pp-cli vehicles create-guest-mode - Enable/disable Guest modetesla-pp-cli vehicles create-hermes - POST /api/1/vehicles/{vehicle_id}/jwt/hermestesla-pp-cli vehicles create-honk-horn - Honk the horntesla-pp-cli vehicles create-max-defrost - Toggle max defrosttesla-pp-cli vehicles create-media-next-favorite - Next favorite stationtesla-pp-cli vehicles create-media-next-track - Next tracktesla-pp-cli vehicles create-media-prev-favorite - Previous favorite stationtesla-pp-cli vehicles create-media-prev-track - Previous tracktesla-pp-cli vehicles create-media-toggle-playback - Toggle play/pausetesla-pp-cli vehicles create-media-volume-down - Volume downtesla-pp-cli vehicles create-media-volume-up - Volume uptesla-pp-cli vehicles create-navigation-gps-request - Send lat/lng directly to navigationtesla-pp-cli vehicles create-remote-start-drive - POST /api/1/vehicles/{vehicle_id}/command/remote_start_drivetesla-pp-cli vehicles create-remove-charge-schedule - Remove charging schedule by idtesla-pp-cli vehicles create-remove-precondition-schedule - Remove preconditioning schedule by idtesla-pp-cli vehicles create-reset-valet-pin - Reset Valet PINtesla-pp-cli vehicles create-schedule-software-update - Schedule the pending software updatetesla-pp-cli vehicles create-seat-heater-request - Set seat heater level (0-3) at a seat position (0=driver, 1=passenger, 2-5=rear)tesla-pp-cli vehicles create-set-charge-limit - Set charge limit percent (50-100)tesla-pp-cli vehicles create-set-charging-amps - Set charging amps drawtesla-pp-cli vehicles create-set-sentry-mode - Enable/disable Sentry modetesla-pp-cli vehicles create-set-temps - Set driver and passenger climate temps (Celsius)tesla-pp-cli vehicles create-set-valet-mode - Enable/disable Valet mode with optional PINtesla-pp-cli vehicles create-share - Send navigation destination to the car (address or coordinates)tesla-pp-cli vehicles create-speed-limit-activate - Activate Speed Limit modetesla-pp-cli vehicles create-speed-limit-clear-pin - Clear Speed Limit PINtesla-pp-cli vehicles create-speed-limit-deactivate - Deactivate Speed Limit modetesla-pp-cli vehicles create-speed-limit-set-limit - Set Speed Limit value (mph)tesla-pp-cli vehicles create-steering-wheel-heater-request - Toggle steering wheel heatertesla-pp-cli vehicles create-sun-roof-control - Sun roof: state = vent | closetesla-pp-cli vehicles create-trigger-homelink - Trigger HomeLink garage doortesla-pp-cli vehicles create-wake-up - Wake the vehicle from sleeptesla-pp-cli vehicles create-window-control - Vent or close all windows; command = vent | closetesla-pp-cli vehicles get-compose-image - Compose a rendered image of the configured vehicletesla-pp-cli vehicles get-data-charge-state - Charge state subset (faster than full vehicle_data)tesla-pp-cli vehicles get-data-climate-state - Climate state subsettesla-pp-cli vehicles get-data-drive-state - Drive state (location, speed, shift) subsettesla-pp-cli vehicles get-data-gui-settings - GUI settings (units, time format)tesla-pp-cli vehicles get-data-vehicle-config - Vehicle config (model, options, trim)tesla-pp-cli vehicles get-data-vehicle-state - Vehicle state (locks, software, sentry) subsettesla-pp-cli vehicles get-mobile-enabled - Is mobile control enabled in the cartesla-pp-cli vehicles get-nearby-chargers - Nearby Supercharger sites with stall availability subfieldtesla-pp-cli vehicles get-release-notes - Release notes for the current/queued software updatetesla-pp-cli vehicles get-service-data - Open service appointments and recent service history for this vehicletesla-pp-cli vehicles get-vehicle-data - Full vehicle state snapshot: charge, climate, drive, GUI, vehicle config, and software
Output Formats
# Human-readable table (default in terminal, JSON when piped)
tesla-pp-cli charging
# JSON for scripting and agents
tesla-pp-cli charging --json
# Filter to specific fields
tesla-pp-cli charging --json --select id,name,status
# Dry run — show the request without sending
tesla-pp-cli charging --dry-run
# Agent mode — JSON + compact + no prompts in one flag
tesla-pp-cli charging --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Explicit retries - add
--idempotent to create retries when a no-op success is acceptable
- Confirmable -
--yes for explicit confirmation of destructive actions
- Piped input - write commands can accept structured input when their help lists
--stdin
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Health Check
tesla-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Config file: ~/.config/tesla-pp-cli/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
TESLA_AUTH_TOKEN | per_call | Yes | Set to your API credential. |
Troubleshooting
Authentication errors (exit code 4)
- Run
tesla-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $TESLA_AUTH_TOKEN
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
tesla command ... returns vehicle command protocol required — Your vehicle is on Tesla's new signed-command protocol. Run tesla doctor for enrollment URL; install tesla-control from teslamotors/vehicle-command for command operations- All commands return 401 token expired — Auto-refresh should handle this transparently. If it doesn't (refresh token revoked), run
tesla auth login to re-authenticate. To disable auto-refresh entirely, set TESLA_PP_NO_AUTOREFRESH=1.
- vehicle_data calls drain the 12V battery — Run snapshots on a cron with
tesla snap --all and avoid keeping the car awake unnecessarily; check tesla doctor for asleep-state behavior and battery drain mitigation
tesla cost ledger shows $0 for Supercharger sessions — Run tesla snap --all to refresh vehicle_data, then tesla timeline to stitch new charge sessions into tesla_charges; Supercharger pricing may also lag in the upstream CHARGING_HISTORY by up to 24h
Discovery Signals
This CLI was generated with browser-captured traffic analysis.
- Target observed: https://owner-api.teslamotors.com/api/1/logs
- Capture coverage: 58 API entries from 60 total network entries
- Reachability: standard_http (95% confidence)
- Protocols: firebase (75% confidence), rest_json (75% confidence)
- Auth signals: bearer_token — headers: authorization; cookie — cookies: _abck, bm_sz; api_key — query: key
- Generation hints: browser_clearance_required, requires_browser_auth
- Candidate command ideas: create_auto_conditioning_start — Derived from observed POST /api/{id}/vehicles/5YJ3E1EA6XXXXXXXX/command/auto_conditioning_start traffic.; create_auto_conditioning_stop — Derived from observed POST /api/{id}/vehicles/5YJ3E1EA6XXXXXXXX/command/auto_conditioning_stop traffic.; create_diagnostic — Derived from observed POST /mobile-app/macgyver/diagnostic traffic.; create_door_lock — Derived from observed POST /api/{id}/vehicles/5YJ3E1EA6XXXXXXXX/command/door_lock traffic.; create_door_unlock — Derived from observed POST /api/{id}/vehicles/5YJ3E1EA6XXXXXXXX/command/door_unlock traffic.; create_fireperf:fetch — Derived from observed POST /v1/projects/tesla-prod/namespaces/fireperf:fetch traffic.; create_hermes — Derived from observed POST /api/{id}/vehicles/5YJ3E1EA6XXXXXXXX/jwt/hermes traffic.; create_keys — Derived from observed POST /api/{id}/users/keys traffic.
Sources & Inspiration
This CLI was built by studying these projects and resources:
Generated by CLI Printing Press