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

tescmd/openclaw/config.py

@@ -12,8 +12,16 @@ from pydantic import BaseModel, Field
 class NodeCapabilities(BaseModel):
     """Advertised capabilities for the OpenClaw node role.
 
+    The node advertises only two commands to the gateway:
+
+    - ``location.get`` (read) — standard node location capability
+    - ``system.run`` (write) — single entry point; the gateway routes all
+      invocations through this method and the internal
+      :class:`~tescmd.openclaw.dispatcher.CommandDispatcher` fans out to
+      the full set of 34 handlers.
+
     Maps to the gateway connect schema fields:
-    - ``caps``: broad capability categories (e.g. ``"location"``, ``"climate"``)
+    - ``caps``: broad capability categories (``"location"``, ``"system"``)
     - ``commands``: specific method names the node can handle
     - ``permissions``: per-command permission booleans
 
@@ -23,39 +31,8 @@ class NodeCapabilities(BaseModel):
 
     reads: list[str] = [
         "location.get",
-        "battery.get",
-        "temperature.get",
-        "speed.get",
-        "charge_state.get",
-        "security.get",
-        # Trigger reads
-        "trigger.list",
-        "trigger.poll",
     ]
     writes: list[str] = [
-        "door.lock",
-        "door.unlock",
-        "climate.on",
-        "climate.off",
-        "climate.set_temp",
-        "charge.start",
-        "charge.stop",
-        "charge.set_limit",
-        "trunk.open",
-        "frunk.open",
-        "flash_lights",
-        "honk_horn",
-        "sentry.on",
-        "sentry.off",
-        # Trigger writes
-        "trigger.create",
-        "trigger.delete",
-        # Convenience trigger aliases
-        "cabin_temp.trigger",
-        "outside_temp.trigger",
-        "battery.trigger",
-        "location.trigger",
-        # Meta-dispatch
         "system.run",
     ]
 

tescmd/openclaw/dispatcher.py

@@ -424,13 +424,21 @@ class CommandDispatcher:
 
         Accepts both OpenClaw-style (``door.lock``) and API-style
         (``door_lock``) method names via :data:`_METHOD_ALIASES`.
+
+        The target method can be specified as ``method`` or ``command``
+        (the latter mirrors the gateway protocol's field name).
         """
-        method = params.get("method", "")
+        raw = params.get("method", "") or params.get("command", "")
+        # Normalize: bots may send a list like ["door.lock"] instead of a string
+        if isinstance(raw, list):
+            raw = raw[0] if raw else ""
+        method = str(raw).strip() if raw else ""
         if not method:
-            raise ValueError("system.run requires 'method' parameter")
+            raise ValueError("system.run requires 'method' (or 'command') parameter")
         resolved = _METHOD_ALIASES.get(method, method)
         if resolved == "system.run":
             raise ValueError("system.run cannot invoke itself")
+        logger.info("system.run → %s", resolved)
         inner_params = params.get("params", {})
         result = await self.dispatch({"method": resolved, "params": inner_params})
         if result is None:

tescmd/openclaw/gateway.py

@@ -229,6 +229,7 @@ class GatewayClient:
         model_identifier: str | None = None,
         capabilities: NodeCapabilities | None = None,
         on_request: Callable[[dict[str, Any]], Awaitable[dict[str, Any] | None]] | None = None,
+        on_reconnect: Callable[[], Awaitable[None]] | None = None,
     ) -> None:
         self._url = url
         self._token = token
@@ -243,6 +244,7 @@ class GatewayClient:
         self._model_identifier = model_identifier or "tescmd"
         self._capabilities = capabilities
         self._on_request = on_request
+        self._on_reconnect = on_reconnect
         self._ws: ClientConnection | None = None
         self._connected = False
         self._send_count = 0
@@ -280,8 +282,21 @@ class GatewayClient:
         so gateways that enforce authentication at the transport layer
         accept the connection before the OpenClaw handshake begins.
 
+        If a receive loop is already running (e.g. from a previous
+        connection or a concurrent reconnect attempt), it is cancelled
+        before establishing the new connection to prevent duplicate
+        ``recv()`` calls on the same WebSocket.
+
         Raises :class:`GatewayConnectionError` on failure.
         """
+        import contextlib
+
+        if self._recv_task is not None and not self._recv_task.done():
+            self._recv_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._recv_task
+            self._recv_task = None
+
         await self._establish_connection()
 
         if self._on_request is not None:
@@ -510,6 +525,12 @@ class GatewayClient:
                 logger.error("Reconnection failed — receive loop exiting")
                 break
 
+            if self._on_reconnect is not None:
+                try:
+                    await self._on_reconnect()
+                except Exception:
+                    logger.warning("on_reconnect callback failed", exc_info=True)
+
     async def _try_reconnect(self) -> bool:
         """Attempt to re-establish the gateway connection with exponential backoff.
 
@@ -531,7 +552,6 @@ class GatewayClient:
         invoke_id = payload.get("id", "")
         command = payload.get("command", "")
         params_json = payload.get("paramsJSON", "{}")
-        logger.info("Invoke request: id=%s command=%s", invoke_id, command)
 
         if not self._on_request:
             await self._send_invoke_result(invoke_id, ok=False, error="no handler configured")
@@ -550,6 +570,18 @@ class GatewayClient:
             )
             params = {}
 
