tescmd 0.1.2__py3-none-any.whl → 0.3.1__py3-none-any.whl

tescmd/triggers/__init__.py

@@ -0,0 +1,18 @@
+"""Trigger/subscription system for telemetry-driven notifications."""
+
+from tescmd.triggers.manager import TriggerLimitError, TriggerManager
+from tescmd.triggers.models import (
+    TriggerCondition,
+    TriggerDefinition,
+    TriggerNotification,
+    TriggerOperator,
+)
+
+__all__ = [
+    "TriggerCondition",
+    "TriggerDefinition",
+    "TriggerLimitError",
+    "TriggerManager",
+    "TriggerNotification",
+    "TriggerOperator",
+]

tescmd/triggers/manager.py

@@ -0,0 +1,264 @@
+"""Trigger evaluation engine.
+
+Evaluates registered triggers against incoming telemetry values,
+manages cooldowns, fires callbacks, and queues notifications.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from collections import defaultdict, deque
+from typing import TYPE_CHECKING, Any
+
+from tescmd.triggers.models import (
+    TriggerCondition,
+    TriggerDefinition,
+    TriggerNotification,
+    TriggerOperator,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+    from datetime import datetime
+
+logger = logging.getLogger(__name__)
+
+MAX_TRIGGERS = 100
+MAX_PENDING = 500
+
+
+class TriggerLimitError(Exception):
+    """Raised when the maximum number of triggers is exceeded."""
+
+
+class TriggerManager:
+    """Manages trigger lifecycle and evaluation.
+
+    Parameters
+    ----------
+    vin:
+        Vehicle Identification Number — included in notifications.
+    """
+
+    def __init__(self, vin: str) -> None:
+        self._vin = vin
+        self._triggers: dict[str, TriggerDefinition] = {}
+        self._field_index: dict[str, set[str]] = defaultdict(set)
+        self._last_fire_times: dict[str, float] = {}
+        self._pending: deque[TriggerNotification] = deque(maxlen=MAX_PENDING)
+        self._on_fire_callbacks: list[Callable[[TriggerNotification], Awaitable[None]]] = []
+
+    def create(self, trigger: TriggerDefinition) -> TriggerDefinition:
+        """Register a trigger.  Returns the trigger with its assigned ID.
+
+        Raises :class:`TriggerLimitError` if the limit is reached.
+        """
+        if len(self._triggers) >= MAX_TRIGGERS:
+            raise TriggerLimitError(
+                f"Maximum of {MAX_TRIGGERS} triggers reached. "
+                "Delete some before creating new ones."
+            )
+
+        cond = trigger.condition
+        self._triggers[trigger.id] = trigger
+        self._field_index[cond.field].add(trigger.id)
+        logger.info(
+            "Created trigger %s: %s %s %s",
+            trigger.id,
+            cond.field,
+            cond.operator.value,
+            cond.value,
+        )
+        return trigger
+
+    def delete(self, trigger_id: str) -> bool:
+        """Remove a trigger by ID.  Returns ``True`` if it existed."""
+        trigger = self._triggers.pop(trigger_id, None)
+        if trigger is None:
+            return False
+        field = trigger.condition.field
+        ids = self._field_index.get(field)
+        if ids is not None:
+            ids.discard(trigger_id)
+            if not ids:
+                del self._field_index[field]
+        self._last_fire_times.pop(trigger_id, None)
+        logger.info("Deleted trigger %s", trigger_id)
+        return True
+
+    def list_all(self) -> list[TriggerDefinition]:
+        """Return all registered triggers."""
+        return list(self._triggers.values())
+
+    def drain_pending(self) -> list[TriggerNotification]:
+        """Return and clear all pending notifications (for MCP polling)."""
+        result = list(self._pending)
+        self._pending.clear()
+        return result
+
+    def add_on_fire(self, callback: Callable[[TriggerNotification], Awaitable[None]]) -> None:
+        """Register an async callback invoked when a trigger fires."""
+        self._on_fire_callbacks.append(callback)
+
+    async def evaluate(
+        self,
+        field: str,
+        value: Any,
+        previous_value: Any,
+        timestamp: datetime,
+    ) -> None:
+        """Evaluate all triggers registered for *field*.
+
+        Called by the bridge after capturing the previous value and
+        before updating the telemetry store.
+        """
+        trigger_ids = self._field_index.get(field)
+        if not trigger_ids:
+            return
+
+        now = time.monotonic()
+        # Iterate over a copy — one-shot triggers mutate the set
+        for tid in list(trigger_ids):
+            trigger = self._triggers.get(tid)
+            if trigger is None:
+                continue
+
+            # Cooldown check for persistent triggers
+            if not trigger.once:
+                last_fire = self._last_fire_times.get(tid)
+                if last_fire is not None and (now - last_fire) < trigger.cooldown_seconds:
+                    continue
+
+            if not _matches(trigger.condition, value, previous_value):
+                continue
+
+            # Fire!
+            self._last_fire_times[tid] = now
+            notification = TriggerNotification(
+                trigger_id=tid,
+                field=field,
+                operator=trigger.condition.operator,
+                threshold=trigger.condition.value,
+                value=value,
+                previous_value=previous_value,
+                fired_at=timestamp,
+                vin=self._vin,
+            )
+
+            logger.info(
+                "Trigger %s fired: %s %s %s (value=%s prev=%s)",
+                tid,
+                field,
+                trigger.condition.operator.value,
+                trigger.condition.value,
+                value,
+                previous_value,
+            )
+
+            self._pending.append(notification)
+
+            for callback in self._on_fire_callbacks:
+                try:
+                    await callback(notification)
+                except Exception:
+                    logger.warning("Trigger fire callback failed for %s", tid, exc_info=True)
+
+            # Auto-delete one-shot triggers
+            if trigger.once:
+                self.delete(tid)
+
+
+def _matches(condition: TriggerCondition, value: Any, previous_value: Any) -> bool:
+    """Check whether a value satisfies a trigger condition."""
+    op = condition.operator
+
+    if op == TriggerOperator.CHANGED:
+        return bool(value != previous_value)
+
+    if op == TriggerOperator.EQ:
+        return bool(value == condition.value)
+
+    if op == TriggerOperator.NEQ:
+        return bool(value != condition.value)
+
+    if op in (TriggerOperator.ENTER, TriggerOperator.LEAVE):
+        return _matches_geofence(condition, value, previous_value)
+
+    # Numeric comparisons
+    try:
+        fval = float(value)
+        fthresh = float(condition.value)
+    except (TypeError, ValueError):
+        logger.debug(
+            "Numeric coercion failed for %s %s (value=%r, threshold=%r)",
+            condition.field,
+            op.value,
+            value,
+            condition.value,
+        )
+        return False
+
+    if op == TriggerOperator.LT:
+        return fval < fthresh
+    if op == TriggerOperator.GT:
+        return fval > fthresh
+    if op == TriggerOperator.LTE:
+        return fval <= fthresh
+    if op == TriggerOperator.GTE:
+        return fval >= fthresh
+
+    return False
+
+
+def _matches_geofence(condition: TriggerCondition, value: Any, previous_value: Any) -> bool:
+    """Evaluate geofence enter/leave conditions.
+
+    Requires a boundary crossing — being "already inside" doesn't fire
+    an ``enter`` trigger.  ``previous_value`` of ``None`` never fires.
+    """
+    from tescmd.openclaw.filters import haversine
+
+    if previous_value is None:
+        return False
+
+    geo = condition.value
+    if not isinstance(geo, dict):
+        logger.warning("Geofence trigger on %s has non-dict value: %r", condition.field, geo)
+        return False
+
+    try:
+        center_lat = float(geo["latitude"])
+        center_lon = float(geo["longitude"])
+        radius = float(geo["radius_m"])
+    except (KeyError, TypeError, ValueError):
+        logger.warning(
+            "Geofence trigger on %s has invalid config (need latitude, longitude, radius_m): %r",
+            condition.field,
+            geo,
+        )
+        return False
+
+    try:
+        cur_lat = float(value["latitude"])
+        cur_lon = float(value["longitude"])
+        prev_lat = float(previous_value["latitude"])
+        prev_lon = float(previous_value["longitude"])
+    except (KeyError, TypeError, ValueError):
+        logger.debug(
+            "Geofence data missing coordinates for %s (value=%r, prev=%r)",
+            condition.field,
+            value,
+            previous_value,
+        )
+        return False
+
+    cur_dist = haversine(cur_lat, cur_lon, center_lat, center_lon)
+    prev_dist = haversine(prev_lat, prev_lon, center_lat, center_lon)
+
+    if condition.operator == TriggerOperator.ENTER:
+        return cur_dist <= radius and prev_dist > radius
+    if condition.operator == TriggerOperator.LEAVE:
+        return cur_dist > radius and prev_dist <= radius
+
+    return False

tescmd/triggers/models.py

@@ -0,0 +1,93 @@
+"""Pydantic v2 models for the trigger/subscription system.
+
+Triggers let OpenClaw bots and MCP clients register conditions on
+telemetry fields and receive notifications when they fire.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class TriggerOperator(str, Enum):
+    """Supported comparison operators for trigger conditions."""
+
+    LT = "lt"
+    GT = "gt"
+    LTE = "lte"
+    GTE = "gte"
+    EQ = "eq"
+    NEQ = "neq"
+    CHANGED = "changed"
+    ENTER = "enter"
+    LEAVE = "leave"
+
+
+# Operators that require no threshold value
+_NO_VALUE_OPS = frozenset({TriggerOperator.CHANGED})
+
+# Geofence operators require a dict with lat/lon/radius
+_GEOFENCE_OPS = frozenset({TriggerOperator.ENTER, TriggerOperator.LEAVE})
+
+
+class TriggerCondition(BaseModel):
+    """A single condition that a trigger evaluates.
+
+    For most operators, ``value`` is a numeric or string threshold.
+    For ``changed``, ``value`` is not required.
+    For ``enter``/``leave``, ``value`` is a dict with
+    ``latitude``, ``longitude``, and ``radius_m``.
+    """
+
+    field: str
+    operator: TriggerOperator
+    value: Any = None
+
+    @model_validator(mode="after")
+    def _validate_value_for_operator(self) -> TriggerCondition:
+        op = self.operator
+        if op in _GEOFENCE_OPS:
+            if not isinstance(self.value, dict):
+                raise ValueError(
+                    f"Operator '{op.value}' requires a dict value "
+                    "with latitude, longitude, radius_m"
+                )
+            missing = {"latitude", "longitude", "radius_m"} - set(self.value.keys())
+            if missing:
+                raise ValueError(f"Geofence value missing keys: {', '.join(sorted(missing))}")
+        elif op not in _NO_VALUE_OPS and self.value is None:
+            raise ValueError(f"Operator '{op.value}' requires a 'value' parameter")
+        return self
+
+
+def _make_trigger_id() -> str:
+    """Generate a short hex ID (12 chars from a UUID4)."""
+    return uuid.uuid4().hex[:12]
+
+
+class TriggerDefinition(BaseModel):
+    """A registered trigger with its condition and firing configuration."""
+
+    id: str = Field(default_factory=_make_trigger_id)
+    condition: TriggerCondition
+    once: bool = False
+    cooldown_seconds: float = Field(default=60.0, ge=0)
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+
+class TriggerNotification(BaseModel):
+    """Notification emitted when a trigger fires."""
+
+    trigger_id: str
+    field: str
+    operator: TriggerOperator
+    threshold: Any = None
+    value: Any = None
+    previous_value: Any = None
+    fired_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    vin: str = ""

