tescmd 0.2.0__tar.gz → 0.3.1__tar.gz

tescmd-0.3.1/.env.example

@@ -0,0 +1,75 @@
+# tescmd — Environment Variables
+#
+# Copy this file to .env and uncomment the variables you need.
+# The setup wizard (tescmd setup) will create ~/.config/tescmd/.env
+# for you automatically.
+#
+# Resolution order:
+#   1. Shell environment variables (highest priority)
+#   2. .env in the current working directory
+#   3. ~/.config/tescmd/.env (created by tescmd setup)
+
+# ─── Tesla Fleet API Credentials ─────────────────────────────────
+# Required. Obtain from https://developer.tesla.com
+# TESLA_CLIENT_ID=
+# TESLA_CLIENT_SECRET=
+
+# ─── Vehicle ──────────────────────────────────────────────────────
+# Default vehicle VIN (avoids passing --vin on every command)
+# TESLA_VIN=
+
+# API region: na (North America), eu (Europe), cn (China)
+# TESLA_REGION=na
+
+# ─── Token Override / Storage ─────────────────────────────────────
+# Direct token override (bypasses keyring / token file)
+# TESLA_ACCESS_TOKEN=
+# TESLA_REFRESH_TOKEN=
+
+# File path for token storage (skips OS keyring)
+# Useful for Docker, headless Linux, CI environments
+# TESLA_TOKEN_FILE=~/.config/tescmd/tokens.json
+
+# ─── Config & Cache ──────────────────────────────────────────────
+# TESLA_CONFIG_DIR=~/.config/tescmd
+# TESLA_CACHE_DIR=~/.cache/tescmd
+# TESLA_CACHE_TTL=60
+# TESLA_CACHE_ENABLED=true
+
+# ─── Output Format & Display Units ───────────────────────────────
+# Force output format: rich (TTY default), json (piped default), quiet
+# TESLA_OUTPUT_FORMAT=
+
+# Display unit preferences
+# TESLA_TEMP_UNIT=F           # F or C
+# TESLA_DISTANCE_UNIT=mi      # mi or km
+# TESLA_PRESSURE_UNIT=psi     # psi or bar
+
+# ─── Command Protocol & Key Hosting ──────────────────────────────
+# Command signing: auto (default), signed, unsigned
+# TESLA_COMMAND_PROTOCOL=auto
+
+# Domain for key hosting (set by tescmd setup)
+# TESLA_DOMAIN=
+
+# Key hosting method: github or tailscale
+# TESLA_HOSTING_METHOD=
+
+# GitHub repo for key deployment (e.g. username/username.github.io)
+# TESLA_GITHUB_REPO=
+
+# Setup tier: readonly or full
+# TESLA_SETUP_TIER=
+
+# Config profile name
+# TESLA_PROFILE=default
+
+# ─── MCP Server ──────────────────────────────────────────────────
+# Credentials for MCP OAuth 2.1 authentication
+# Required for tescmd serve and tescmd mcp serve
+# TESCMD_MCP_CLIENT_ID=
+# TESCMD_MCP_CLIENT_SECRET=
+
+# ─── OpenClaw ────────────────────────────────────────────────────
+# Gateway authentication token
+# OPENCLAW_GATEWAY_TOKEN=

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

@@ -5,8 +5,9 @@ dist/
 build/
 .venv/
 .env
+.env.bak
 *.pem
 .mypy_cache/
 .pytest_cache/
 .ruff_cache/
-.coverage
+.coverage

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