+        # Log with the real command name — for system.run, peek at the
+        # inner method so the activity log shows what's actually invoked.
+        if command == "system.run":
+            inner = params.get("method", "") or params.get("command", "")
+            if isinstance(inner, list):
+                inner = inner[0] if inner else ""
+            logger.info(
+                "Invoke request: id=%s command=%s (via system.run)", invoke_id, inner or "?"
+            )
+        else:
+            logger.info("Invoke request: id=%s command=%s", invoke_id, command)
+
         # Build the message dict the dispatcher expects
         dispatch_msg: dict[str, Any] = {
             "method": command,

tescmd/telemetry/tailscale.py

@@ -112,27 +112,86 @@ class TailscaleManager:
     # Serve management (static file hosting)
     # ------------------------------------------------------------------
 
-    async def start_serve(self, path: str, target: str | Path) -> None:
+    async def start_serve(
+        self,
+        path: str,
+        target: str | Path,
+        *,
+        port: int = 443,
+        funnel: bool = False,
+    ) -> None:
         """Serve a local directory at a URL path prefix.
 
-        Runs: ``tailscale serve --bg --set-path <path> <target>``
+        Runs: ``tailscale serve --bg [--https=<port>] [--funnel] --set-path <path> <target>``
+
+        When *port* differs from 443 the ``--https=<port>`` flag is added so
+        Tailscale listens on the requested HTTPS port.
 
         Args:
             path: URL path prefix (e.g. ``/.well-known/``).
             target: Local directory to serve.
+            port: HTTPS port to serve on (default ``443``).
+            funnel: Also enable Funnel (public access) for this handler.
         """
-        returncode, stdout, stderr = await self._run(
-            "tailscale",
-            "serve",
-            "--bg",
-            "--set-path",
-            path,
-            str(target),
-        )
+        cmd: list[str] = ["tailscale", "serve", "--bg"]
+        if port != 443:
+            cmd.append(f"--https={port}")
+        if funnel:
+            cmd.append("--funnel")
+        cmd.extend(["--set-path", path, str(target)])
+
+        returncode, stdout, stderr = await self._run(*cmd)
         if returncode != 0:
             msg = stderr.strip() or stdout.strip()
             raise TailscaleError(f"Failed to start Tailscale serve: {msg}")
-        logger.info("Tailscale serve started: %s -> %s", path, target)
+        logger.info("Tailscale serve started: %s -> %s (port %d)", path, target, port)
+
+    async def start_proxy(self, local_port: int, *, https_port: int = 443) -> None:
+        """Reverse-proxy an HTTPS port to a local HTTP server.
+
+        Runs: ``tailscale serve --bg [--https=<https_port>] http://127.0.0.1:<local_port>``
+
+        Unlike :meth:`start_serve` (which serves static files via
+        ``--set-path``), this sets up a reverse proxy so Tailscale
+        forwards traffic to a local HTTP server.
+
+        Args:
+            local_port: Port of the local HTTP server to proxy to.
+            https_port: Public-facing HTTPS port (default ``443``).
+        """
+        cmd: list[str] = ["tailscale", "serve", "--bg"]
+        if https_port != 443:
+            cmd.append(f"--https={https_port}")
+        cmd.append(f"http://127.0.0.1:{local_port}")
+
+        returncode, stdout, stderr = await self._run(*cmd)
+        if returncode != 0:
+            msg = stderr.strip() or stdout.strip()
+            raise TailscaleError(f"Failed to start Tailscale proxy: {msg}")
+        logger.info(
+            "Tailscale proxy started: https port %d -> http://127.0.0.1:%d",
+            https_port,
+            local_port,
+        )
+
+    async def stop_proxy(self, *, https_port: int = 443) -> None:
+        """Remove a reverse-proxy serve configuration for an HTTPS port.
+
+        Runs: ``tailscale serve --bg [--https=<https_port>] off``
+        """
+        cmd: list[str] = ["tailscale", "serve", "--bg"]
+        if https_port != 443:
+            cmd.append(f"--https={https_port}")
+        cmd.append("off")
+
+        returncode, stdout, stderr = await self._run(*cmd)
+        if returncode != 0:
+            logger.warning(
+                "Failed to stop Tailscale proxy on port %d (may already be stopped): %s",
+                https_port,
+                stderr.strip() or stdout.strip(),
+            )
+        logger.info("Tailscale proxy stopped for HTTPS port %d", https_port)
 
     async def stop_serve(self, path: str) -> None:
         """Remove a serve handler for a path.
@@ -155,21 +214,24 @@ class TailscaleManager:
             )
         logger.info("Tailscale serve stopped for path: %s", path)
 
-    async def enable_funnel(self) -> None:
-        """Enable Funnel on port 443 (expose all serve handlers publicly).
+    async def enable_funnel(self, port: int = 443) -> None:
+        """Enable Funnel on the given *port* (expose all serve handlers publicly).
 
-        Runs: ``tailscale funnel --bg 443``
+        Runs: ``tailscale funnel --bg <port>``
+
+        Args:
+            port: HTTPS port to expose via Funnel (default ``443``).
         """
         returncode, stdout, stderr = await self._run(
             "tailscale",
             "funnel",
             "--bg",
-            "443",
+            str(port),
         )
         if returncode != 0:
             msg = stderr.strip() or stdout.strip()
             raise TailscaleError(f"Failed to enable Tailscale Funnel: {msg}")
-        logger.info("Tailscale Funnel enabled on port 443")
+        logger.info("Tailscale Funnel enabled on port %d", port)
 
     # ------------------------------------------------------------------
     # Funnel management (port proxying for telemetry)

tescmd/triggers/models.py

@@ -8,13 +8,13 @@ from __future__ import annotations
 
 import uuid
 from datetime import UTC, datetime
-from enum import Enum
+from enum import StrEnum
 from typing import Any
 
 from pydantic import BaseModel, Field, model_validator
 
 
-class TriggerOperator(str, Enum):
+class TriggerOperator(StrEnum):
     """Supported comparison operators for trigger conditions."""
 
     LT = "lt"

tescmd-0.5.0.dist-info/METADATA

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