plexus-python 0.2.0__tar.gz → 0.4.1__tar.gz

{plexus_python-0.2.0 → plexus_python-0.4.1}/AGENTS.md

@@ -4,11 +4,11 @@ Machine-readable interface for AI assistants and automation scripts.
 
 ## Environment Variables
 
-| Variable                | Description                                  | Default                          |
-| ----------------------- | -------------------------------------------- | -------------------------------- |
-| `PLEXUS_API_KEY`        | API key for authentication (required)        | none                             |
-| `PLEXUS_GATEWAY_URL`    | Gateway HTTP ingest URL                      | `https://plexus-gateway.fly.dev` |
-| `PLEXUS_GATEWAY_WS_URL` | Gateway WebSocket URL                        | `wss://plexus-gateway.fly.dev`   |
+| Variable                | Description                           | Default                          |
+| ----------------------- | ------------------------------------- | -------------------------------- |
+| `PLEXUS_API_KEY`        | API key for authentication (required) | none                             |
+| `PLEXUS_GATEWAY_URL`    | Gateway HTTP ingest URL               | `https://plexus-gateway.fly.dev` |
+| `PLEXUS_GATEWAY_WS_URL` | Gateway WebSocket URL                 | `wss://plexus-gateway.fly.dev`   |
 
 ## CLI Commands
 