@@ -5,6 +5,65 @@ 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.3.1] - 2026-02-02
+
+### Added
+
+- **README overhaul** — header banner, logo, new "What It Does" summary section, expanded Prerequisites table with Python 3.11+, pip, Tesla account, and helpful links
+- **Tailscale Funnel auto-detection in auth setup** — `_interactive_setup` now detects Tailscale and offers to start Funnel so Tesla can verify the origin URL during Developer Portal configuration; cleans up Funnel on exit
+- **Tailscale hostname passthrough** — setup wizard forwards detected Tailscale hostname to auth flow, showing a concrete "Also add" origin URL instead of the generic placeholder
+- **Comprehensive agent skill documentation** — expanded skill covering all command groups, triggers, and OpenClaw dispatch
+
+### Fixed
+
+- **Cross-platform file permissions** — OpenClaw gateway key file now uses `secure_file()` from `_internal.permissions` instead of raw `chmod(0o600)`, adding proper Windows support via `icacls`
+- **12-factor app compliance** — config, disposability, and concurrency improvements across the codebase
+- **Documentation accuracy** — corrected `media_adjust_volume` tool name in MCP docs; emphasized MCP/OpenClaw over direct CLI for cost savings in agent skill
+
+## [0.3.0] - 2026-02-01
+
+### Added
+
+- **Unified `tescmd serve`** — single command combining MCP server, Fleet Telemetry streaming, cache warming, and optional OpenClaw bridge; full-screen TUI dashboard shows live telemetry, MCP status, tunnel URL, sink count, and connection health
+- **TUI dashboard** — 8-panel Textual layout with telemetry field table, server info sidebar, activity log, request log, and filter status; command palette (`ctrl+p`), keybindings (`q` to quit, `f` to toggle filters), clean graceful shutdown
+- **OpenClaw Bridge** — `tescmd openclaw bridge [VIN]` streams Fleet Telemetry to an OpenClaw Gateway with configurable delta+throttle filtering per field; supports `--dry-run` for JSONL output without a gateway connection
+- **OpenClaw node role** — bidirectional command dispatch over the gateway WebSocket; bots send commands via the gateway that are forwarded as `node.invoke.request` events, routed through `CommandDispatcher` with read/write separation, tier enforcement, and VCSEC signing guards
+- **Trigger subscription system** — `trigger.create`, `trigger.delete`, `trigger.list`, `trigger.poll` commands let bots register conditions on any telemetry field; supports operators `lt`, `gt`, `lte`, `gte`, `eq`, `neq`, `changed`, `enter`, `leave`; one-shot and persistent modes with configurable cooldown; max 100 triggers, 500 pending notifications
+- **Geofence triggers** — `enter`/`leave` operators on Location field detect boundary crossings using haversine distance; fires only on actual crossing (not "already inside"), requires previous position for comparison
+- **Trigger convenience aliases** — `cabin_temp.trigger`, `outside_temp.trigger`, `battery.trigger`, `location.trigger` pre-fill the field name so bots don't need to know raw telemetry field names
+- **Trigger notification delivery** — dual-channel: OpenClaw push events (`trigger.fired`) for connected bots, and MCP polling via `trigger_poll` tool for agent frameworks
+- **`system.run` meta-dispatch** — allows bots to invoke any registered handler by name with alias mapping (e.g., `door_lock` → `door.lock`, `auto_conditioning_start` → `climate.on`); guards against recursive self-dispatch
+- **MCP Server** — `tescmd mcp serve` exposes all tescmd commands as MCP tools for Claude Desktop/Code and other agent frameworks; supports stdio and streamable-http transports with OAuth 2.1 authentication
+- **MCP custom tool registry** — `MCPServer.register_custom_tool()` allows runtime registration of non-CLI tools (used by trigger system); custom tools appear alongside CLI-backed tools with proper schemas
+- **Agent skill** — `skills/tescmd/SKILL.md` teaches AI agents how to use every tescmd command group with examples, parameter types, and common patterns
+- **Reusable telemetry session** — extracted shared telemetry lifecycle (server → tunnel → partner registration → fleet config → cleanup) into `telemetry/setup.py` for use by serve, stream, and bridge commands
+- **Dual-gate telemetry filter** — `openclaw/filters.py` combines delta threshold (value change) and throttle interval (minimum time between emissions) to reduce noise in telemetry streams; includes haversine distance for location fields
+- **OpenClaw event emitter** — maps telemetry fields to OpenClaw `req:agent` event payloads (location, battery, temperature, speed, charge state transitions, security changes)
+- **Gateway WebSocket client** — implements the OpenClaw operator protocol (challenge → connect → hello-ok handshake) with Ed25519 device key signing and exponential backoff reconnection
+- **Bridge configuration** — `BridgeConfig` pydantic model with per-field filter settings, loadable from JSON file or CLI flags
+- **CSV telemetry logging** — wide-format CSV log with one row per frame and one column per subscribed field; written to `~/.config/tescmd/logs/` by default, disable with `--no-log`
+- **Cache sink** — telemetry-driven cache warming keeps read-command cache fresh while telemetry is active, making agent reads free
+- **Frame fanout** — `FrameFanout` distributes decoded telemetry frames to multiple sinks (dashboard, CSV, cache, OpenClaw bridge, triggers) in parallel
+- **Telemetry field mapper** — `telemetry/mapper.py` maps protobuf field names to tescmd model field names with unit conversion
+- **Command guards in dispatcher** — extracted `check_command_guards()` (tier check + VCSEC signing requirement) into a shared function called by both CLI and OpenClaw dispatcher paths
+- **Standard dependencies** — `websockets>=14.0`, `mcp>=1.0`, and `textual>=1.0` now included in default install
+
+### Changed
+
+- Refactored `_cmd_telemetry_stream` in `cli/vehicle.py` to use the shared `telemetry_session()` context manager (no behavioral change)
+- Proto-aligned telemetry field definitions with proper `interval_seconds` for delta fields
+- Separated JSON serialization errors from WebSocket connection errors in gateway send path for clearer diagnostics
+- Raised trigger push notification and lifecycle event failures from debug to warning level for observability
+
+### Fixed
+
+- Fixed prompt for re-authentication when refresh token is expired or revoked (was failing silently)
+- Fixed delta fields requiring `interval_seconds` configuration
+- Fixed log file paths not shown on quit
+- Added `exc_info` to MCP custom tool error logging for full stack traces
+- Added JSON parse guards and explicit parameter validation in MCP tool wrappers
+- Added `system.run` recursive self-dispatch guard
+
 ## [0.2.0] - 2026-01-31
 
 ### Added
