tescmd 0.3.1__tar.gz → 0.5.0__tar.gz

{tescmd-0.3.1 → tescmd-0.5.0}/.github/workflows/test.yml

@@ -8,6 +8,7 @@ on:
 jobs:
   test:
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     strategy:
       matrix:
         python-version: ["3.11", "3.12", "3.13"]
@@ -20,4 +21,4 @@ jobs:
       - run: ruff check src/ tests/
       - run: ruff format --check src/ tests/
       - run: mypy src/
-      - run: pytest
+      - run: pytest -v --timeout=30

{tescmd-0.3.1 → tescmd-0.5.0}/.gitignore

@@ -1,3 +1,4 @@
+.DS_Store
 __pycache__/
 *.pyc
 *.egg-info/

{tescmd-0.3.1 → tescmd-0.5.0}/CHANGELOG.md

@@ -5,6 +5,59 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-02-03
+
+### Changed
+
+- **Slim node capabilities** — node now advertises only `location.get` + `system.run` to the gateway (was 29 individual commands); all 34 handlers remain available via `system.run` meta-dispatch, reducing handshake payload and simplifying capability negotiation
+- **Explicit `send_connected()` lifecycle** — `node.connected` event is now sent explicitly after `connect_with_backoff()` and after successful reconnection, replacing the implicit first-frame trigger; CLI callers show a warning if the lifecycle event fails while the connection itself succeeded
+- **`send_connected()` returns bool** — callers can now detect lifecycle event failure; both `openclaw bridge` and `serve` commands display a yellow warning when the event fails to send
+- **Separated reconnect error handling** — `_maybe_reconnect()` now handles connection failure and lifecycle event failure independently; a failed `node.connected` no longer incorrectly doubles the reconnect backoff timer
+
+### Added
+
+- **`on_reconnect` gateway callback** — `GatewayClient` accepts an `on_reconnect` callback invoked after the receive loop successfully reconnects, ensuring `node.connected` is sent on every reconnection (not just the initial connect)
+- **`system.run` activity logging** — dispatcher logs the resolved inner method when routing through `system.run`, so operational logs show `system.run → door.lock` instead of just `system.run`
+
+### Fixed
+
+- **`send_connected()` false-positive logging** — no longer logs "Sent node.connected event" when the gateway is disconnected (the event was being silently dropped by `send_event()`)
+- **`OpenClawPipeline.dispatcher` typing** — changed from `Any` to `CommandDispatcher` for static analysis support
+
+## [0.4.0] - 2026-02-02
+
+### Added
+
+- **Unique app name generation** — setup wizard generates a `tescmd-<hex>` application name to prevent collisions on the Tesla Developer Portal; reused on re-runs unless `--force` is passed
+- **In-process KeyServer** — ephemeral HTTP server (`KeyServer`) serves the PEM public key on localhost during interactive setup so Tailscale Funnel can proxy it without writing to the serve directory
+- **Key mismatch warning** — setup wizard detects when the remote public key (GitHub Pages or Tailscale) differs from the local key and warns before Phase 2, so the user knows a redeploy is coming
+- **`fetch_tailscale_key_pem()`** — synchronous helper in the deploy module to fetch the raw PEM from a Tailscale Funnel URL, mirroring `github_pages.fetch_key_pem()`
+- **`TailscaleManager.start_proxy()`** — reverse-proxy mode (`tailscale serve --bg http://127.0.0.1:<port>`) for forwarding to a local HTTP server, distinct from the static-file `start_serve()`
+
+### Changed
+
+- **Setup phase reorder** — phases now run: keys → Fleet API registration → OAuth login → key enrollment (was: keys → enrollment → registration → OAuth); registration happens while credentials are fresh, enrollment is last so the user finishes in the Tesla app
+- **Credentials always required** — both Client ID and Client Secret are mandatory with retry loops (3 attempts each); empty input no longer silently skips setup
+- **Auto-save credentials** — `.env` file is written automatically after credential entry; removed the "Save to .env?" prompt
+- **`--force` regenerates app name** — passing `--force` to setup now generates a fresh `tescmd-<hex>` name instead of reusing the saved one
+- **Atomic Tailscale serve + Funnel** — `start_key_serving()` uses a single `tailscale serve --bg --funnel --set-path / <dir>` command instead of separate serve + funnel calls
+- **`TailscaleManager.start_serve()` API** — added `port` and `funnel` keyword arguments for configurable HTTPS port and inline Funnel enablement
+- **Enrollment messaging** — streamlined to focus on QR code scanning; removed duplicate URL display and the "Open in browser?" prompt (browser opens automatically)
+- **GitHub Pages note** — clarified that Tailscale is used alongside GitHub Pages for telemetry streaming, not as a replacement
+- **Funnel cleanup uses `stop_funnel()`** — finally block in `_interactive_setup` now calls the proper `TailscaleManager.stop_funnel()` method instead of the low-level `_run()` static method, preserving state tracking and idempotency
+
+### Fixed
+
+- **CLI module HTTP isolation** — moved direct `httpx.get()` call out of `setup.py` into `tailscale_serve.fetch_tailscale_key_pem()` to comply with single-responsibility layering (CLI handles args + output, deploy modules handle HTTP)
+
+## [0.3.2] - 2026-02-02
+
+### Fixed
+
+- **OAuth URL printed for manual fallback** — `login_flow()` now prints the authorization URL before opening the browser so users can copy-paste it when `webbrowser.open()` fails
+- **422 "already registered" treated as success** — `register_partner_account()` now treats HTTP 422 with "already been taken" as idempotent success instead of raising `AuthError`; re-running setup or `auth register` shows "Already registered — no action needed"
+- **GitHub key comparison on re-deploy** — `_deploy_key_github()` fetches the remote public key and compares it to the local key; if they match, deployment is skipped; if they differ, the user is prompted before overwriting
+
 ## [0.3.1] - 2026-02-02
 
 ### Added