@@ -48,21 +48,6 @@ px.send_batch([
 px = Plexus(api_key="plx_xxxxx", persistent_buffer=True)
 ```
 
-## Project Structure
-
-```
-plexus/
-├── cli.py          # CLI entry point (click commands)
-├── tui.py          # Live terminal dashboard (Rich)
-├── client.py       # Plexus HTTP client (thin SDK)
-├── connector.py    # WebSocket daemon
-├── config.py       # Config file + env var management
-├── detect.py       # Hardware auto-detection
-├── deps.py         # Dependency helpers
-├── sensors/        # I2C sensor drivers + SensorHub
-└── adapters/       # Protocol adapters: CAN, MAVLink, MQTT, Modbus, OPC-UA, BLE, Serial
-```
-
 ## Key Conventions
 
 - Config lives in `~/.plexus/config.json`

{plexus_python-0.2.0 → plexus_python-0.4.1}/API.md

@@ -152,34 +152,36 @@ For real-time UI-controlled streaming, devices connect via WebSocket.
 
 ### Device Authentication
 
-Devices authenticate using an API key:
+Devices authenticate using an API key. The `source_id` in the request is the device's *desired* name; the server may return a different, auto-suffixed name in the `authenticated` frame if the desired name is already claimed by another device (see [Device identity](../README.md#device-identity) in the README).
 
 ```json
 // Device → Server
 {
   "type": "device_auth",
   "api_key": "plx_xxxxx",
-  "source_id": "my-device-001",
-  "platform": "Linux",
-  "sensors": [
-    {
-      "name": "MPU6050",
-      "description": "6-axis IMU",
-      "metrics": ["accel_x", "accel_y", "accel_z", "gyro_x", "gyro_y", "gyro_z"],
-      "sample_rate": 100,
-      "prefix": "",
-      "available": true
-    }
-  ]
+  "source_id": "drone-01",
+  "install_id": "c9f2e0b46f4a4f6a8c3e1d5b0a2e7f91",
+  "platform": "python-sdk",
+  "agent_version": "0.3.1"
 }
 
 // Server → Device
 {
   "type": "authenticated",
-  "source_id": "my-device-001"
+  "source_id": "drone-01"
+}
+
+// Server → Device (collision case)
+{
+  "type": "authenticated",
+  "source_id": "drone-01_2"
 }
 ```
 
+The SDK **adopts** whatever `source_id` the server returns and uses it for all subsequent frames, heartbeats, and reconnects. It also persists the assigned name locally so reconnects go straight to the claimed slot.
+
+`install_id` is a stable per-installation UUID, generated on the device's first run and saved to `~/.plexus/config.json`. It lets the server distinguish a rebooting device from a new device trying to claim an existing name. Legacy SDKs that omit `install_id` continue to work as before (the server passes the declared `source_id` through unchanged).
+
 ### Message Types (Dashboard → Device)
 
 | Type            | Description                          |

plexus_python-0.4.1/CHANGELOG.md

@@ -0,0 +1,110 @@
+# Changelog
+
+## [0.4.1] - 2026-04-27 - CI fixes for 0.4.0
+
+### Fixed
+
+- `plexus/cli.py` — drop a stray `f` prefix on a non-interpolated string
+  that ruff (`F541`) caught in CI.
+- `tests/test_retry.py::test_concurrent_sends` — move `patch.object` out
+  of the per-thread closure. `mock.patch.object` mutates instance
+  attributes and is not thread-safe; under 20 concurrent threads the
+  state would leak and surface as a spurious `AttributeError` on Python
+  3.8.
+
+## [0.4.0] - 2026-04-27 - Stable device identity + CLI
+
+The gateway is now authoritative for a device's `source_id`. The SDK sends a
+locally-generated `install_id` in the auth frame; the gateway atomically
+claims `(org, source_id)` and, if the desired name is already owned by a
+different install, returns an auto-suffixed name (`drone-01` → `drone-01_2`
+→ `drone-01_3`…) in the `authenticated` frame. The SDK adopts and persists
+the assigned name so subsequent reconnects are stable.
+
+This fixes the silent stream-merging that happened when cloned SD-card
+images shared a hostname or when two operators picked the same name.
+
+### Added
+
+- `plexus init` (alias `plexus login`) — fly.io / vercel-style browser auth
+  flow. Spins up a localhost listener, opens `${PLEXUS_ENDPOINT}/auth/cli`
+  with a state-protected callback, and persists the issued key to
+  `~/.plexus/config.json`. Console script registered in `pyproject.toml`
+  (`plexus = "plexus.cli:main"`); stdlib-only, no new runtime deps.
+- `plexus.config.get_install_id()` — lazy per-installation UUID, persisted
+  to `~/.plexus/config.json`. **Not** written by `setup.sh`: it's minted by
+  the SDK on first run so pre-baked images get distinct IDs per boot.
+- `PLEXUS_INSTALL_ID` env var — override for `get_install_id()` so
+  ephemeral containers (Fly machines, k8s pods, CI runners) can pin a
+  stable identity across restarts when the config filesystem is ephemeral.
+  Without this, every redeploy gets a fresh UUID and the gateway
+  auto-suffixes the source_id.
+- `plexus.config.set_source_id()` — persist the gateway-assigned name after
+  auto-suffix resolution.
+- `WebSocketTransport(install_id=..., on_source_id_assigned=...)` — the
+  transport sends `install_id` in the `device_auth` frame and invokes the
+  callback whenever the gateway returns a different `source_id` than
+  requested.
+
+### Changed
+
+- `WebSocketTransport` now reads the `source_id` back from the
+  `authenticated` frame and updates `self.source_id` in place if the gateway
+  auto-suffixed. The rename is logged at INFO level on first occurrence.
+- `Plexus` wires `install_id` into the transport and persists the assigned
+  `source_id` to config on rename.
+- `scripts/setup.sh` — `--name` is **required**. The hostname fallback is
+  removed (it was the main source of cloned-image collisions). In a TTY the
+  script prompts interactively; in non-TTY it exits with an error. Names are
+  validated against `^[a-z0-9][a-z0-9_-]{1,62}$`. Stale `plexus start` /
+  `plexus reset` hints were dropped.
+
+### Wire-protocol (compatible)
+
+- `device_auth` frame gains an optional `install_id` field. The gateway
+  treats a missing `install_id` as legacy pass-through, so older SDKs and
+  the C SDK continue to work unchanged.
+
+## [0.3.0] - WebSocket transport
+
+Adds a wire-compatible WebSocket transport matching the `plexus-c` SDK. WS is now the default; failed sends transparently fall back to `POST /ingest`.
+
+### Added
+
+- `plexus.WebSocketTransport` — connects to `/ws/device` on the gateway. Exchanges the same `device_auth` / `authenticated` / `telemetry` / `heartbeat` / `typed_command` / `command_result` frames as `plexus-c`.
+- `Plexus(transport="ws" | "http")` — defaults to `"ws"`.
+- `Plexus.on_command(name, handler, description=..., params=...)` — register command handlers; automatic `ack`, handler return becomes `result`, exceptions become `error`.
+- `Plexus.close()` — stops the WebSocket thread.
+- Runtime dep: `websocket-client>=1.7`.
+- Tests: `tests/test_ws.py` (auth handshake, telemetry, command roundtrip, error paths).
+
+## [0.2.0] - Thin SDK rewrite
+
+Breaking. `plexus-python` is now just the thin client — no agent, adapters, sensors, CLI, or TUI. The package is 886 lines with one runtime dependency (`requests`). Protocol integrations (MAVLink, CAN, MQTT, Modbus, OPC-UA, BLE, I2C sensors) now live as standalone recipes in `examples/`, using the upstream library directly (`pymavlink`, `python-can`, `paho-mqtt`, etc.) plus `px.send()`.
+
+### Added
+
+- 5 runnable example scripts: `basic.py`, `mavlink.py`, `can.py`, `mqtt.py`, `i2c_bme280.py`
+
+### Removed
+
+- `plexus/adapters/` (MAVLink, CAN, MQTT, Modbus, OPC-UA, BLE, Serial — use the upstream lib directly)
+- `plexus/sensors/` (I2C drivers + auto-detect — use Adafruit CircuitPython or smbus2 directly)
+- `plexus/cameras/` (frame upload — out of scope)
+- `plexus/cli.py`, `plexus/connector.py`, `plexus/streaming.py`, `plexus/detect.py`, `plexus/tui.py`, `plexus/deps.py`
+- `plexus` console script, `python -m plexus`
+- Extras: `[sensors]`, `[system]`, `[tui]`, `[mqtt]`, `[can]`, `[mavlink]`, `[modbus]`, `[opcua]`, `[ble]`, `[serial]`, `[ros]`, `[camera]`, `[picamera]`, `[all]`
+- Runtime deps: `click`, `websockets`
+
+### Changed
+
+- Default ingest endpoint points directly at the Plexus gateway (`https://plexus-gateway.fly.dev/ingest`), not the Next.js app proxy
+- Client raises `ValueError` clearly when no API key is available, instead of invoking a login flow
+
+## [0.1.0] - Initial release
+
+- `Plexus` thin client for HTTP ingest
+- `plexus start` daemon with WebSocket streaming
+- Protocol adapters: MAVLink, CAN, MQTT, Modbus, OPC-UA, Serial, BLE
+- I2C sensor auto-detection and drivers
+- Store-and-forward buffering (SQLite)

{plexus_python-0.2.0 → plexus_python-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plexus-python
-Version: 0.2.0
+Version: 0.4.1
 Summary: Thin Python SDK for Plexus — send telemetry in one line
 Project-URL: Homepage, https://plexus.dev
 Project-URL: Documentation, https://docs.plexus.dev
@@ -24,10 +24,12 @@ Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: System :: Hardware
 Requires-Python: >=3.8
 Requires-Dist: requests>=2.28.0
+Requires-Dist: websocket-client>=1.7
 Provides-Extra: dev
 Requires-Dist: pytest; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: websockets>=12; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # plexus-python
@@ -52,6 +54,21 @@ px.send("temperature", 72.5)
 
 Get an API key at [app.plexus.company](https://app.plexus.company) → Devices → Add Device.
 
+## Device identity
+
+Every device needs a unique `source_id`. The recommended way to set one on a real host is the bootstrap script, which requires a device name up front:
+
+```bash
+curl -sL https://app.plexus.company/setup | bash -s -- \
+  --key plx_xxx --name drone-01
+```
+
+The name must match `^[a-z0-9][a-z0-9_-]{1,62}$`. `setup.sh` refuses to run without `--name` (or without a TTY to prompt for one) — this is deliberate, because the previous `hostname` fallback silently merged telemetry from cloned SD-card images that all booted as `raspberrypi`.
+
+**If two devices end up requesting the same name**, the gateway auto-suffixes: the first connection gets `drone-01`, the second gets `drone-01_2`, the third `drone-01_3`, and so on. The SDK logs the rename at INFO and persists the assigned name to `~/.plexus/config.json` so the device keeps its identity across reboots. Under the hood, a per-installation UUID (`install_id`, lazily generated on first run) is what lets the gateway tell "same device reconnecting" from "different device claiming the same name."
+
+In normal code, you usually just pass `source_id=...` explicitly to `Plexus(...)` and never have to think about it.
+
 ## Usage
 
 ```python
@@ -119,13 +136,47 @@ px.buffer_size()
 px.flush_buffer()
 ```
 
+## Transport
+
+By default the SDK connects over a **WebSocket** to `/ws/device` on the gateway — same wire protocol as the C SDK. This gives you:
+
+- lower-latency streaming of telemetry,
+- live command delivery from the UI / API to the device.
+
+If the socket is unavailable, sends transparently fall back to `POST /ingest` so no data is lost.
+
+```python
+# default — ws with http fallback
+px = Plexus()
+
+# force http (legacy)
+px = Plexus(transport="http")
+```
+
+### Handling commands
+
+Register a handler before the first `send()` so the command is advertised in the auth frame:
+
+```python
+def reboot(name, params):
+    delay = params.get("delay_s", 0)
+    # ... reboot logic ...
+    return {"ok": True, "delay": delay}
+
+px = Plexus()
+px.on_command("reboot", reboot, description="reboot the device")
+px.send("temperature", 72.5)   # opens the socket, waits for auth
+```
+
+The SDK sends an `ack` frame before invoking the handler, then a `result` frame with whatever the handler returns (or an `error` frame if it raises).
+
 ## Environment Variables
 
 | Variable                | Description                  | Default                          |
 | ----------------------- | ---------------------------- | -------------------------------- |
 | `PLEXUS_API_KEY`        | API key (required)           | none                             |
 | `PLEXUS_GATEWAY_URL`    | HTTP ingest URL              | `https://plexus-gateway.fly.dev` |
-| `PLEXUS_GATEWAY_WS_URL` | WebSocket URL (unused in SDK, for compatibility) | `wss://plexus-gateway.fly.dev` |
+| `PLEXUS_GATEWAY_WS_URL` | WebSocket URL              | `wss://plexus-gateway.fly.dev`   |
 
 ## Architecture
 

{plexus_python-0.2.0 → plexus_python-0.4.1}/README.md

@@ -20,6 +20,21 @@ px.send("temperature", 72.5)
 
 Get an API key at [app.plexus.company](https://app.plexus.company) → Devices → Add Device.
 
+## Device identity
+
+Every device needs a unique `source_id`. The recommended way to set one on a real host is the bootstrap script, which requires a device name up front:
+
+```bash
+curl -sL https://app.plexus.company/setup | bash -s -- \
+  --key plx_xxx --name drone-01
+```
+
+The name must match `^[a-z0-9][a-z0-9_-]{1,62}$`. `setup.sh` refuses to run without `--name` (or without a TTY to prompt for one) — this is deliberate, because the previous `hostname` fallback silently merged telemetry from cloned SD-card images that all booted as `raspberrypi`.
+
+**If two devices end up requesting the same name**, the gateway auto-suffixes: the first connection gets `drone-01`, the second gets `drone-01_2`, the third `drone-01_3`, and so on. The SDK logs the rename at INFO and persists the assigned name to `~/.plexus/config.json` so the device keeps its identity across reboots. Under the hood, a per-installation UUID (`install_id`, lazily generated on first run) is what lets the gateway tell "same device reconnecting" from "different device claiming the same name."
+
+In normal code, you usually just pass `source_id=...` explicitly to `Plexus(...)` and never have to think about it.
+
 ## Usage
 
 ```python
@@ -87,13 +102,47 @@ px.buffer_size()
 px.flush_buffer()
 ```
 
+## Transport
+
+By default the SDK connects over a **WebSocket** to `/ws/device` on the gateway — same wire protocol as the C SDK. This gives you:
+
+- lower-latency streaming of telemetry,
+- live command delivery from the UI / API to the device.
+
+If the socket is unavailable, sends transparently fall back to `POST /ingest` so no data is lost.
+
+```python
+# default — ws with http fallback
+px = Plexus()
+
+# force http (legacy)
+px = Plexus(transport="http")
+```
+
+### Handling commands
+
+Register a handler before the first `send()` so the command is advertised in the auth frame:
+
+```python
+def reboot(name, params):
+    delay = params.get("delay_s", 0)
+    # ... reboot logic ...
+    return {"ok": True, "delay": delay}
+
+px = Plexus()
+px.on_command("reboot", reboot, description="reboot the device")
+px.send("temperature", 72.5)   # opens the socket, waits for auth
+```
+
+The SDK sends an `ack` frame before invoking the handler, then a `result` frame with whatever the handler returns (or an `error` frame if it raises).
+
 ## Environment Variables
 
 | Variable                | Description                  | Default                          |
 | ----------------------- | ---------------------------- | -------------------------------- |
 | `PLEXUS_API_KEY`        | API key (required)           | none                             |
 | `PLEXUS_GATEWAY_URL`    | HTTP ingest URL              | `https://plexus-gateway.fly.dev` |
-| `PLEXUS_GATEWAY_WS_URL` | WebSocket URL (unused in SDK, for compatibility) | `wss://plexus-gateway.fly.dev` |
+| `PLEXUS_GATEWAY_WS_URL` | WebSocket URL              | `wss://plexus-gateway.fly.dev`   |
 
 ## Architecture
 

{plexus_python-0.2.0 → plexus_python-0.4.1}/SECURITY.md

@@ -22,7 +22,7 @@ Instead, email **support@plexus.company** with:
 ## Supported Versions
 
 | Version | Supported |
-|---------|-----------|
+| ------- | --------- |
 | 0.9.x   | Yes       |
 | < 0.9   | No        |
 

{plexus_python-0.2.0 → plexus_python-0.4.1}/examples/basic.py

@@ -11,7 +11,7 @@ import time
 
 from plexus import Plexus
 
-px = Plexus(source_id="demo-device")
+px = Plexus(api_key="plx_123...", source_id="demo-device")
 
 while True:
     px.send("temperature", 20 + random.random() * 5)

{plexus_python-0.2.0 → plexus_python-0.4.1}/plexus/__init__.py

@@ -8,6 +8,7 @@ Plexus — thin Python SDK for sending telemetry to the Plexus gateway.
 """
 
 from plexus.client import Plexus
+from plexus.ws import WebSocketTransport
 
-__version__ = "0.2.0"
-__all__ = ["Plexus"]
+__version__ = "0.4.1"
+__all__ = ["Plexus", "WebSocketTransport"]

plexus_python-0.4.1/plexus/cli.py

@@ -0,0 +1,275 @@
+"""
+Plexus CLI — `plexus init` style auth, plus a few sibling commands.
+
+Designed to feel like fly.io / vercel CLIs:
+    $ pip install plexus
+    $ plexus init
+    Opening browser to https://app.plexus.company/auth/cli...
+    ✓ Saved API key as cli-<host>. You're set up.
+
+Implementation:
+- Spin up a local HTTP listener on a random free port.
+- Open the browser to /auth/cli with the callback URL embedded.
+- Block until the browser POSTs (well — redirects with key) to /callback.
+- Verify the `state` parameter matches what we generated.
+- Persist the key via plexus.config.save_config; the SDK already reads
+  `~/.plexus/config.json` for `PLEXUS_API_KEY`.
+
+Stdlib only — keep dependency footprint minimal.
+"""
+
+from __future__ import annotations
+
+import argparse
+import http.server
+import secrets
+import socket
+import socketserver
+import sys
+import threading
+import urllib.parse
+import webbrowser
+from typing import Optional
+
+from . import config
+
+
+DEFAULT_TIMEOUT_SECONDS = 300
+SUCCESS_HTML = """<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Plexus CLI</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <style>
+      :root { color-scheme: light dark; }
+      body {
+        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+        display: flex; align-items: center; justify-content: center;
+        min-height: 100vh; margin: 0; background: Canvas; color: CanvasText;
+      }
+      .card {
+        max-width: 360px; padding: 32px; border: 1px solid #8884;
+        border-radius: 12px; text-align: center;
+      }
+      h1 { margin: 0 0 8px; font-size: 18px; }
+      p { margin: 0; color: #888; font-size: 14px; }
+    </style>
+  </head>
+  <body>
+    <div class="card">
+      <h1>You're all set</h1>
+      <p>Return to your terminal &mdash; the CLI has your key.</p>
+    </div>
+  </body>
+</html>""".encode("utf-8")
+
+ERROR_HTML = """<!doctype html>
+<html><head><meta charset="utf-8" /><title>Plexus CLI</title></head>
+<body><pre style="font-family:ui-monospace,monospace;padding:24px">
+Plexus CLI authorization failed. Return to your terminal for details.
+</pre></body></html>""".encode("utf-8")
+
+
+class _CallbackResult:
+    key: Optional[str] = None
+    state: Optional[str] = None
+    error: Optional[str] = None
+
+
+def _pick_free_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+def _make_handler(result: _CallbackResult, expected_state: str, done: threading.Event):
+    class Handler(http.server.BaseHTTPRequestHandler):
+        # Silence the default request log — we don't want CLI noise.
+        def log_message(self, *_args, **_kwargs):  # type: ignore[override]
+            return
+
+        def do_GET(self):  # type: ignore[override]
+            parsed = urllib.parse.urlparse(self.path)
+            if parsed.path != "/callback":
+                self.send_response(404)
+                self.end_headers()
+                return
+
+            params = urllib.parse.parse_qs(parsed.query)
+            got_state = (params.get("state") or [""])[0]
+            got_key = (params.get("key") or [""])[0]
+
+            if got_state != expected_state:
+                result.error = "state mismatch"
+                self.send_response(400)
+                self.send_header("Content-Type", "text/html; charset=utf-8")
+                self.end_headers()
+                self.wfile.write(ERROR_HTML)
+                done.set()
+                return
+
+            if not got_key:
+                result.error = "no key in callback"
+                self.send_response(400)
+                self.send_header("Content-Type", "text/html; charset=utf-8")
+                self.end_headers()
+                self.wfile.write(ERROR_HTML)
+                done.set()
+                return
+
+            result.key = got_key
+            result.state = got_state
+            self.send_response(200)
+            self.send_header("Content-Type", "text/html; charset=utf-8")
+            self.end_headers()
+            self.wfile.write(SUCCESS_HTML)
+            done.set()
+
+    return Handler
+
+
+def _hostname_label() -> str:
+    try:
+        host = socket.gethostname() or "device"
+    except Exception:
+        host = "device"
+    # Strip the trailing .local etc. and clean it for display.
+    safe = host.split(".")[0].lower().replace(" ", "-")
+    return f"cli-{safe}" if safe else "cli"
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    """Open the browser, capture an API key, save it locally."""
+    existing = config.get_api_key()
+    if existing and not args.force:
+        print(
+            "An API key is already configured. "
+            "Re-run with --force to replace it.",
+            file=sys.stderr,
+        )
+        return 1
+
+    endpoint = config.get_endpoint().rstrip("/")
+    state = secrets.token_urlsafe(24)
+    name = args.name or _hostname_label()
+    port = _pick_free_port()
+    callback = f"http://127.0.0.1:{port}/callback"
+
+    auth_url = (
+        f"{endpoint}/auth/cli"
+        f"?state={urllib.parse.quote(state)}"
+        f"&callback={urllib.parse.quote(callback)}"
+        f"&name={urllib.parse.quote(name)}"
+    )
+
+    result = _CallbackResult()
+    done = threading.Event()
+    handler = _make_handler(result, state, done)
+
+    server = socketserver.TCPServer(("127.0.0.1", port), handler)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+
+    try:
+        print(f"Opening {auth_url}")
+        try:
+            webbrowser.open(auth_url, new=1, autoraise=True)
+        except Exception:
+            pass  # User can copy the URL manually.
+
+        print("Waiting for browser confirmation...", flush=True)
+        finished = done.wait(timeout=args.timeout)
+        if not finished:
+            print(
+                f"Timed out after {args.timeout}s. Re-run `plexus init`.",
+                file=sys.stderr,
+            )
+            return 2
+    finally:
+        server.shutdown()
+        server.server_close()
+
+    if result.error or not result.key:
+        print(
+            f"Authorization failed: {result.error or 'no key returned'}",
+            file=sys.stderr,
+        )
+        return 3
+
+    cfg = config.load_config()
+    cfg["api_key"] = result.key
+    config.save_config(cfg)
+    print(f"✓ Saved API key as {name}.")
+    print("  ~/.plexus/config.json")
+    return 0
+
+
+def cmd_logout(_args: argparse.Namespace) -> int:
+    """Forget the locally stored API key."""
+    cfg = config.load_config()
+    if not cfg.get("api_key"):
+        print("Nothing to do — no key on file.")
+        return 0
+    cfg["api_key"] = None
+    config.save_config(cfg)
+    print("✓ Cleared local API key.")
+    return 0
+
+
+def cmd_whoami(_args: argparse.Namespace) -> int:
+    """Print the prefix of the locally stored key + the configured endpoint."""
+    key = config.get_api_key()
+    endpoint = config.get_endpoint()
+    if not key:
+        print("Not signed in. Run `plexus init` to authorize this machine.")
+        return 1
+    masked = f"{key[:8]}…{key[-4:]}" if len(key) > 12 else key
+    print(f"key:      {masked}")
+    print(f"endpoint: {endpoint}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="plexus",
+        description="Plexus CLI — auth, send, query telemetry from your terminal.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    init = sub.add_parser(
+        "init",
+        help="Authorize this machine and save an API key locally.",
+        aliases=["login"],
+    )
+    init.add_argument("--name", help="Label for the issued key (default: cli-<hostname>).")
+    init.add_argument(
+        "--timeout",
+        type=int,
+        default=DEFAULT_TIMEOUT_SECONDS,
+        help="Seconds to wait for the browser callback.",
+    )
+    init.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite an existing local key.",
+    )
+    init.set_defaults(func=cmd_init)
+
+    logout = sub.add_parser("logout", help="Forget the local API key.")
+    logout.set_defaults(func=cmd_logout)
+
+    whoami = sub.add_parser("whoami", help="Show the local credential summary.")
+    whoami.set_defaults(func=cmd_whoami)
+
+    return parser
+
+
+def main(argv: Optional[list] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())