@@ -18,7 +77,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **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`
+- **websockets dependency** — `websockets>=14.0` now included in default install
 - **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

tescmd-0.3.1/CLAUDE.md

@@ -0,0 +1,131 @@
+# CLAUDE.md — Project Context for Claude Code
+
+## Project Overview
+
+**tescmd** is a Python 3.11+ CLI for querying and controlling Tesla vehicles via the [Tesla Fleet API](https://developer.tesla.com/docs/fleet-api). It covers auth, vehicle queries/commands, energy products, Supercharger billing, Fleet Telemetry streaming, OpenClaw bridge, and an MCP server for agent integration.
+
+## Tech Stack
+
+- **Python 3.11+**, **pydantic v2**, **click**, **httpx** (async), **rich**, **cryptography**, **protobuf**, **keyring**, **python-dotenv**
+- **websockets** (telemetry + OpenClaw), **mcp** (MCP server) — core dependencies
+- Optional: **bleak** (`[ble]` extra — BLE key enrollment)
+
+## Project Structure
+
+```
+src/tescmd/
+├── cli/                   # Click CLI layer
+│   ├── main.py            # Root group, AppContext, _register_commands()
+│   ├── _options.py        # Shared Click options/decorators (@global_options)
+│   ├── _client.py         # API client builders, auto_wake, cached_vehicle_data, cached_api_call, TTL tiers
+│   ├── auth.py, cache.py, charge.py, billing.py, climate.py, security.py
+│   ├── status.py, trunk.py, vehicle.py, media.py, nav.py, partner.py
+│   ├── software.py, energy.py, user.py, sharing.py, raw.py, key.py
+│   ├── setup.py           # Interactive first-run wizard
+│   ├── serve.py           # Unified MCP + telemetry + OpenClaw command
+│   ├── openclaw.py        # Standalone openclaw bridge command
+│   └── mcp_cmd.py         # mcp serve command
+├── api/                   # HTTP client + domain APIs (composition pattern)
+│   ├── client.py          # TeslaFleetClient (base HTTP, auth headers, retries)
+│   ├── vehicle.py, command.py, signed_command.py, energy.py
+│   ├── charging.py, partner.py, sharing.py, user.py
+│   └── errors.py          # AuthError, VehicleAsleepError, TierError, TunnelError, etc.
+├── models/                # Pydantic v2 models (vehicle, energy, user, auth, command, config)
+├── auth/                  # OAuth2 PKCE, token_store (keyring + file fallback), callback server
+├── protocol/              # Vehicle Command Protocol (ECDH sessions, HMAC signing, protobuf)
+├── crypto/                # EC key gen, ECDH, Schnorr signatures
+├── cache/                 # File-based JSON cache with tiered TTLs
+├── output/                # OutputFormatter, RichOutput (DisplayUnits), JsonOutput
+├── telemetry/             # Fleet Telemetry streaming
+│   ├── setup.py           # Reusable telemetry_session() context manager
+│   ├── server.py, decoder.py, fields.py, dashboard.py, tailscale.py
+├── openclaw/              # OpenClaw bridge
+│   ├── config.py          # BridgeConfig, FieldFilter, NodeCapabilities (pydantic)
+│   ├── filters.py         # DualGateFilter (delta + throttle), haversine()
+│   ├── emitter.py         # EventEmitter (telemetry → OpenClaw events)
+│   ├── gateway.py         # GatewayClient (WebSocket, node protocol, Ed25519 auth)
+│   ├── bridge.py          # TelemetryBridge orchestrator, build_openclaw_pipeline()
+│   ├── dispatcher.py      # CommandDispatcher (reads, writes, triggers, system.run)
+│   └── telemetry_store.py # In-memory latest-value cache for telemetry fields
+├── triggers/              # Trigger subscription system
+│   ├── models.py          # TriggerOperator, TriggerCondition, TriggerDefinition, TriggerNotification
+│   └── manager.py         # TriggerManager (evaluation, cooldown, delivery, geofencing)
+├── mcp/                   # MCP server
+│   └── server.py          # MCPServer (FastMCP, CliRunner + custom callable tools)
+├── deploy/                # Key hosting (GitHub Pages, Tailscale Funnel)
+└── _internal/             # vin.py, async_utils.py, permissions.py
+```
+
+## Coding Conventions
+
+- **Type hints everywhere** — all function signatures, all variables where non-obvious
+- **async/await** — all API calls are async; CLI entry points use `run_async()` helper
+- **Pydantic models** — all API request/response payloads; all configuration
+- **src layout** — code in `src/tescmd/`, tests in `tests/`
+- **No star imports** — explicit imports only
+- **Single responsibility** — CLI modules handle args + output, API modules handle HTTP
+- **Composition over inheritance** — API classes wrap `TeslaFleetClient`, don't extend it
+- **Error stream routing** — JSON/piped mode writes errors to stderr; Rich/TTY mode uses stdout
+
+## Key Patterns
+
+**CLI command registration:** New command groups are registered in `cli/main.py:_register_commands()`. Each CLI module defines a Click group and is imported there.
+
+**Global options propagation:** Use `@global_options` decorator from `cli/_options.py` on commands that need VIN, format, wake, cache flags. Options flow through `AppContext` via `@click.pass_obj`.
+
+**API client construction:** `cli/_client.py` provides `get_vehicle_api(app_ctx)` → returns `(client, api)` tuple. Also `get_command_api()` for write commands (handles signed vs unsigned routing).
+
+**Cache:** All read commands use `cached_api_call()` with scope-aware TTLs (STATIC 1h, SLOW 5m, DEFAULT 1m, FAST 30s). Write commands invalidate via `invalidate_cache_for_vin()` / `invalidate_cache_for_site()`.
+
+**Output:** `OutputFormatter` auto-detects TTY → Rich, piped → JSON, `--quiet` → stderr only. JSON output uses a consistent `{ok, command, data, error, timestamp}` envelope.
+
+**Telemetry session lifecycle:** `telemetry/setup.py:telemetry_session()` is an async context manager handling: server start → Tailscale tunnel → partner domain re-registration → fleet config → yield → cleanup. Used by both `cli/vehicle.py` (stream) and `cli/openclaw.py` (bridge).
+
+**OpenClaw pipeline:** `TelemetryServer.on_frame` → `DualGateFilter.should_emit()` → `EventEmitter.to_event()` → `GatewayClient.send_event()`. The `TelemetryBridge` class wires these together. `build_openclaw_pipeline()` is the shared factory used by both `cli/openclaw.py` (standalone) and `cli/serve.py` (combined mode). Inbound commands flow: gateway `node.invoke.request` → `CommandDispatcher.dispatch()` → handler → `node.invoke.result`.
+
+**Trigger system:** `TriggerManager` evaluates conditions on every telemetry frame (independent of the dual-gate filter). Supports numeric comparison (`lt`, `gt`, `eq`, etc.), `changed` detection, and geofence `enter`/`leave` with haversine distance. One-shot and persistent (with cooldown) firing modes. Notifications delivered via OpenClaw push and MCP polling (`trigger.poll`).
+
+**MCP tools:** `mcp/server.py` maps tool names to CLI arg lists via `_CliToolDef` dataclasses. `invoke_tool()` uses `CliRunner.invoke(cli, ["--format", "json", "--wake", *args], env=os.environ.copy())`. Custom tools (e.g. trigger CRUD) use `_CustomToolDef` with direct callable handlers registered via `register_custom_tool()`. Read/write tools are separated for `readOnlyHint` annotations. HTTP transport uses OAuth 2.1 via `_InMemoryOAuthProvider` (auto-approve authorization, dynamic client registration, in-memory token storage) with `_PermissiveClient` wrappers that accept any redirect URI. DNS rebinding protection is configured to allow the Tailscale Funnel hostname when `public_url` is set.
+
+## Build & Test
+
+```bash
+# Build
+python -m build                    # hatchling via pyproject.toml
+
+# Test (parallel by default via pytest-xdist)
+pytest                             # all ~1600 tests
+pytest tests/openclaw/ -x -v       # openclaw tests
+pytest tests/triggers/ -x -v       # trigger tests
+pytest tests/mcp/ -x -v            # mcp tests
+pytest -m e2e                      # live API smoke tests (needs TESLA_ACCESS_TOKEN)
+
+# Lint
+ruff check src/ tests/
+ruff format src/ tests/
+mypy src/
+```
+
+## Environment Variables
+
+| Variable | Description |
+|---|---|
+| `TESLA_CLIENT_ID` / `TESLA_CLIENT_SECRET` | OAuth2 app credentials |
+| `TESLA_VIN` | Default vehicle VIN |
+| `TESLA_REGION` | API region: `na`, `eu`, `cn` |
+| `TESLA_ACCESS_TOKEN` / `TESLA_REFRESH_TOKEN` | Direct token override |
+| `TESLA_TOKEN_FILE` | File path for token storage (skips keyring) |
+| `TESLA_CONFIG_DIR` | Config directory (default: `~/.config/tescmd`) |
+| `TESLA_CACHE_DIR` / `TESLA_CACHE_TTL` / `TESLA_CACHE_ENABLED` | Cache settings |
+| `TESLA_OUTPUT_FORMAT` | Force format: `rich`, `json`, `quiet` |
+| `TESLA_COMMAND_PROTOCOL` | `auto` (default), `signed`, `unsigned` |
+| `TESLA_TEMP_UNIT` / `TESLA_DISTANCE_UNIT` / `TESLA_PRESSURE_UNIT` | Display units |
+| `TESLA_DOMAIN` / `TESLA_HOSTING_METHOD` / `TESLA_GITHUB_REPO` | Key hosting |
+| `TESLA_SETUP_TIER` | `readonly` or `full` |
+| `TESLA_PROFILE` | Active config profile |
+| `OPENCLAW_GATEWAY_TOKEN` | OpenClaw gateway auth token |
+
+
+## Additional Resources
+
+Tesla's published vehicle-command proto omits some VehicleAction fields (e.g. navigation commands). The Teslemetry project maintains a more complete proto: https://github.com/Teslemetry/python-tesla-fleet-api/blob/main/proto/car_server.proto

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tescmd
-Version: 0.2.0
+Version: 0.3.1
 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
@@ -26,11 +26,16 @@ 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
@@ -44,23 +49,33 @@ 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
 
+<p align="center">
+  <img src="images/tescmd_header.jpeg" alt="tescmd — Python CLI for Tesla Fleet API" width="100%">
+</p>
+
 # 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)
+<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>
 
 A Python CLI for querying and controlling Tesla vehicles via the Fleet API — built for both human operators and AI agents.
 
+## What It Does
+
+tescmd gives you full command-line access to Tesla's Fleet API: check battery and charge status, lock or unlock doors, control climate, open trunks, send navigation waypoints, manage Powerwalls, stream live telemetry, and more. It handles OAuth2 authentication, token refresh, key enrollment, command signing, and response caching so you don't have to. Every command works in both interactive (Rich tables) and scripted (JSON) modes, and an MCP server lets AI agents call any command as a tool.
+
 ## Why tescmd?
 
-Tesla's Fleet API gives developers full access to vehicle data and commands, but working with it directly means juggling OAuth2 PKCE flows, token refresh, regional endpoints, key enrollment, and raw JSON responses. tescmd wraps all of that into a single command-line tool that handles authentication, token management, and output formatting so you can focus on what you actually want to do — check your battery, find your car, or control your vehicle.
+Tesla's Fleet API gives developers full access to vehicle data and commands, but working with it directly means juggling OAuth2 PKCE flows, token refresh, regional endpoints, key enrollment, and raw JSON responses.
+
+tescmd wraps all of that into a single command-line tool that handles authentication, token management, and output formatting so you can focus on what you actually want to do — check your battery, find your car, or control your vehicle.
 
 tescmd is designed to work as a tool that AI agents can invoke directly. Platforms like [OpenClaw](https://openclaw.ai/), [Claude Desktop](https://claude.ai), and other agent frameworks can call tescmd commands, parse the structured JSON output, and take actions on your behalf — "lock my car", "what's my battery at?", "start climate control". The deterministic JSON output, meaningful exit codes, cost-aware wake confirmation, and `--wake` opt-in flag make it safe for autonomous agent use without surprise billing.
 
@@ -73,7 +88,11 @@ 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 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
+- **Live Dashboard** — `tescmd serve` launches a full-screen TUI showing live telemetry data, MCP server info, tunnel URL, sink count, and cache stats — all in a scrollable, interactive terminal UI powered by Textual
+- **Fleet Telemetry streaming** — `tescmd serve` (or `tescmd vehicle telemetry stream`) receives push-based data from your vehicle via Tailscale Funnel — no polling, 99%+ cost reduction. Telemetry sessions produce a wide-format CSV log by default
+- **OpenClaw Bridge** — `tescmd serve --openclaw ws://...` streams filtered telemetry to an OpenClaw Gateway with configurable delta+throttle filtering per field; supports bidirectional command dispatch so bots can send vehicle commands back through the gateway
+- **Trigger subscriptions** — register conditions on any telemetry field (battery < 20%, speed > 80, location enters geofence) and get notified via OpenClaw push events or MCP polling; supports one-shot and persistent modes with cooldown
+- **MCP Server** — `tescmd serve` (or `tescmd mcp serve`) exposes all commands as MCP tools for Claude.ai, Claude Desktop, Claude Code, and other agent frameworks via OAuth 2.1
 - **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
