Tescmd

tescmd — Tesla Fleet API CLI

Query data from and send commands to Tesla vehicles, energy products, and Supercharger billing via the Tesla Fleet API. Supports CLI invocation, MCP tool calls, and OpenClaw gateway dispatch.

Prefer MCP or OpenClaw Over Direct CLI

Every direct CLI call to the Tesla Fleet API is billable — including 4xx errors like "vehicle asleep" (408) and rate limits (429). There is no free tier.

If tescmd serve is running (MCP + telemetry), always prefer the MCP tools or OpenClaw gateway over spawning CLI subprocesses:

Why this matters: A naive script polling vehicle_data every 5 minutes generates ~1,000+ billable requests/day. With tescmd serve running, telemetry pushes data for free and the MCP/OpenClaw read paths serve it from cache at zero cost. Only write commands (lock, charge, climate) hit the API.

Decision flow:

1. Is tescmd serve running? → Use MCP tools or OpenClaw dispatch
2. No server? → Fall back to direct CLI with --format json --wake

Direct CLI Invocation (Fallback)

When no MCP/OpenClaw server is available, use these flags:

tescmd --format json --wake <command> [args]

VIN can also be passed positionally: tescmd --format json --wake charge status 5YJ3E1EA...

JSON Envelope

All commands return:

{"ok": true, "command": "charge.status", "data": {...}, "timestamp": "...", "_cache": {"hit": true, "age_seconds": 15, "ttl": 60}}

On error: {"ok": false, "error": {"code": "auth_failed", "message": "..."}, "command": "..."}

Error codes: auth_failed (re-login needed), vehicle_asleep (use --wake), tier_readonly (run tescmd setup), key_not_enrolled (run tescmd key enroll), missing_scopes (re-login with scopes).

Caching

Read commands are cached with tiered TTLs: static data (specs, warranty) 1h, fleet lists 5m, standard queries 1m, location/speed 30s. Write commands auto-invalidate the cache. Use --fresh to bypass.

Vehicle State Queries

vehicle

charge

climate

security

software

energy

billing

user

Other reads

Vehicle Commands (Write)

All write commands require --wake for unattended use. Commands using the Vehicle Command Protocol are signed automatically when keys are enrolled.

charge

climate

security

trunk

media

nav

software

energy (write)

vehicle (write)

sharing

Other writes

Trigger Subscriptions

Register conditions on telemetry fields. Available via MCP tools (trigger_create, etc.) and OpenClaw dispatch (trigger.create, etc.).

Operators

Firing modes

• One-shot (once: true): fires once, auto-deletes
• Persistent (once: false, default): fires repeatedly with cooldown_seconds (default 60s)

MCP trigger tools

Param format: Trigger tools use flat parameters — pass field, operator, value directly in arguments. This differs from CLI-based MCP tools which use {vin, args}.

trigger_create — Create a trigger.

{"field": "BatteryLevel", "operator": "lt", "value": 20}

Returns: {"id": "a1b2c3d4e5f6", "field": "BatteryLevel", "operator": "lt"}

Optional params: once (bool), cooldown_seconds (float).

Geofence example:

{"field": "Location", "operator": "enter", "value": {"latitude": 37.7749, "longitude": -122.4194, "radius_m": 500}}

trigger_delete — Delete by ID: {"id": "a1b2c3d4e5f6"}

trigger_list — List all triggers. Returns {"triggers": [...]}

trigger_poll — Drain pending notifications. Returns {"notifications": [{trigger_id, field, operator, threshold, value, previous_value, fired_at, vin}, ...]}

Limits

Max 100 triggers. Max 500 pending notifications (oldest dropped on overflow).

Common telemetry field names

OpenClaw Gateway Commands

When connected via OpenClaw (tescmd serve --openclaw ws://... or tescmd openclaw bridge), bots dispatch commands through the gateway. These use dot-notation.

Read commands

Write commands

Trigger commands (via gateway)

system.run aliases

system.run accepts both OpenClaw-style and API-style names:

Example: {"method": "system.run", "params": {"method": "door_lock", "params": {}}}

Server Modes

Start tescmd serve first, then use MCP tools or OpenClaw dispatch for all reads — this eliminates per-request API costs for vehicle state queries.

tescmd serve (recommended)

Combined MCP + telemetry + OpenClaw with TUI dashboard. Telemetry pushes keep the cache warm so MCP reads are free:

tescmd serve VIN                                    # MCP + telemetry TUI
tescmd serve VIN --openclaw ws://gw:18789           # + OpenClaw bridge
tescmd serve VIN --no-mcp                           # Telemetry-only TUI
tescmd serve --no-telemetry                         # MCP-only (no VIN needed)
tescmd serve --transport stdio                      # MCP stdio for Claude Desktop

tescmd mcp serve

Standalone MCP server (legacy, prefer tescmd serve):

tescmd mcp serve --transport streamable-http --port 8080
tescmd mcp serve --transport stdio

tescmd openclaw bridge

Standalone OpenClaw bridge:

tescmd openclaw bridge VIN --gateway ws://gw:18789 --token SECRET
tescmd openclaw bridge --dry-run                    # JSONL output, no gateway

Common Patterns

Check battery and conditionally start charging

# Read battery
RESULT=$(tescmd --format json --wake charge status VIN)
LEVEL=$(echo "$RESULT" | jq '.data.charge_state.battery_level')

# Start charging if low
if [ "$LEVEL" -lt 20 ]; then
  tescmd --format json --wake charge start VIN
fi

Find the vehicle

tescmd --format json --wake vehicle location VIN
# → data.drive_state.latitude, data.drive_state.longitude

Lock and verify

tescmd --format json --wake security lock VIN
tescmd --format json --wake --fresh security status VIN
# → data.vehicle_state.locked == true

Set up a low-battery trigger (MCP)

Call trigger_create tool with: {"field": "BatteryLevel", "operator": "lt", "value": 20, "once": true}

Then periodically call trigger_poll to check for notifications.

Set up a geofence trigger (MCP)

{"field": "Location", "operator": "leave", "value": {"latitude": 37.7749, "longitude": -122.4194, "radius_m": 200}}

Fires when vehicle leaves the 200m radius around the specified point.