tescmd 0.1.2__tar.gz → 0.2.0__tar.gz

tescmd-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,19 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

tescmd-0.2.0/.github/workflows/test.yml

@@ -0,0 +1,23 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev,telemetry]"
+      - run: ruff check src/ tests/
+      - run: ruff format --check src/ tests/
+      - run: mypy src/
+      - run: pytest

{tescmd-0.1.2 → tescmd-0.2.0}/CHANGELOG.md

@@ -5,6 +5,36 @@ 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.2.0] - 2026-01-31
+
+### Added
+
+- **Fleet Telemetry Streaming** — `tescmd vehicle telemetry stream [VIN]` starts a local WebSocket server, exposes it via Tailscale Funnel, configures the vehicle to push real-time telemetry, and displays it in an interactive Rich Live dashboard (TTY) or JSONL stream (piped)
+- **Telemetry dashboard** — Rich Live TUI with field name, value, and last-update columns; unit conversion (°F/°C, mi/km, psi/bar); connection status; frame counter; uptime display
+- **Protobuf telemetry decoder** — official Tesla protobuf definitions (`vehicle_data`, `vehicle_alert`, `vehicle_error`, `vehicle_metric`, `vehicle_connectivity`) for fully typed telemetry message parsing
+- **FlatBuffer telemetry support** — `flatbuf.py` parser for Tesla's FlatBuffer-encoded telemetry payloads alongside protobuf
+- **Field presets** — `--fields` option accepts preset names (`default`, `driving`, `charging`, `climate`, `all`) or comma-separated field names with 120+ registered telemetry fields
+- **Interval override** — `--interval` option overrides the polling interval for all fields
+- **Tailscale Funnel integration** — automatic Funnel start/stop with cert retrieval for Fleet Telemetry HTTPS requirement
+- **JSONL output** — piped mode emits one JSON line per telemetry frame for scripting and log ingestion
+- **TunnelError hierarchy** — `TunnelError` parent with `TailscaleError` subtype; actionable install/setup guidance
+- **Optional dependency group** — `pip install tescmd[telemetry]` adds `websockets>=14.0`
+- **Tailscale key hosting** — `tescmd key deploy --method tailscale` hosts the public key via Tailscale Funnel at `https://<machine>.tailnet.ts.net/.well-known/appspecific/com.tesla.3p.public-key.pem`; auto-detected as second priority after GitHub Pages
+- **Key hosting priority chain** — setup wizard and `key deploy` auto-detect the best hosting method: GitHub Pages → Tailscale Funnel → manual; `--method` flag overrides auto-detection
+- **`TESLA_HOSTING_METHOD` setting** — persists the chosen key hosting method (`github`, `tailscale`) across sessions
+- **Schnorr signature support** — `crypto/schnorr.py` for Schnorr-based authentication challenges used in telemetry server handshake
+- **`auth import` command** — `tescmd auth import < tokens.json` imports tokens from a JSON file for headless/CI environments
+- **Setup guide** — `docs/setup.md` with step-by-step walkthrough of all 7 setup phases
+- **FAQ** — `docs/faq.md` covering common questions about tescmd, costs, hosting, and configuration
+- **CI/CD workflows** — GitHub Actions for test-on-push (Python 3.11–3.13) and publish-to-PyPI-on-release via trusted publishing
+- **README badges** — PyPI version, Python versions, CI build status, license, and GitHub release badges
+- **E2E smoke tests** — `tests/cli/test_e2e_smoke.py` provides 179 pytest-based end-to-end tests covering every CLI command against the live Fleet API, with JSON envelope validation and save/restore for write commands (`pytest -m e2e`)
+
+### Fixed
+
+- Fixed telemetry dashboard uptime counter not incrementing
+- Improved tunnel start/stop success messages for clarity
+
 ## [0.1.2] - 2025-01-31
 
 ### Added
@@ -46,7 +76,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **`command_protocol` setting** — `auto` (default), `signed`, or `unsigned` to control command routing; configurable via `TESLA_COMMAND_PROTOCOL` env var
 - **Enrollment step in setup wizard** — full-tier setup now offers to enroll the key on a vehicle after key generation
 - **Friendly command output** — all vehicle commands now display descriptive success messages (e.g. "Climate control turned on.", "Doors locked.") instead of bare "OK"
-- **E2E test script** — `scripts/e2e_test.py` provides interactive end-to-end command testing against a live vehicle with per-command confirmation, category filtering, and destructive-command skipping
+- **E2E smoke tests** — `tests/cli/test_e2e_smoke.py` provides 179 pytest-based end-to-end tests covering every CLI command against the live Fleet API, with JSON envelope validation and save/restore for write commands (`pytest -m e2e`)
 
 ## [0.1.0]
 

{tescmd-0.1.2 → tescmd-0.2.0}/CLAUDE.md