tescmd-0.5.0/PKG-INFO

@@ -0,0 +1,301 @@
+Metadata-Version: 2.4
+Name: tescmd
+Version: 0.5.0
+Summary: A Python CLI for querying and controlling Tesla vehicles via the Fleet API
+Project-URL: Homepage, https://github.com/oceanswave/tescmd
+Project-URL: Repository, https://github.com/oceanswave/tescmd
+Project-URL: Issues, https://github.com/oceanswave/tescmd/issues
+Project-URL: Documentation, https://github.com/oceanswave/tescmd#readme
+Author: oceanswave
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,ev,fleet-api,tesla,vehicle
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: cryptography>=42.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: keyring>=25.0
+Requires-Dist: mcp>=1.0
+Requires-Dist: protobuf>=5.29
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: rich>=13.0
+Requires-Dist: starlette>=0.37
+Requires-Dist: textual>=1.0
+Requires-Dist: uvicorn>=0.30
+Requires-Dist: websockets>=14.0
+Provides-Extra: ble
+Requires-Dist: bleak>=0.22; extra == 'ble'
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: grpcio-tools>=1.68; extra == 'dev'
+Requires-Dist: mypy-protobuf>=3.6; extra == 'dev'
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.34; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="images/tescmd_header.jpeg" alt="tescmd — Python CLI for Tesla Fleet API" width="100%">
+</p>
+
+# tescmd
+
+<p align="center">
+  <a href="https://pypi.org/project/tescmd/"><img src="https://img.shields.io/pypi/v/tescmd" alt="PyPI"></a>
+  <a href="https://pypi.org/project/tescmd/"><img src="https://img.shields.io/pypi/pyversions/tescmd" alt="Python"></a>
+  <a href="https://github.com/oceanswave/tescmd/actions/workflows/test.yml"><img src="https://img.shields.io/github/actions/workflow/status/oceanswave/tescmd/test.yml?branch=main&label=build" alt="Build"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/oceanswave/tescmd" alt="License"></a>
+  <a href="https://github.com/oceanswave/tescmd/releases"><img src="https://img.shields.io/github/v/release/oceanswave/tescmd" alt="GitHub Release"></a>
+</p>
+
+<p align="center">
+  <strong>The complete Python CLI for Tesla's Fleet API — built for humans and AI agents alike.</strong>
+</p>
+
+<p align="center">
+  Check your battery. Lock your doors. Stream live telemetry. Let Claude control your car.<br>
+  Two commands to install. One wizard to set up. Every API endpoint at your fingertips.
+</p>
+
+---
+
+## Quick Start
+
+```bash
+pip install tescmd
+tescmd setup
+```
+
+The setup wizard handles everything — Tesla Developer app creation, key generation, public key hosting, Fleet API registration, OAuth2 authentication, and vehicle key enrollment. Then you're ready:
+
+```bash
+tescmd charge status               # Battery and charging state
+tescmd climate on --wake            # Turn on climate (wakes if asleep)
+tescmd security lock --wake         # Lock the car
+tescmd nav waypoints "Home" "Work"  # Multi-stop navigation
+tescmd serve 5YJ3...               # Launch the live dashboard
+```
+
+---
+
+## See It in Action
+
+### Live TUI Dashboard
+
+`tescmd serve` launches a full-screen terminal dashboard with real-time telemetry, MCP server status, tunnel info, and connection metrics — powered by Textual.
+
+<p align="center">
+  <img src="images/tescmd_serve.png" alt="tescmd serve — live TUI dashboard" width="700">
+</p>
+
+### AI Agent Integration
+
+Every command doubles as an MCP tool. Claude Desktop, Claude Code, and other agent frameworks can query your vehicle, send commands, and react to telemetry — all through structured JSON with built-in cost protection.
+
+<p align="center">
+  <img src="images/tescmd_mcp.png" alt="tescmd MCP server — Claude Desktop integration" width="700">
+</p>
+
+### Rich Terminal Output
+
+Formatted tables in your terminal, structured JSON when piped — tescmd auto-detects the right output for the context.
+
+<p align="center">
+  <img src="images/tescmd_waypoints.png" alt="tescmd nav waypoints" width="500">
+</p>
+
+---
+
+## What You Get
+
+### Query & Control
+
+Full read/write access to Tesla's Fleet API: battery, charge, climate, locks, trunks, windows, sentry, navigation, media, speed limits, PINs, Powerwalls, and more. Every read command is cached with smart TTLs — bots can call tescmd as often as they want and only pay for the first request.
+
+### Fleet Telemetry Streaming
+
+Your vehicle pushes data directly to your machine via Tailscale Funnel — no polling, no per-request charges. Choose from field presets (`driving`, `charging`, `all`) or subscribe to 120+ individual fields. Sessions produce a wide-format CSV log by default.
+
+```bash
+tescmd serve 5YJ3... --fields driving     # Speed, location, power
+tescmd serve 5YJ3... --fields all         # Everything
+```
+
+### MCP Server for AI Agents
+
+`tescmd serve` exposes every command as an MCP tool with OAuth 2.1 authentication. Agents get deterministic JSON output, meaningful exit codes, and a `--wake` opt-in flag so they never trigger billable wake calls by accident.
+
+### OpenClaw Bridge
+
+Stream filtered telemetry to an [OpenClaw](https://openclaw.ai/) Gateway with per-field delta and throttle filtering. Bots on the gateway can send commands back — lock doors, start charging, set climate — through bidirectional dispatch.
+
+### Trigger Subscriptions
+
+Register conditions on any telemetry field — battery below 20%, speed above 80, location enters a geofence — and get notified via OpenClaw push events or MCP polling. Supports one-shot and persistent modes with cooldown.
+
+### Signed Vehicle Commands
+
+tescmd implements the [Vehicle Command Protocol](https://github.com/teslamotors/vehicle-command) with ECDH session management and HMAC-SHA256 signing. Once your key is enrolled, commands are signed transparently — no agent-side crypto needed.
+
+---
+
+## Cost Protection Built In
+
+Tesla's Fleet API is pay-per-use. A naive polling script can generate hundreds of dollars in monthly charges from a single vehicle. tescmd implements four layers of defense:
+
+| Layer | What it does |
+|---|---|
+| **Tiered caching** | Specs cached 1h, fleet lists 5m, standard queries 1m, location 30s |
+| **Wake confirmation** | Prompts before billable wake calls; `--wake` flag for scripts |
+| **Smart wake state** | Tracks recent wake confirmations, skips redundant attempts |
+| **Write invalidation** | Write commands auto-invalidate the relevant cache scope |
+
+Streaming telemetry via `tescmd serve` replaces polling entirely — flat cost regardless of data volume. See [API Costs](docs/api-costs.md) for the full breakdown.
+
+---
+
+## Commands
+
+| Group | Description |
+|---|---|
+| `setup` | Interactive first-run wizard |
+| `auth` | OAuth2 login, logout, token management, export/import |
+| `vehicle` | State queries, wake, rename, telemetry streaming, fleet status |
+| `charge` | Charge control, scheduling, departure, fleet management |
+| `climate` | HVAC, seats, steering wheel, bioweapon defense, overheat protection |
+| `security` | Lock/unlock, sentry, valet, PINs, speed limits, remote start |
+| `trunk` | Trunk, frunk, windows, sunroof, tonneau |
+| `media` | Playback control, volume, favorites |
+| `nav` | Send destinations, GPS coordinates, multi-stop waypoints, HomeLink |
+| `software` | Update status, scheduling, cancellation |
+| `energy` | Powerwall status, backup reserve, storm mode, grid config, history |
+| `billing` | Supercharger billing history and invoices |
+| `user` | Account info, region, orders, feature flags |
+| `sharing` | Driver management, vehicle sharing invites |
+| `key` | Key generation, deployment, enrollment, validation |
+| `serve` | Combined MCP + telemetry + OpenClaw TUI dashboard |
+| `mcp` | Standalone MCP server |
+| `openclaw` | Standalone OpenClaw bridge |
+| `cache` | Cache status and management |
+| `raw` | Direct Fleet API endpoint access |
+
+Every command supports `--format json` for scripting and `--help` for detailed usage. See the [Command Reference](docs/commands.md) for the full list.
+
+---
+
+## Installation
+
+```bash
+pip install tescmd
+```
+
+**Requirements:** Python 3.11+ and a [Tesla account](https://www.tesla.com) with a linked vehicle or energy product.
+
+**Recommended:** [GitHub CLI](https://cli.github.com) (`gh`) for automated key hosting via GitHub Pages, or [Tailscale](https://tailscale.com) for zero-config key hosting and telemetry streaming via Funnel.
+
+<details>
+<summary>Install from source</summary>
+
+```bash
+git clone https://github.com/oceanswave/tescmd.git
+cd tescmd
+pip install -e ".[dev]"
+```
+
+</details>
+
+---
+
+## Configuration
+
+tescmd resolves settings from CLI flags, environment variables (`.env` files loaded automatically), and defaults — in that order.
+
+<details>
+<summary>Environment variables</summary>
+
+```dotenv
+TESLA_CLIENT_ID=your-client-id
+TESLA_CLIENT_SECRET=your-client-secret
+TESLA_VIN=5YJ3E1EA1NF000000
+TESLA_REGION=na                    # na, eu, cn
+
+# Display units (optional — defaults to US)
+TESLA_TEMP_UNIT=F                  # F or C
+TESLA_DISTANCE_UNIT=mi             # mi or km
+TESLA_PRESSURE_UNIT=psi            # psi or bar
+
+# Or switch everything at once:
+#   tescmd --units metric charge status
+```
+
+See [docs/commands.md](docs/commands.md) for the full environment variable reference.
+
+</details>
+
+<details>
+<summary>Token storage</summary>
+
+Tokens are stored in the OS keyring by default (macOS Keychain, GNOME Keyring, Windows Credential Manager). On headless systems, tescmd falls back to a file-based store with restricted permissions. Transfer tokens between machines with `tescmd auth export` and `tescmd auth import`.
+
+</details>
+
+---
+
+## Documentation
+
+| | |
+|---|---|
+| [Setup Guide](docs/setup.md) | Step-by-step walkthrough of `tescmd setup` |
+| [Command Reference](docs/commands.md) | Detailed usage for every command |
+| [API Costs](docs/api-costs.md) | Cost breakdown, savings calculations, streaming comparison |
+| [Bot Integration](docs/bot-integration.md) | JSON schema, exit codes, headless auth |
+| [OpenClaw Bridge](docs/openclaw.md) | Gateway protocol, bidirectional commands, triggers, geofencing |
+| [MCP Server](docs/mcp.md) | Tool reference, OAuth 2.1, custom tools, trigger polling |
+| [Vehicle Command Protocol](docs/vehicle-command-protocol.md) | ECDH sessions and signed commands |
+| [Authentication](docs/authentication.md) | OAuth2 PKCE flow, token storage, scopes |
+| [Architecture](docs/architecture.md) | Layered design, module responsibilities |
+| [FAQ](docs/faq.md) | Common questions about costs, hosting, and configuration |
+| [Development](docs/development.md) | Contributing, testing, linting |
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/oceanswave/tescmd.git && cd tescmd
+pip install -e ".[dev]"
+pytest                             # 1600+ tests
+ruff check src/ tests/ && mypy src/
+```
+
+---
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for release history.
+
+## License
+
+MIT
+
+<p align="center">
+  <img src="images/tescmd_logo.jpeg" alt="tescmd logo" width="300">
+</p>

tescmd-0.5.0/README.md

@@ -0,0 +1,247 @@
+<p align="center">
+  <img src="images/tescmd_header.jpeg" alt="tescmd — Python CLI for Tesla Fleet API" width="100%">
+</p>
+
+# tescmd
+
+<p align="center">
+  <a href="https://pypi.org/project/tescmd/"><img src="https://img.shields.io/pypi/v/tescmd" alt="PyPI"></a>
+  <a href="https://pypi.org/project/tescmd/"><img src="https://img.shields.io/pypi/pyversions/tescmd" alt="Python"></a>
+  <a href="https://github.com/oceanswave/tescmd/actions/workflows/test.yml"><img src="https://img.shields.io/github/actions/workflow/status/oceanswave/tescmd/test.yml?branch=main&label=build" alt="Build"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/oceanswave/tescmd" alt="License"></a>
+  <a href="https://github.com/oceanswave/tescmd/releases"><img src="https://img.shields.io/github/v/release/oceanswave/tescmd" alt="GitHub Release"></a>
+</p>
+
+<p align="center">
+  <strong>The complete Python CLI for Tesla's Fleet API — built for humans and AI agents alike.</strong>
+</p>
+
+<p align="center">
+  Check your battery. Lock your doors. Stream live telemetry. Let Claude control your car.<br>
+  Two commands to install. One wizard to set up. Every API endpoint at your fingertips.
+</p>
+
+---
+
+## Quick Start
+
+```bash
+pip install tescmd
+tescmd setup
+```
+
+The setup wizard handles everything — Tesla Developer app creation, key generation, public key hosting, Fleet API registration, OAuth2 authentication, and vehicle key enrollment. Then you're ready:
+
+```bash
+tescmd charge status               # Battery and charging state
+tescmd climate on --wake            # Turn on climate (wakes if asleep)
+tescmd security lock --wake         # Lock the car
+tescmd nav waypoints "Home" "Work"  # Multi-stop navigation
+tescmd serve 5YJ3...               # Launch the live dashboard
+```
+
+---
+
+## See It in Action
+
+### Live TUI Dashboard
+
+`tescmd serve` launches a full-screen terminal dashboard with real-time telemetry, MCP server status, tunnel info, and connection metrics — powered by Textual.
+
+<p align="center">
+  <img src="images/tescmd_serve.png" alt="tescmd serve — live TUI dashboard" width="700">
+</p>
+
+### AI Agent Integration
+
+Every command doubles as an MCP tool. Claude Desktop, Claude Code, and other agent frameworks can query your vehicle, send commands, and react to telemetry — all through structured JSON with built-in cost protection.
+
+<p align="center">
+  <img src="images/tescmd_mcp.png" alt="tescmd MCP server — Claude Desktop integration" width="700">
+</p>
+
+### Rich Terminal Output
+
+Formatted tables in your terminal, structured JSON when piped — tescmd auto-detects the right output for the context.
+
+<p align="center">
+  <img src="images/tescmd_waypoints.png" alt="tescmd nav waypoints" width="500">
+</p>
+
+---
+
+## What You Get
+
+### Query & Control
+
+Full read/write access to Tesla's Fleet API: battery, charge, climate, locks, trunks, windows, sentry, navigation, media, speed limits, PINs, Powerwalls, and more. Every read command is cached with smart TTLs — bots can call tescmd as often as they want and only pay for the first request.
+
+### Fleet Telemetry Streaming
+
+Your vehicle pushes data directly to your machine via Tailscale Funnel — no polling, no per-request charges. Choose from field presets (`driving`, `charging`, `all`) or subscribe to 120+ individual fields. Sessions produce a wide-format CSV log by default.
+
+```bash
+tescmd serve 5YJ3... --fields driving     # Speed, location, power
+tescmd serve 5YJ3... --fields all         # Everything
+```
+
+### MCP Server for AI Agents
+
+`tescmd serve` exposes every command as an MCP tool with OAuth 2.1 authentication. Agents get deterministic JSON output, meaningful exit codes, and a `--wake` opt-in flag so they never trigger billable wake calls by accident.
+
+### OpenClaw Bridge
+
+Stream filtered telemetry to an [OpenClaw](https://openclaw.ai/) Gateway with per-field delta and throttle filtering. Bots on the gateway can send commands back — lock doors, start charging, set climate — through bidirectional dispatch.
+
+### Trigger Subscriptions
+
+Register conditions on any telemetry field — battery below 20%, speed above 80, location enters a geofence — and get notified via OpenClaw push events or MCP polling. Supports one-shot and persistent modes with cooldown.
+
+### Signed Vehicle Commands
+
+tescmd implements the [Vehicle Command Protocol](https://github.com/teslamotors/vehicle-command) with ECDH session management and HMAC-SHA256 signing. Once your key is enrolled, commands are signed transparently — no agent-side crypto needed.
+
+---
+
+## Cost Protection Built In
+
+Tesla's Fleet API is pay-per-use. A naive polling script can generate hundreds of dollars in monthly charges from a single vehicle. tescmd implements four layers of defense:
+
+| Layer | What it does |
+|---|---|
+| **Tiered caching** | Specs cached 1h, fleet lists 5m, standard queries 1m, location 30s |
+| **Wake confirmation** | Prompts before billable wake calls; `--wake` flag for scripts |
+| **Smart wake state** | Tracks recent wake confirmations, skips redundant attempts |
+| **Write invalidation** | Write commands auto-invalidate the relevant cache scope |
+
+Streaming telemetry via `tescmd serve` replaces polling entirely — flat cost regardless of data volume. See [API Costs](docs/api-costs.md) for the full breakdown.
+
+---
+
+## Commands
+
+| Group | Description |
+|---|---|
+| `setup` | Interactive first-run wizard |
+| `auth` | OAuth2 login, logout, token management, export/import |
+| `vehicle` | State queries, wake, rename, telemetry streaming, fleet status |
+| `charge` | Charge control, scheduling, departure, fleet management |
+| `climate` | HVAC, seats, steering wheel, bioweapon defense, overheat protection |
+| `security` | Lock/unlock, sentry, valet, PINs, speed limits, remote start |
+| `trunk` | Trunk, frunk, windows, sunroof, tonneau |
+| `media` | Playback control, volume, favorites |
+| `nav` | Send destinations, GPS coordinates, multi-stop waypoints, HomeLink |
+| `software` | Update status, scheduling, cancellation |
+| `energy` | Powerwall status, backup reserve, storm mode, grid config, history |
+| `billing` | Supercharger billing history and invoices |
+| `user` | Account info, region, orders, feature flags |
+| `sharing` | Driver management, vehicle sharing invites |
+| `key` | Key generation, deployment, enrollment, validation |
+| `serve` | Combined MCP + telemetry + OpenClaw TUI dashboard |
+| `mcp` | Standalone MCP server |
+| `openclaw` | Standalone OpenClaw bridge |
+| `cache` | Cache status and management |
+| `raw` | Direct Fleet API endpoint access |
+
+Every command supports `--format json` for scripting and `--help` for detailed usage. See the [Command Reference](docs/commands.md) for the full list.
+
+---
+
+## Installation
+
+```bash
+pip install tescmd
+```
+
+**Requirements:** Python 3.11+ and a [Tesla account](https://www.tesla.com) with a linked vehicle or energy product.
+
+**Recommended:** [GitHub CLI](https://cli.github.com) (`gh`) for automated key hosting via GitHub Pages, or [Tailscale](https://tailscale.com) for zero-config key hosting and telemetry streaming via Funnel.
+
+<details>
+<summary>Install from source</summary>
+
+```bash
+git clone https://github.com/oceanswave/tescmd.git
+cd tescmd
+pip install -e ".[dev]"
+```
+
+</details>
+
+---
+
+## Configuration
+
+tescmd resolves settings from CLI flags, environment variables (`.env` files loaded automatically), and defaults — in that order.
+
+<details>
+<summary>Environment variables</summary>
+
+```dotenv
+TESLA_CLIENT_ID=your-client-id
+TESLA_CLIENT_SECRET=your-client-secret
+TESLA_VIN=5YJ3E1EA1NF000000
+TESLA_REGION=na                    # na, eu, cn
+
+# Display units (optional — defaults to US)
+TESLA_TEMP_UNIT=F                  # F or C
+TESLA_DISTANCE_UNIT=mi             # mi or km
+TESLA_PRESSURE_UNIT=psi            # psi or bar
+
+# Or switch everything at once:
+#   tescmd --units metric charge status
+```
+
+See [docs/commands.md](docs/commands.md) for the full environment variable reference.
+
+</details>
+
+<details>
+<summary>Token storage</summary>
+
+Tokens are stored in the OS keyring by default (macOS Keychain, GNOME Keyring, Windows Credential Manager). On headless systems, tescmd falls back to a file-based store with restricted permissions. Transfer tokens between machines with `tescmd auth export` and `tescmd auth import`.
+
+</details>
+
+---
+
+## Documentation
+
+| | |
+|---|---|
+| [Setup Guide](docs/setup.md) | Step-by-step walkthrough of `tescmd setup` |
+| [Command Reference](docs/commands.md) | Detailed usage for every command |
+| [API Costs](docs/api-costs.md) | Cost breakdown, savings calculations, streaming comparison |
+| [Bot Integration](docs/bot-integration.md) | JSON schema, exit codes, headless auth |
+| [OpenClaw Bridge](docs/openclaw.md) | Gateway protocol, bidirectional commands, triggers, geofencing |
+| [MCP Server](docs/mcp.md) | Tool reference, OAuth 2.1, custom tools, trigger polling |
+| [Vehicle Command Protocol](docs/vehicle-command-protocol.md) | ECDH sessions and signed commands |
+| [Authentication](docs/authentication.md) | OAuth2 PKCE flow, token storage, scopes |
+| [Architecture](docs/architecture.md) | Layered design, module responsibilities |
+| [FAQ](docs/faq.md) | Common questions about costs, hosting, and configuration |
+| [Development](docs/development.md) | Contributing, testing, linting |
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/oceanswave/tescmd.git && cd tescmd
+pip install -e ".[dev]"
+pytest                             # 1600+ tests
+ruff check src/ tests/ && mypy src/
+```
+
+---
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for release history.
+
+## License
+
+MIT
+
+<p align="center">
+  <img src="images/tescmd_logo.jpeg" alt="tescmd logo" width="300">
+</p>

{tescmd-0.3.1 → tescmd-0.5.0}/docs/commands.md

@@ -364,10 +364,10 @@ ACTION REQUIRED: Add virtual key in the Tesla app
 
   Enrollment URL: https://tesla.com/_ak/yourdomain.github.io
 
-  1. Open the URL above on your phone
-  2. Tap Finish Setup on the web page
-  3. The Tesla app will show an Add Virtual Key prompt
-  4. Approve it
+  1. Scan the QR code on the page above with your phone
+  2. The Tesla app will show an Add Virtual Key prompt
+  3. Approve it
+
 ```
 
 **JSON mode:** Returns a single envelope with `"status": "ready"`, `enroll_url`, and instructions.

{tescmd-0.3.1 → tescmd-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tescmd"
-version = "0.3.1"
+version = "0.5.0"
 description = "A Python CLI for querying and controlling Tesla vehicles via the Fleet API"
 readme = "README.md"
 license = "MIT"
@@ -49,6 +49,7 @@ dev = [
     "pytest-httpx>=0.34",
     "pytest-xdist>=3.0",
     "pytest-cov>=5.0",
+    "pytest-timeout>=2.3",
     "ruff>=0.8",
     "mypy>=1.13",
     "mypy-protobuf>=3.6",
@@ -88,6 +89,7 @@ plugins = ["pydantic.mypy"]
 testpaths = ["tests"]
 asyncio_mode = "auto"
 addopts = "-n auto -m 'not e2e'"
+timeout = 30
 markers = [
     "e2e: End-to-end smoke tests against the live Tesla Fleet API (requires TESLA_ACCESS_TOKEN)",
 ]