{tescmd-0.1.2.dist-info → tescmd-0.3.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tescmd
-Version: 0.1.2
+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
@@ -41,21 +46,36 @@ 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'
 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/) -->
-[![License](https://img.shields.io/github/license/oceanswave/tescmd)](LICENSE)
+<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.
 
@@ -68,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 awareness** — setup wizard highlights Fleet Telemetry streaming for up to 97% API 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
@@ -83,51 +107,47 @@ 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
+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.
 
-# List your vehicles
-tescmd vehicle list
+After setup completes, you can start using commands:
 
-# Get full vehicle data snapshot
-tescmd vehicle info
+```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 serve 5YJ3...               # MCP + telemetry TUI dashboard + CSV log
+tescmd serve --no-mcp              # Telemetry-only TUI dashboard
+```
 
-# Check charge status (uses cache — second call is instant)
-tescmd charge status
+Every read command is cached — repeat calls within the TTL window are instant and free.
 
-# Start charging (auto-invalidates cache)
-tescmd charge start --wake
+## Prerequisites
 
-# Climate control
-tescmd climate on --wake
-tescmd climate set 72
+| 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 |
 
-# Lock the car
-tescmd security lock --wake
+### Self-Hosting with Tailscale (No Domain Required)
 
-# Enroll your key on a vehicle (required for signed commands)
-tescmd key enroll 5YJ3E1EA1NF000000
+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.
 
-# Cache management
-tescmd cache status
-tescmd cache clear
+```bash
+# Install Tailscale, enable Funnel in your tailnet ACL, then:
+tescmd setup   # wizard auto-detects Tailscale and offers it as the hosting method
 ```
 
-## Prerequisites
-
-The following tools should be installed and authenticated before running `tescmd 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 | Secure remote access to vehicles via Fleet Telemetry | `tailscale login` |
+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.
 
-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.
+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
 
@@ -210,7 +230,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 |
@@ -224,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 |
 
@@ -305,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 |
 
@@ -355,6 +378,50 @@ 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
+# Full-screen TUI with live telemetry + MCP server
+tescmd serve 5YJ3...
+
+# Telemetry-only mode (full-screen TUI, no MCP)
+tescmd serve 5YJ3... --no-mcp
+
+# Select field presets
+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 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
+
+# Legacy Rich Live dashboard
+tescmd serve 5YJ3... --legacy-dashboard
+```
+
+**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
+
+| 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 +516,20 @@ 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
+- [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
+- [Development](docs/development.md) — contribution guidelines, testing, linting
+
 ## Changelog
 
 See [CHANGELOG.md](CHANGELOG.md) for release history.
@@ -456,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>