@@ -4,7 +4,7 @@
 
 **tescmd** is a Python CLI application that queries data from and sends commands to Tesla vehicles via the [Tesla Fleet API](https://developer.tesla.com/docs/fleet-api). The current implementation covers OAuth2 authentication, key management, vehicle state queries (battery, location, climate, drive state, tire pressure, trunks, and more), and both human-friendly (Rich TUI) and machine-friendly (JSON) output with configurable display units.
 
-**Current scope:** auth, vehicle queries, vehicle commands (charge, climate, security, trunk, media, nav, software), energy product management (including telemetry), Supercharger charging history and invoices, user account info, vehicle sharing, partner account endpoints (public key, fleet telemetry errors), key management with enrollment and unenrollment, Vehicle Command Protocol (ECDH sessions + HMAC-signed protobuf commands), tier enforcement, initial setup, response caching with cost-aware wake confirmation, Fleet Telemetry configuration management (create/delete/errors), configuration status dashboard, and GitHub Pages key deployment.
+**Current scope:** auth, vehicle queries, vehicle commands (charge, climate, security, trunk, media, nav, software), energy product management (including telemetry), Supercharger charging history and invoices, user account info, vehicle sharing, partner account endpoints (public key, fleet telemetry errors), key management with enrollment and unenrollment, Vehicle Command Protocol (ECDH sessions + HMAC-signed protobuf commands), tier enforcement, initial setup, response caching with cost-aware wake confirmation, Fleet Telemetry configuration management (create/delete/errors), real-time telemetry streaming via Tailscale Funnel, configuration status dashboard, key deployment via GitHub Pages or Tailscale Funnel (auto-detected priority chain).
 
 ## Tech Stack
 
@@ -17,6 +17,7 @@
 - **protobuf** — protobuf serialization for Vehicle Command Protocol messages
 - **keyring** — OS-level credential storage for tokens
 - **python-dotenv** — `.env` file loading
+- **websockets** — async WebSocket server for telemetry streaming (optional: `[telemetry]`)
 - **bleak** — BLE communication for key enrollment (optional; portal enrollment is primary)
 
 ## Project Structure
@@ -38,7 +39,7 @@ src/tescmd/
 │   ├── security.py        # security status, lock, auto-secure, unlock, sentry, valet, valet-reset, remote-start, flash, honk, boombox, pin-to-drive, pin-reset, pin-clear-admin, speed-limit, speed-clear, speed-clear-admin, guest-mode, erase-data
 │   ├── status.py          # status (show config, auth, and cache status)
 │   ├── trunk.py           # trunk open, close, frunk, window, sunroof, tonneau-open/close/stop
-│   ├── vehicle.py         # vehicle list, get, info, data, location, wake, rename, mobile-access, nearby-chargers, alerts, release-notes, service, drivers, calendar, subscriptions, upgrades, options, specs, warranty, fleet-status, low-power, accessory-power; telemetry subgroup: config, create, delete, errors
+│   ├── vehicle.py         # vehicle list, get, info, data, location, wake, rename, mobile-access, nearby-chargers, alerts, release-notes, service, drivers, calendar, subscriptions, upgrades, options, specs, warranty, fleet-status, low-power, accessory-power; telemetry subgroup: config, create, delete, errors, stream
 │   ├── media.py           # media play-pause, next/prev track, next/prev fav, volume
 │   ├── nav.py             # nav send, gps, supercharger, homelink, waypoints
 │   ├── partner.py         # partner public-key, telemetry-error-vins, telemetry-errors
@@ -60,7 +61,7 @@ src/tescmd/
 │   ├── partner.py         # PartnerAPI (public key, fleet telemetry errors — requires partner token)
 │   ├── sharing.py         # SharingAPI (driver and invite management)
 │   ├── user.py            # UserAPI (account info, region, orders, features)
-│   └── errors.py          # API error types (incl. TierError, SessionError, KeyNotEnrolledError)
+│   └── errors.py          # API error types (incl. TierError, SessionError, KeyNotEnrolledError, TunnelError, TailscaleError)
 ├── cache/                 # Response caching
 │   ├── __init__.py        # Re-exports ResponseCache, generic_cache_key
 │   ├── response_cache.py  # ResponseCache (file-based JSON with TTL, generic cache)
@@ -99,11 +100,19 @@ src/tescmd/
 │   ├── formatter.py       # OutputFormatter (auto-detect TTY vs pipe)
 │   ├── rich_output.py     # Rich tables, panels, status displays, DisplayUnits
 │   └── json_output.py     # Structured JSON output
+├── telemetry/             # Fleet Telemetry streaming
+│   ├── __init__.py        # Re-exports
+│   ├── tailscale.py       # TailscaleManager: check presence, start/stop funnel, get cert, serve/funnel for key hosting
+│   ├── server.py          # TelemetryServer: async WebSocket server
+│   ├── decoder.py         # TelemetryDecoder: protobuf to TelemetryFrame dataclass
+│   ├── fields.py          # Field name registry (120+ fields) and preset configs
+│   └── dashboard.py       # TelemetryDashboard: Rich Live TUI renderer
 ├── ble/                   # BLE communication (stub — enrollment not yet wired)
 │   └── __init__.py
 ├── deploy/                # Key deployment helpers
 │   ├── __init__.py
-│   └── github_pages.py    # GitHub Pages deployment for public key hosting
+│   ├── github_pages.py    # GitHub Pages deployment for public key hosting
+│   └── tailscale_serve.py # Tailscale Funnel deployment for public key hosting
 ├── config/                # Configuration (stub — settings in models/config.py)
 │   └── __init__.py
 └── _internal/             # Shared utilities
@@ -117,6 +126,15 @@ spec/
 
 scripts/
 └── validate_fleet_api.py      # Spec-driven API coverage validator (AST-based)
+
+tests/telemetry/
+├── conftest.py            # Shared fixtures (cli_env)
+├── test_tailscale.py      # Mocked subprocess tests for TailscaleManager
+├── test_decoder.py        # Protobuf decode with crafted bytes
+├── test_fields.py         # Field registry and preset resolution
+├── test_server.py         # WebSocket client integration tests
+├── test_dashboard.py      # Rich Live render output verification
+└── test_stream_cmd.py     # CLI integration tests for stream command
 ```
 
 ### Key Models (`models/vehicle.py`)
@@ -276,11 +294,12 @@ The `[R] Retry` option allows users to wake the vehicle for free via the Tesla m
 
 ## Testing
 
-- **pytest** + **pytest-asyncio** + **pytest-httpx**
+- **pytest** + **pytest-asyncio** + **pytest-httpx** + **pytest-xdist**
+- Tests run in parallel by default (`addopts = "-n auto"` in `pyproject.toml`). Always use `pytest` (not `pytest -n 1`) unless debugging a specific isolation issue.
 - Test files mirror source: `tests/cli/test_auth.py`, `tests/api/test_client.py`, etc.
 - Use `pytest-httpx` to mock HTTP responses (no live API calls in tests)
 - Async tests use `@pytest.mark.asyncio`
-- Current count: ~910 tests
+- Current count: ~1118 tests
 
 ## Linting & Formatting
 
@@ -308,6 +327,8 @@ The `[R] Retry` option allows users to wake the vehicle for free via the Tesla m
 16. **Key enrollment** — `tescmd key enroll <VIN>` sends the public key to the vehicle via the unsigned `add_key_request` endpoint, then guides the user through Tesla app approval with an interactive prompt or `--wait` auto-polling.
 17. **Cross-platform token storage** — `TokenStore` uses a `_TokenBackend` protocol with two implementations: `_KeyringBackend` (OS keyring) and `_FileBackend` (JSON file with atomic writes and restricted permissions). Backend selection: explicit `TESLA_TOKEN_FILE` → file; keyring probe success → keyring; probe failure → file fallback at `{config_dir}/tokens.json` with one-time warning.
 18. **Cross-platform file permissions** — `_internal/permissions.py` provides `secure_file()` which uses `chmod 0600` on Unix and `icacls` on Windows. Used by both token storage and key generation. Failures are silently ignored (Docker volumes, network mounts, etc.).
+19. **Fleet Telemetry streaming** — `tescmd vehicle telemetry stream [VIN]` starts a local WebSocket server, exposes it via Tailscale Funnel, configures the vehicle's fleet telemetry config to push to it, and displays data in a Rich Live dashboard (TTY) or JSONL stream (piped). Tesla requires the telemetry config hostname to match the partner-registered domain — the stream command automatically re-registers the partner domain to match the tunnel hostname, then restores the original domain on exit (try/finally). The `telemetry/` package has five modules: `TailscaleManager` (subprocess-based — Funnel has no Python API), `TelemetryServer` (websockets async server), `TelemetryDecoder` (reuses `protocol/protobuf/messages._decode_field` for wire-format parsing), `fields.py` (120+ field name registry with presets), and `TelemetryDashboard` (Rich Live TUI with unit conversion via `DisplayUnits`). Port is randomly selected from ephemeral range (49152–65535). Cleanup is guaranteed via try/finally (partner domain restore → telemetry config delete → funnel stop → server stop). Optional dependency: `pip install tescmd[telemetry]` adds `websockets>=14.0`.
+20. **Key hosting priority chain** — `tescmd setup` and `tescmd key deploy` auto-detect the best hosting method for the public key: GitHub Pages (always-on, free) → Tailscale Funnel (requires machine running) → manual. The `--method` flag on `key deploy` overrides auto-detection. `TESLA_HOSTING_METHOD` persists the choice. Tailscale key hosting uses path-based `tailscale serve --bg --set-path /.well-known/ <dir>` + `tailscale funnel --bg 443`. Note: Tailscale key hosting may conflict with telemetry streaming's funnel usage — run `tescmd key deploy --method tailscale` to re-enable after streaming.
 
 ## Environment Variables
 
@@ -333,6 +354,7 @@ The `[R] Retry` option allows users to wake the vehicle for free via the Tesla m
 | `TESLA_DOMAIN` | Domain for Fleet API key hosting | — |
 | `TESLA_SETUP_TIER` | Setup tier (`readonly` or `full`) | — |
 | `TESLA_GITHUB_REPO` | GitHub repo for key deployment (e.g., `user/user.github.io`) | — |
+| `TESLA_HOSTING_METHOD` | Key hosting method (`github`, `tailscale`, or unset for manual) | — |
 
 All variables can also be set in a `.env` file in the working directory or `$TESLA_CONFIG_DIR/.env`.
 
@@ -349,7 +371,6 @@ All variables can also be set in a `.env` file in the working directory or `$TES
 | `--no-cache` / `--fresh` | Global | Bypass response cache for this invocation |
 | `--wake` | Global | Auto-wake vehicle without confirmation (billable) |
 | `--units {us,metric}` | Global | Display units preset (us: °F/mi/psi, metric: °C/km/bar) |
-
 All global flags can be specified at the root level (`tescmd --wake charge status`) or after the subcommand (`tescmd charge status --wake`).
 
 ## API Coverage Validation
@@ -398,4 +419,12 @@ tescmd cache clear --scope account  # Clear account-level entries
 tescmd charge status             # Uses cache, prompts before wake
 tescmd charge status --fresh     # Bypasses cache, still prompts before wake
 tescmd charge status --wake      # Auto-wakes without prompting (billable)
+
+# Telemetry streaming (requires: pip install tescmd[telemetry] + Tailscale)
+tescmd vehicle telemetry stream VIN                     # Rich Live dashboard
+tescmd vehicle telemetry stream VIN --fields driving    # Driving preset
+tescmd vehicle telemetry stream VIN --fields charging   # Charging preset
+tescmd vehicle telemetry stream VIN --interval 5        # Override all field intervals to 5s
+tescmd vehicle telemetry stream VIN --format json       # JSONL output for scripting
+pytest tests/telemetry/                                 # Telemetry-specific tests
 ```

{tescmd-0.1.2 → tescmd-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tescmd
-Version: 0.1.2
+Version: 0.2.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
@@ -41,15 +41,20 @@ 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-xdist>=3.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: telemetry
+Requires-Dist: websockets>=14.0; extra == 'telemetry'
 Description-Content-Type: text/markdown
 
 # tescmd
 
-<!-- [![PyPI](https://img.shields.io/pypi/v/tescmd)](https://pypi.org/project/tescmd/) -->
-<!-- [![Python](https://img.shields.io/pypi/pyversions/tescmd)](https://pypi.org/project/tescmd/) -->
+[![PyPI](https://img.shields.io/pypi/v/tescmd)](https://pypi.org/project/tescmd/)
+[![Python](https://img.shields.io/pypi/pyversions/tescmd)](https://pypi.org/project/tescmd/)
+[![Build](https://img.shields.io/github/actions/workflow/status/oceanswave/tescmd/test.yml?branch=main&label=build)](https://github.com/oceanswave/tescmd/actions/workflows/test.yml)
 [![License](https://img.shields.io/github/license/oceanswave/tescmd)](LICENSE)
+[![GitHub Release](https://img.shields.io/github/v/release/oceanswave/tescmd)](https://github.com/oceanswave/tescmd/releases)
 
 A Python CLI for querying and controlling Tesla vehicles via the Fleet API — built for both human operators and AI agents.
 
@@ -68,7 +73,7 @@ tescmd is designed to work as a tool that AI agents can invoke directly. Platfor
 - **Tier enforcement** — readonly tier blocks write commands with clear guidance to upgrade
 - **Energy products** — Powerwall live status, site info, backup reserve, operation mode, storm mode, time-of-use settings, charging history, calendar history, grid import/export
 - **User & sharing** — account info, region, orders, feature flags, driver management, vehicle sharing invites
-- **Fleet Telemetry awareness** — setup wizard highlights Fleet Telemetry streaming for up to 97% API cost reduction
+- **Fleet Telemetry streaming** — `tescmd vehicle telemetry stream` starts a real-time dashboard with push-based data from your vehicle via Tailscale Funnel — no polling, 99%+ cost reduction
 - **Universal response caching** — all read commands are cached with tiered TTLs (1h for specs/warranty, 5m for fleet lists, 1m standard, 30s for location-dependent); bots can call tescmd as often as needed — within the TTL window, responses are instant and free
 - **Cost-aware wake** — prompts before sending billable wake API calls; `--wake` flag for scripts that accept the cost
 - **Guided OAuth2 setup** — `tescmd auth login` walks you through browser-based authentication with PKCE
@@ -83,40 +88,23 @@ tescmd is designed to work as a tool that AI agents can invoke directly. Platfor
 
 ```bash
 pip install tescmd
-
-# First-time setup (interactive wizard)
 tescmd setup
+```
 
-# Authenticate (opens browser)
-tescmd auth login
-
-# List your vehicles
-tescmd vehicle list
-
-# Get full vehicle data snapshot
-tescmd vehicle info
-
-# Check charge status (uses cache — second call is instant)
-tescmd charge status
-
-# Start charging (auto-invalidates cache)
-tescmd charge start --wake
-
-# Climate control
-tescmd climate on --wake
-tescmd climate set 72
-
-# Lock the car
-tescmd security lock --wake
+That's it. The interactive setup wizard walks you through everything: creating a Tesla Developer app, generating an EC key pair, hosting the public key (via GitHub Pages or Tailscale Funnel), registering with the Fleet API, authenticating via OAuth2, and enrolling your key on a vehicle. Each step checks prerequisites and offers remediation if something is missing.
 
-# Enroll your key on a vehicle (required for signed commands)
-tescmd key enroll 5YJ3E1EA1NF000000
+After setup completes, you can start using commands:
 
-# Cache management
-tescmd cache status
-tescmd cache clear
+```bash
+tescmd charge status               # Check battery and charging state
+tescmd vehicle info                 # Full vehicle data snapshot
+tescmd climate on --wake            # Turn on climate (wakes vehicle if asleep)
+tescmd security lock --wake         # Lock the car
+tescmd vehicle telemetry stream     # Real-time telemetry dashboard
 ```
 
+Every read command is cached — repeat calls within the TTL window are instant and free.
+
 ## Prerequisites
 
 The following tools should be installed and authenticated before running `tescmd setup`:
@@ -125,9 +113,11 @@ The following tools should be installed and authenticated before running `tescmd
 |------|----------|---------|------|
 | **Git** | Yes | Version control, repo management | N/A |
 | **GitHub CLI** (`gh`) | Recommended | Auto-creates `*.github.io` domain for key hosting | `gh auth login` |
-| **Tailscale** | Optional | Secure remote access to vehicles via Fleet Telemetry | `tailscale login` |
+| **Tailscale** | Optional | Key hosting via Funnel + Fleet Telemetry streaming | `tailscale login` |
+
+Without the GitHub CLI, `tescmd setup` will try Tailscale Funnel for key hosting (requires Funnel enabled in your tailnet ACL). Without either, you'll need to manually host your public key at the Tesla-required `.well-known` path on your own domain.
 
-Without the GitHub CLI, you'll need to manually host your public key at the Tesla-required `.well-known` path on your own domain. Tailscale is only needed if you plan to use Fleet Telemetry streaming for reduced API costs.
+For telemetry streaming, you need **Tailscale** with Funnel enabled.
 
 ## Installation
 
@@ -210,7 +200,7 @@ Check which backend is active with `tescmd status` — the output includes a `To
 |---|---|---|
 | `setup` | *(interactive wizard)* | First-run configuration: client ID, secret, region, domain, key enrollment |
 | `auth` | `login`, `logout`, `status`, `refresh`, `register`, `export`, `import` | OAuth2 authentication lifecycle |
-| `vehicle` | `list`, `get`, `info`, `data`, `location`, `wake`, `rename`, `mobile-access`, `nearby-chargers`, `alerts`, `release-notes`, `service`, `drivers`, `calendar`, `subscriptions`, `upgrades`, `options`, `specs`, `warranty`, `fleet-status`, `low-power`, `accessory-power`, `telemetry {config,create,delete,errors}` | Vehicle discovery, state queries, fleet telemetry, power management |
+| `vehicle` | `list`, `get`, `info`, `data`, `location`, `wake`, `rename`, `mobile-access`, `nearby-chargers`, `alerts`, `release-notes`, `service`, `drivers`, `calendar`, `subscriptions`, `upgrades`, `options`, `specs`, `warranty`, `fleet-status`, `low-power`, `accessory-power`, `telemetry {config,create,delete,errors,stream}` | Vehicle discovery, state queries, fleet telemetry streaming, power management |
 | `charge` | `status`, `start`, `stop`, `limit`, `limit-max`, `limit-std`, `amps`, `port-open`, `port-close`, `schedule`, `departure`, `precondition-add`, `precondition-remove`, `add-schedule`, `remove-schedule`, `clear-schedules`, `clear-preconditions`, `managed-amps`, `managed-location`, `managed-schedule` | Charge queries, control, scheduling, and fleet management |
 | `billing` | `history`, `sessions`, `invoice` | Supercharger billing history and invoices |
 | `climate` | `status`, `on`, `off`, `set`, `precondition`, `seat`, `seat-cool`, `wheel-heater`, `overheat`, `bioweapon`, `keeper`, `cop-temp`, `auto-seat`, `auto-wheel`, `wheel-level` | Climate, seat, and steering wheel control |
@@ -355,6 +345,41 @@ Configure via environment variables:
 | `TESLA_CACHE_TTL` | `60` | Time-to-live in seconds |
 | `TESLA_CACHE_DIR` | `~/.cache/tescmd` | Cache directory path |
 
+## Fleet Telemetry Streaming
+
+Tesla's Fleet Telemetry lets your vehicle push real-time data directly to your server — no polling, no per-request charges. tescmd handles all the setup:
+
+```bash
+# Install telemetry dependencies
+pip install tescmd[telemetry]
+
+# Stream real-time data (Rich dashboard in TTY, JSONL when piped)
+tescmd vehicle telemetry stream
+
+# Select field presets
+tescmd vehicle telemetry stream --fields driving     # Speed, location, power
+tescmd vehicle telemetry stream --fields charging    # Battery, voltage, current
+tescmd vehicle telemetry stream --fields climate     # Temps, HVAC state
+tescmd vehicle telemetry stream --fields all         # Everything (120+ fields)
+
+# Override polling interval
+tescmd vehicle telemetry stream --interval 5         # Every 5 seconds
+
+# JSONL output for scripting
+tescmd vehicle telemetry stream --format json | jq .
+```
+
+**Requires Tailscale** with Funnel enabled. The stream command starts a local WebSocket server, exposes it via Tailscale Funnel (handles TLS + NAT traversal), configures Tesla to push data to it, and renders an interactive dashboard with live uptime counter, unit conversion, and connection status. Press `q` to stop — cleanup messages show each step (removing telemetry config, restoring partner domain, stopping tunnel).
+
+### Telemetry vs Polling Costs
+
+| Approach | 1 vehicle, 5-second interval, 24 hours | Monthly cost estimate |
+|---|---|---|
+| **Polling `vehicle_data`** | ~17,280 requests × $0.001 = **$17/day** | **$500+/month** |
+| **Fleet Telemetry streaming** | 1 config create + 1 config delete = **2 requests** | **< $0.01/month** |
+
+Fleet Telemetry streaming is a flat-cost alternative: you pay only for the initial config setup and teardown, regardless of how much data flows. The tradeoff is that you need Tailscale running on a machine to receive the push.
+
 ## Key Enrollment & Vehicle Command Protocol
 
 Newer Tesla vehicles require commands to be signed using the [Vehicle Command Protocol](https://github.com/teslamotors/vehicle-command). tescmd handles this transparently:
@@ -449,6 +474,18 @@ Run this periodically or after modifying API methods to catch drift.
 
 See [docs/development.md](docs/development.md) for detailed contribution guidelines.
 
+## Documentation
+
+- [Setup Guide](docs/setup.md) — step-by-step walkthrough of `tescmd setup`
+- [FAQ](docs/faq.md) — common questions about tescmd, costs, hosting, and configuration
+- [Command Reference](docs/commands.md) — detailed usage for every command
+- [API Costs](docs/api-costs.md) — detailed cost breakdown and savings calculations
+- [Bot Integration](docs/bot-integration.md) — JSON schema, exit codes, telemetry streaming, headless auth
+- [Architecture](docs/architecture.md) — layered design, module responsibilities, design decisions
+- [Vehicle Command Protocol](docs/vehicle-command-protocol.md) — ECDH sessions and signed commands
+- [Authentication](docs/authentication.md) — OAuth2 PKCE flow, token storage, scopes
+- [Development](docs/development.md) — contribution guidelines, testing, linting
+
 ## Changelog
 
 See [CHANGELOG.md](CHANGELOG.md) for release history.

{tescmd-0.1.2 → tescmd-0.2.0}/README.md

@@ -1,8 +1,10 @@
 # tescmd
 
-<!-- [![PyPI](https://img.shields.io/pypi/v/tescmd)](https://pypi.org/project/tescmd/) -->
-<!-- [![Python](https://img.shields.io/pypi/pyversions/tescmd)](https://pypi.org/project/tescmd/) -->
+[![PyPI](https://img.shields.io/pypi/v/tescmd)](https://pypi.org/project/tescmd/)
+[![Python](https://img.shields.io/pypi/pyversions/tescmd)](https://pypi.org/project/tescmd/)
+[![Build](https://img.shields.io/github/actions/workflow/status/oceanswave/tescmd/test.yml?branch=main&label=build)](https://github.com/oceanswave/tescmd/actions/workflows/test.yml)
 [![License](https://img.shields.io/github/license/oceanswave/tescmd)](LICENSE)
+[![GitHub Release](https://img.shields.io/github/v/release/oceanswave/tescmd)](https://github.com/oceanswave/tescmd/releases)
 
 A Python CLI for querying and controlling Tesla vehicles via the Fleet API — built for both human operators and AI agents.
 
@@ -21,7 +23,7 @@ tescmd is designed to work as a tool that AI agents can invoke directly. Platfor
 - **Tier enforcement** — readonly tier blocks write commands with clear guidance to upgrade
 - **Energy products** — Powerwall live status, site info, backup reserve, operation mode, storm mode, time-of-use settings, charging history, calendar history, grid import/export
 - **User & sharing** — account info, region, orders, feature flags, driver management, vehicle sharing invites
-- **Fleet Telemetry awareness** — setup wizard highlights Fleet Telemetry streaming for up to 97% API cost reduction
+- **Fleet Telemetry streaming** — `tescmd vehicle telemetry stream` starts a real-time dashboard with push-based data from your vehicle via Tailscale Funnel — no polling, 99%+ cost reduction
 - **Universal response caching** — all read commands are cached with tiered TTLs (1h for specs/warranty, 5m for fleet lists, 1m standard, 30s for location-dependent); bots can call tescmd as often as needed — within the TTL window, responses are instant and free
 - **Cost-aware wake** — prompts before sending billable wake API calls; `--wake` flag for scripts that accept the cost
 - **Guided OAuth2 setup** — `tescmd auth login` walks you through browser-based authentication with PKCE
@@ -36,40 +38,23 @@ tescmd is designed to work as a tool that AI agents can invoke directly. Platfor
 
 ```bash
 pip install tescmd
-
-# First-time setup (interactive wizard)
 tescmd setup
+```
 
-# Authenticate (opens browser)
-tescmd auth login
-
-# List your vehicles
-tescmd vehicle list
-
-# Get full vehicle data snapshot
-tescmd vehicle info
-
-# Check charge status (uses cache — second call is instant)
-tescmd charge status
-
-# Start charging (auto-invalidates cache)
-tescmd charge start --wake
-
-# Climate control
-tescmd climate on --wake
-tescmd climate set 72
-
-# Lock the car
-tescmd security lock --wake
+That's it. The interactive setup wizard walks you through everything: creating a Tesla Developer app, generating an EC key pair, hosting the public key (via GitHub Pages or Tailscale Funnel), registering with the Fleet API, authenticating via OAuth2, and enrolling your key on a vehicle. Each step checks prerequisites and offers remediation if something is missing.
 
-# Enroll your key on a vehicle (required for signed commands)
-tescmd key enroll 5YJ3E1EA1NF000000
+After setup completes, you can start using commands:
 
-# Cache management
-tescmd cache status
-tescmd cache clear
+```bash
+tescmd charge status               # Check battery and charging state
+tescmd vehicle info                 # Full vehicle data snapshot
+tescmd climate on --wake            # Turn on climate (wakes vehicle if asleep)
+tescmd security lock --wake         # Lock the car
+tescmd vehicle telemetry stream     # Real-time telemetry dashboard
 ```
 
+Every read command is cached — repeat calls within the TTL window are instant and free.
+
 ## Prerequisites
 
 The following tools should be installed and authenticated before running `tescmd setup`:
@@ -78,9 +63,11 @@ The following tools should be installed and authenticated before running `tescmd
 |------|----------|---------|------|
 | **Git** | Yes | Version control, repo management | N/A |
 | **GitHub CLI** (`gh`) | Recommended | Auto-creates `*.github.io` domain for key hosting | `gh auth login` |
-| **Tailscale** | Optional | Secure remote access to vehicles via Fleet Telemetry | `tailscale login` |
+| **Tailscale** | Optional | Key hosting via Funnel + Fleet Telemetry streaming | `tailscale login` |
+
+Without the GitHub CLI, `tescmd setup` will try Tailscale Funnel for key hosting (requires Funnel enabled in your tailnet ACL). Without either, you'll need to manually host your public key at the Tesla-required `.well-known` path on your own domain.
 
-Without the GitHub CLI, you'll need to manually host your public key at the Tesla-required `.well-known` path on your own domain. Tailscale is only needed if you plan to use Fleet Telemetry streaming for reduced API costs.
+For telemetry streaming, you need **Tailscale** with Funnel enabled.
 
 ## Installation
 
@@ -163,7 +150,7 @@ Check which backend is active with `tescmd status` — the output includes a `To
 |---|---|---|
 | `setup` | *(interactive wizard)* | First-run configuration: client ID, secret, region, domain, key enrollment |
 | `auth` | `login`, `logout`, `status`, `refresh`, `register`, `export`, `import` | OAuth2 authentication lifecycle |
-| `vehicle` | `list`, `get`, `info`, `data`, `location`, `wake`, `rename`, `mobile-access`, `nearby-chargers`, `alerts`, `release-notes`, `service`, `drivers`, `calendar`, `subscriptions`, `upgrades`, `options`, `specs`, `warranty`, `fleet-status`, `low-power`, `accessory-power`, `telemetry {config,create,delete,errors}` | Vehicle discovery, state queries, fleet telemetry, power management |
+| `vehicle` | `list`, `get`, `info`, `data`, `location`, `wake`, `rename`, `mobile-access`, `nearby-chargers`, `alerts`, `release-notes`, `service`, `drivers`, `calendar`, `subscriptions`, `upgrades`, `options`, `specs`, `warranty`, `fleet-status`, `low-power`, `accessory-power`, `telemetry {config,create,delete,errors,stream}` | Vehicle discovery, state queries, fleet telemetry streaming, power management |
 | `charge` | `status`, `start`, `stop`, `limit`, `limit-max`, `limit-std`, `amps`, `port-open`, `port-close`, `schedule`, `departure`, `precondition-add`, `precondition-remove`, `add-schedule`, `remove-schedule`, `clear-schedules`, `clear-preconditions`, `managed-amps`, `managed-location`, `managed-schedule` | Charge queries, control, scheduling, and fleet management |
 | `billing` | `history`, `sessions`, `invoice` | Supercharger billing history and invoices |
 | `climate` | `status`, `on`, `off`, `set`, `precondition`, `seat`, `seat-cool`, `wheel-heater`, `overheat`, `bioweapon`, `keeper`, `cop-temp`, `auto-seat`, `auto-wheel`, `wheel-level` | Climate, seat, and steering wheel control |
@@ -308,6 +295,41 @@ Configure via environment variables:
 | `TESLA_CACHE_TTL` | `60` | Time-to-live in seconds |
 | `TESLA_CACHE_DIR` | `~/.cache/tescmd` | Cache directory path |
 
+## Fleet Telemetry Streaming
+
+Tesla's Fleet Telemetry lets your vehicle push real-time data directly to your server — no polling, no per-request charges. tescmd handles all the setup:
+
+```bash
+# Install telemetry dependencies
+pip install tescmd[telemetry]
+
+# Stream real-time data (Rich dashboard in TTY, JSONL when piped)
+tescmd vehicle telemetry stream
+
+# Select field presets
+tescmd vehicle telemetry stream --fields driving     # Speed, location, power
+tescmd vehicle telemetry stream --fields charging    # Battery, voltage, current
+tescmd vehicle telemetry stream --fields climate     # Temps, HVAC state
+tescmd vehicle telemetry stream --fields all         # Everything (120+ fields)
+
+# Override polling interval
+tescmd vehicle telemetry stream --interval 5         # Every 5 seconds
+
+# JSONL output for scripting
+tescmd vehicle telemetry stream --format json | jq .
+```
+
+**Requires Tailscale** with Funnel enabled. The stream command starts a local WebSocket server, exposes it via Tailscale Funnel (handles TLS + NAT traversal), configures Tesla to push data to it, and renders an interactive dashboard with live uptime counter, unit conversion, and connection status. Press `q` to stop — cleanup messages show each step (removing telemetry config, restoring partner domain, stopping tunnel).
+
+### Telemetry vs Polling Costs
+
+| Approach | 1 vehicle, 5-second interval, 24 hours | Monthly cost estimate |
+|---|---|---|
+| **Polling `vehicle_data`** | ~17,280 requests × $0.001 = **$17/day** | **$500+/month** |
+| **Fleet Telemetry streaming** | 1 config create + 1 config delete = **2 requests** | **< $0.01/month** |
+
+Fleet Telemetry streaming is a flat-cost alternative: you pay only for the initial config setup and teardown, regardless of how much data flows. The tradeoff is that you need Tailscale running on a machine to receive the push.
+
 ## Key Enrollment & Vehicle Command Protocol
 
 Newer Tesla vehicles require commands to be signed using the [Vehicle Command Protocol](https://github.com/teslamotors/vehicle-command). tescmd handles this transparently:
@@ -402,6 +424,18 @@ Run this periodically or after modifying API methods to catch drift.
 
 See [docs/development.md](docs/development.md) for detailed contribution guidelines.
 
+## Documentation
+
+- [Setup Guide](docs/setup.md) — step-by-step walkthrough of `tescmd setup`
+- [FAQ](docs/faq.md) — common questions about tescmd, costs, hosting, and configuration
+- [Command Reference](docs/commands.md) — detailed usage for every command
+- [API Costs](docs/api-costs.md) — detailed cost breakdown and savings calculations
+- [Bot Integration](docs/bot-integration.md) — JSON schema, exit codes, telemetry streaming, headless auth
+- [Architecture](docs/architecture.md) — layered design, module responsibilities, design decisions
+- [Vehicle Command Protocol](docs/vehicle-command-protocol.md) — ECDH sessions and signed commands
+- [Authentication](docs/authentication.md) — OAuth2 PKCE flow, token storage, scopes
+- [Development](docs/development.md) — contribution guidelines, testing, linting
+
 ## Changelog
 
 See [CHANGELOG.md](CHANGELOG.md) for release history.

{tescmd-0.1.2 → tescmd-0.2.0}/docs/architecture.md

@@ -31,9 +31,15 @@ tescmd follows a layered architecture with strict separation of concerns. Each l
 │  auth/oauth.py ─ auth/token_store.py             │
 │    (OAuth2 PKCE, token refresh, keyring)         │
 ├─────────────────────────────────────────────────┤
+│              Telemetry Layer                      │
+│  telemetry/server.py ─ telemetry/decoder.py      │
+│  telemetry/dashboard.py ─ telemetry/fields.py    │
+│  telemetry/tailscale.py ─ telemetry/flatbuf.py   │
+│  (WebSocket server, protobuf decode, Rich TUI)   │
+├─────────────────────────────────────────────────┤
 │               Infrastructure                     │
 │  output/ ─ crypto/ ─ models/ ─ _internal/        │
-│  cache/ ─ (formatting, keys, schemas, helpers)   │
+│  cache/ ─ deploy/ ─ (formatting, keys, schemas)  │
 └─────────────────────────────────────────────────┘
 ```
 
@@ -115,7 +121,7 @@ CLI modules do **not** construct HTTP requests or handle auth tokens directly.
 
 **Currently implemented command groups:**
 - `auth` — login (`--reconsent`), logout, status, refresh, register, export, import
-- `vehicle` — list, info, data, location, wake, alerts, release-notes, service, drivers
+- `vehicle` — list, info, data, location, wake, alerts, release-notes, service, drivers, telemetry (config, create, delete, errors, stream)
 - `charge` — status, start, stop, limit, amps, schedule, departure, precondition
 - `climate` — status, on, off, set, seat, keeper, cop-temp, auto-seat, auto-wheel, wheel-level
 - `security` — status, lock, unlock, sentry, valet, remote-start, flash, honk, speed-limit, pin management
@@ -140,7 +146,7 @@ CLI modules do **not** construct HTTP requests or handle auth tokens directly.
 - **`energy.py`** (`EnergyAPI`) — Energy product endpoints (Powerwall, solar).
 - **`sharing.py`** (`SharingAPI`) — Driver and invite management.
 - **`user.py`** (`UserAPI`) — Account info, region, orders, features.
-- **`errors.py`** — Typed exceptions: `AuthError`, `MissingScopesError`, `VehicleAsleepError`, `SessionError`, `KeyNotEnrolledError`, `TierError`, `RateLimitError`, etc.
+- **`errors.py`** — Typed exceptions: `AuthError`, `MissingScopesError`, `VehicleAsleepError`, `SessionError`, `KeyNotEnrolledError`, `TierError`, `RateLimitError`, `TunnelError`, `TailscaleError`, etc.
 
 API classes use **composition**: they receive a `TeslaFleetClient` instance, not extend it.
 
@@ -188,6 +194,7 @@ See [vehicle-command-protocol.md](vehicle-command-protocol.md) for the full prot
 
 - **`keys.py`** — EC P-256 key generation, PEM export/import, public key extraction.
 - **`ecdh.py`** — ECDH key exchange (`derive_session_key`) and uncompressed public key extraction.
+- **`schnorr.py`** — Schnorr signature implementation for telemetry server authentication handshake.
 
 ### `output/` — Output Formatting
 
@@ -195,10 +202,27 @@ See [vehicle-command-protocol.md](vehicle-command-protocol.md) for the full prot
 - **`rich_output.py`** — Rich-based rendering: tables for vehicle data, charge status, climate status, vehicle config, GUI settings. Includes `DisplayUnits` for configurable unit conversion (°F/°C, mi/km, PSI/bar).
 - **`json_output.py`** — JSON serialization with consistent structure for machine parsing.
 
+### `telemetry/` — Fleet Telemetry Streaming
+
+- **`server.py`** (`TelemetryServer`) — Async WebSocket server that receives telemetry push from Tesla. Handles TLS via Tailscale Funnel certs, Schnorr-based authentication handshake, and frame dispatch.
+- **`decoder.py`** (`TelemetryDecoder`) — Decodes protobuf-encoded telemetry payloads using official Tesla proto definitions (`vehicle_data`, `vehicle_alert`, `vehicle_error`, `vehicle_metric`, `vehicle_connectivity`). Returns typed `TelemetryFrame` dataclasses.
+- **`flatbuf.py`** — FlatBuffer parser for Tesla's alternative telemetry encoding format.
+- **`fields.py`** — Field name registry (120+ fields) with preset configs (`default`, `driving`, `charging`, `climate`, `all`). Maps field names to protobuf field numbers.
+- **`dashboard.py`** (`TelemetryDashboard`) — Rich Live TUI with field name, value, and last-update columns. Supports unit conversion via `DisplayUnits`, connection status, frame counter, and uptime display.
+- **`tailscale.py`** (`TailscaleManager`) — Subprocess-based Tailscale management: check installation, start/stop Funnel, retrieve TLS certs, serve files at specific paths.
+
+**Optional dependency:** `pip install tescmd[telemetry]` adds `websockets>=14.0`.
+
+### `deploy/` — Key Deployment
+
+- **`github_pages.py`** — Deploys the public key to a GitHub Pages repo at the `.well-known` path.
+- **`tailscale_serve.py`** — Hosts the public key via Tailscale Funnel at `https://<machine>.tailnet.ts.net/.well-known/appspecific/com.tesla.3p.public-key.pem`.
+
 ### `_internal/` — Shared Utilities
 
 - **`vin.py`** — Smart VIN resolution: checks positional arg, `--vin` flag, active profile, then falls back to interactive vehicle picker.
 - **`async_utils.py`** — `run_async()` helper for running async code from sync Click entry points.
+- **`permissions.py`** — Cross-platform file permissions: `secure_file()` uses `chmod 0600` on Unix and `icacls` on Windows.
 
 ## Design Decisions