@@ -100,24 +119,35 @@ 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
+tescmd serve 5YJ3...               # MCP + telemetry TUI dashboard + CSV log
+tescmd serve --no-mcp              # Telemetry-only TUI 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`:
+| Requirement | Required | What it is | Why tescmd needs it |
+|---|---|---|---|
+| **Python 3.11+** | Yes | The programming language runtime that runs tescmd | tescmd is a Python package — you need Python installed to use it |
+| **pip** | Yes | Python's package installer (ships with Python) | Used to install tescmd and its dependencies via `pip install tescmd` |
+| **Tesla account** | Yes | A [tesla.com](https://www.tesla.com) account linked to a vehicle or energy product | tescmd authenticates via OAuth2 against your Tesla account to access the Fleet API |
+| **Git** | Yes | Version control tool ([git-scm.com](https://git-scm.com)) | Used during setup for key hosting via GitHub Pages |
+| **GitHub CLI** (`gh`) | Recommended | GitHub's command-line tool ([cli.github.com](https://cli.github.com)) — authenticate with `gh auth login` | Auto-creates a `*.github.io` site to host your public key at the `.well-known` path Tesla requires |
+| **Tailscale** | Recommended | Mesh VPN with public tunneling ([tailscale.com](https://tailscale.com)) — authenticate with `tailscale login` | Provides a public HTTPS URL for key hosting and Fleet Telemetry streaming with zero infrastructure setup |
+
+### Self-Hosting with Tailscale (No Domain Required)
+
+If you have **Tailscale** installed with Funnel enabled, you don't need a custom domain or GitHub Pages at all. Tailscale Funnel gives you a public HTTPS URL (`<machine>.tailnet.ts.net`) that serves both your public key and (optionally) Fleet Telemetry streaming — all from your local machine with zero infrastructure setup.
 
-| Tool | Required | Purpose | Auth |
-|------|----------|---------|------|
-| **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 | Key hosting via Funnel + Fleet Telemetry streaming | `tailscale login` |
+```bash
+# Install Tailscale, enable Funnel in your tailnet ACL, then:
+tescmd setup   # wizard auto-detects Tailscale and offers it as the hosting method
+```
 
-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.
+This is the fastest path to a working setup: Tailscale handles TLS certificates, NAT traversal, and public DNS automatically. The tradeoff is that your machine needs to be running for Tesla to reach your key and for telemetry streaming to work. For always-on key hosting with offline machines, use GitHub Pages instead.
 
-For telemetry streaming, you need **Tailscale** with Funnel enabled.
+Without either GitHub CLI or Tailscale, you'll need to manually host your public key at the Tesla-required `.well-known` path on your own domain.
 
 ## Installation
 
@@ -214,6 +244,9 @@ Check which backend is active with `tescmd status` — the output includes a `To
 | `sharing` | `add-driver`, `remove-driver`, `create-invite`, `redeem-invite`, `revoke-invite`, `list-invites` | Vehicle sharing and driver management |
 | `key` | `generate`, `deploy`, `validate`, `show`, `enroll`, `unenroll` | Key management and enrollment |
 | `partner` | `public-key`, `telemetry-error-vins`, `telemetry-errors` | Partner account endpoints (require client credentials) |
+| `serve` | *(unified server)* | Combined MCP + telemetry + OpenClaw TUI dashboard with trigger subscriptions |
+| `openclaw` | `bridge` | Standalone OpenClaw bridge with bidirectional command dispatch |
+| `mcp` | `serve` | Standalone MCP server exposing all commands as agent tools |
 | `cache` | `status`, `clear` | Response cache management |
 | `raw` | `get`, `post` | Arbitrary Fleet API endpoint access |
 
@@ -295,7 +328,7 @@ A naive script that polls `vehicle_data` every 5 minutes generates **4-5 billabl
 
 | | Without tescmd | With tescmd |
 |---|---|---|
-| Vehicle asleep, check battery | 408 error (billable) + wake (billable) + poll (billable) + data (billable) = **4+ requests** | Cache miss → prompt user → user wakes via Tesla app (free) → retry → data (billable) = **1 request** |
+| Vehicle asleep, check battery | 408 error (billable) + wake (billable) + poll (billable) + data (billable) = **4+ requests** | Data attempt → 408 (billable) → prompt user → user wakes via Tesla app (free) → retry → data (billable) = **2 requests** |
 | Check battery again 30s later | Another 4+ requests | **0 requests** (cache hit) |
 | 10 checks in 1 minute | **40+ billable requests** | **1 billable request** + 9 cache hits |
 
@@ -350,26 +383,35 @@ Configure via environment variables:
 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]
+# Full-screen TUI with live telemetry + MCP server
+tescmd serve 5YJ3...
 
-# Stream real-time data (Rich dashboard in TTY, JSONL when piped)
-tescmd vehicle telemetry stream
+# Telemetry-only mode (full-screen TUI, no MCP)
+tescmd serve 5YJ3... --no-mcp
 
 # 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)
+tescmd serve 5YJ3... --fields driving     # Speed, location, power
+tescmd serve 5YJ3... --fields charging    # Battery, voltage, current
+tescmd serve 5YJ3... --fields all         # Everything (120+ fields)
 
 # Override polling interval
-tescmd vehicle telemetry stream --interval 5         # Every 5 seconds
+tescmd serve 5YJ3... --interval 5         # Every 5 seconds
+
+# JSONL output for scripting (non-TTY / piped)
+tescmd serve 5YJ3... --no-mcp --format json | jq .
+
+# Disable CSV log
+tescmd serve 5YJ3... --no-log
 
-# JSONL output for scripting
-tescmd vehicle telemetry stream --format json | jq .
+# Legacy Rich Live dashboard
+tescmd serve 5YJ3... --legacy-dashboard
 ```
 
-**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).
+**Requires Tailscale** with Funnel enabled. The serve command starts a local WebSocket server, exposes it via Tailscale Funnel (handles TLS + NAT traversal), configures Tesla to push data to it, and renders a full-screen TUI with live telemetry data, server info (MCP URL, tunnel, sinks), unit conversion, and connection status. Press `q` to quit.
+
+By default, telemetry sessions write a wide-format CSV log to `~/.config/tescmd/logs/` with one row per frame and one column per subscribed field. Disable with `--no-log`.
+
+`tescmd vehicle telemetry stream` is an alias for `tescmd serve --no-mcp`.
 
 ### Telemetry vs Polling Costs
 
@@ -481,6 +523,8 @@ See [docs/development.md](docs/development.md) for detailed contribution guideli
 - [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
+- [OpenClaw Bridge](docs/openclaw.md) — gateway protocol, bidirectional commands, trigger subscriptions, geofencing
+- [MCP Server](docs/mcp.md) — tool reference, authentication, custom tools, trigger polling
 - [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
@@ -493,3 +537,7 @@ See [CHANGELOG.md](CHANGELOG.md) for release history.
 ## License
 
 MIT
+
+<p align="center">
+  <img src="images/tescmd_logo.jpeg" alt="tescmd logo" width="180">
+</p>