sphyr-sdk 2.0.0b1__tar.gz

sphyr_sdk-2.0.0b1/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: sphyr-sdk
+Version: 2.0.0b1
+Summary: Python SDK for Sphyr Agent Guard
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1.0,>=0.28.0
+Requires-Dist: pydantic<3.0,>=2.13.0
+Requires-Dist: cryptography<49.0,>=42.0
+Requires-Dist: requests<3.0,>=2.32
+Provides-Extra: instrument
+Requires-Dist: requests<3.0,>=2.32; extra == "instrument"
+Provides-Extra: dev
+Requires-Dist: pytest-cov<8.0,>=7.0; extra == "dev"
+Requires-Dist: freezegun<2.0,>=1.5; extra == "dev"
+Requires-Dist: pytest-asyncio<2.0,>=0.25; extra == "dev"
+Requires-Dist: requests<3.0,>=2.32; extra == "dev"
+
+# sphyr-sdk
+
+Python SDK for [Sphyr Agent Guard](https://sphyr.io). Adds verifiable, auditable security checks to every outbound agent request.
+
+## Quick-Start
+
+### 1. Install
+
+```bash
+pip install sphyr-sdk
+```
+
+### 2. Sign in (no key copy-paste)
+
+```bash
+npx @sphyr/cli login
+```
+
+Opens your browser, signs you in via the device flow, and writes your credential to
+`~/.sphyr/config.json` (owner-only `0600`). After this, the SDK picks it up automatically.
+
+> No Node/npx on your machine? Run `python -m sphyr_sdk login` for the same device-flow sign-in.
+>
+> Setting up an IDE-based agent (Claude Desktop, Cursor, etc.) instead? Use
+> `npx @sphyr/cli guard init` — it signs you in **and** writes the MCP server config for each
+> detected IDE.
+
+### 3. Protect every outbound call (recommended — install and forget)
+
+```python
+from sphyr_sdk import auto_instrument
+
+# One line at startup. After this, every requests / httpx call is signed, scanned,
+# and audited through Sphyr automatically — no per-call wrapping.
+report = auto_instrument()
+print(report.requests.status)  # 'patched' or 'not_installed'
+print(report.httpx.status)     # 'patched' or 'not_installed'
+```
+
+> **Breaking change (v0.27.0):** `auto_instrument()` now returns a `PatchReport` (per-lib
+> instrumentation status) instead of a `SphyrClient`. Callers that did
+> `client = auto_instrument(...)` must update — use `SphyrClient(...).instrument()` directly
+> if you need a client reference for later teardown.
+>
+> **The SDK does nothing until you call `auto_instrument()`** — importing the package alone is not protective.
+>
+> **Fail-closed by default:** if the Sphyr gateway is unreachable, instrumented requests raise
+> `SphyrNetworkError` rather than leaving unscreened. Pass `auto_instrument(fail_closed=False)` to
+> prioritize app uptime over strict enforcement.
+
+Credentials resolve in order: **explicit args → `SPHYR_CREDENTIAL` env var →
+`~/.sphyr/config.json`**. So `auto_instrument()` with no arguments works after `npx @sphyr/cli login`.
+
+### Works with your agent framework — automatically
+
+`auto_instrument()` patches the underlying HTTP layer (`requests` and `httpx`), so any library or
+framework that makes outbound calls through them is signed, scanned, and audited the moment you call
+it — **no adapters, no per-framework wiring**. That includes the OpenAI SDK, the Anthropic SDK,
+LangChain / LangGraph, CrewAI, AutoGen, and LlamaIndex (all of which use `requests`/`httpx` under the
+hood). Call `auto_instrument()` once at process start, before your agent makes its first request.
+
+### Manual / advanced — wrap calls yourself
+
+```python
+import asyncio
+
+from sphyr_sdk.client import AsyncSphyrClient
+from sphyr_sdk.errors import SphyrError
+
+
+async def main() -> None:
+    client = AsyncSphyrClient()  # resolves creds from env / ~/.sphyr/config.json
+    try:
+        result = await client.call({"url": "https://api.example.com/data", "mthd": "GET"})
+        print(result)
+    except SphyrError as err:
+        print(err.code, err.retryable, err.docs_url)
+
+
+asyncio.run(main())
+```
+
+### 4. Add the MCP Server (Claude Desktop, Cursor, etc.)
+
+**Recommended — one command:**
+
+```bash
+npx @sphyr/cli guard init
+```
+
+This opens your browser, signs you in, and writes per-IDE configs automatically — including the `SPHYR_CREDENTIAL` env var. MCP server setup uses the Node-based `sphyr-mcp` binary from `@sphyr/sdk`.
+
+See [sphyr.io/docs/mcp](https://sphyr.io/docs/mcp) for per-client setup (Claude Desktop, Claude Code CLI, Cursor, Antigravity, OpenAI Codex).
+
+Full reference (retry policy, custom transport, timeout config, error catalog): [sphyr.io/docs](https://sphyr.io/docs)
+
+## What traffic is intercepted (and what is not)
+
+`instrument()` / `auto_instrument()` work by patching specific HTTP client libraries. Traffic from anything else flows **directly to the network, unguarded** — there is no OS-level interception.
+
+| Transport | Intercepted? |
+|---|---|
+| `requests` (Session-based and module-level) | ✅ yes |
+| `httpx` (`Client` and `AsyncClient`) | ✅ yes |
+| `aiohttp` | ❌ no — flows unguarded |
+| `urllib` / `urllib.request` / `http.client` | ❌ no — flows unguarded |
+| `urllib3` (used directly, not via requests) | ❌ no — flows unguarded |
+| `pycurl` / subprocess `curl` | ❌ no — flows unguarded |
+
+If your agent uses an unsupported transport, route those calls through `SphyrClient.call()` explicitly, or switch the agent's HTTP layer to `requests`/`httpx`.
+
+**Local/private traffic exclusions.** To prevent gateway loops and keep local development working, intercepted clients pass traffic to `localhost`, RFC 1918 ranges (`10/8`, `172.16/12`, `192.168/16`), generic link-local (`169.254/16`), and IPv6 ULA/link-local **directly to the real transport, unguarded**. One deliberate exception: the cloud metadata endpoints (`169.254.169.254`, `fd00:ec2::254`) are always routed through the gateway, which blocks and audits the attempt — these are the primary SSRF targets a prompt-injected agent probes.
+
+## Tool Schema Drift Detection
+
+When `SphyrClient.instrument()` is active, the SDK automatically detects changes to an MCP server's `tools/list` response between sessions. The first response per origin sets the baseline; subsequent changes raise `SphyrDriftError` (in `BLOCK` mode) or emit a telemetry event and continue (in `LOG` mode, the default).
+
+```python
+from sphyr_sdk import SphyrClient, SphyrDriftError
+
+try:
+    result = await client.call({"url": "https://mcp.example.com/...", "mthd": "GET"})
+except SphyrDriftError as err:
+    # Tool schema changed unexpectedly — halt and alert
+    print(err.code)  # "TOOL_SCHEMA_DRIFT"
+```
+
+`SphyrDriftError` is also importable from `sdk.agent_guard_utils` for legacy integrations. The enforcement mode (`LOG` or `BLOCK`) is set per API key via `key_flags.tool_drift_mode` in the admin console.
+
+## User-Agent header (custom integrations)
+
+This SDK sends `User-Agent: sphyr-sdk-python/<version>` on every request to the Sphyr gateway. You do not need to do anything to enable this — it is set automatically.
+
+If you are **building a custom MCP client** that talks to the Sphyr gateway directly (i.e. not using this SDK), you must set a `User-Agent` header on your requests. Cloudflare's WAF blocks Python `urllib`'s default `Python-urllib/3.X` User-Agent as a bot — requests fail with HTTP 403 / Error 1010 (`browser_signature_banned`) before they reach the Worker. Any non-empty descriptive value (e.g. `your-app/1.0`) is sufficient.

sphyr_sdk-2.0.0b1/README.md

@@ -0,0 +1,134 @@
+# sphyr-sdk
+
+Python SDK for [Sphyr Agent Guard](https://sphyr.io). Adds verifiable, auditable security checks to every outbound agent request.
+
+## Quick-Start
+
+### 1. Install
+
+```bash
+pip install sphyr-sdk
+```
+
+### 2. Sign in (no key copy-paste)
+
+```bash
+npx @sphyr/cli login
+```
+
+Opens your browser, signs you in via the device flow, and writes your credential to
+`~/.sphyr/config.json` (owner-only `0600`). After this, the SDK picks it up automatically.
+
+> No Node/npx on your machine? Run `python -m sphyr_sdk login` for the same device-flow sign-in.
+>
+> Setting up an IDE-based agent (Claude Desktop, Cursor, etc.) instead? Use
+> `npx @sphyr/cli guard init` — it signs you in **and** writes the MCP server config for each
+> detected IDE.
+
+### 3. Protect every outbound call (recommended — install and forget)
+
+```python
+from sphyr_sdk import auto_instrument
+
+# One line at startup. After this, every requests / httpx call is signed, scanned,
+# and audited through Sphyr automatically — no per-call wrapping.
+report = auto_instrument()
+print(report.requests.status)  # 'patched' or 'not_installed'
+print(report.httpx.status)     # 'patched' or 'not_installed'
+```
+
+> **Breaking change (v0.27.0):** `auto_instrument()` now returns a `PatchReport` (per-lib
+> instrumentation status) instead of a `SphyrClient`. Callers that did
+> `client = auto_instrument(...)` must update — use `SphyrClient(...).instrument()` directly
+> if you need a client reference for later teardown.
+>
+> **The SDK does nothing until you call `auto_instrument()`** — importing the package alone is not protective.
+>
+> **Fail-closed by default:** if the Sphyr gateway is unreachable, instrumented requests raise
+> `SphyrNetworkError` rather than leaving unscreened. Pass `auto_instrument(fail_closed=False)` to
+> prioritize app uptime over strict enforcement.
+
+Credentials resolve in order: **explicit args → `SPHYR_CREDENTIAL` env var →
+`~/.sphyr/config.json`**. So `auto_instrument()` with no arguments works after `npx @sphyr/cli login`.
+
+### Works with your agent framework — automatically
+
+`auto_instrument()` patches the underlying HTTP layer (`requests` and `httpx`), so any library or
+framework that makes outbound calls through them is signed, scanned, and audited the moment you call
+it — **no adapters, no per-framework wiring**. That includes the OpenAI SDK, the Anthropic SDK,
+LangChain / LangGraph, CrewAI, AutoGen, and LlamaIndex (all of which use `requests`/`httpx` under the
+hood). Call `auto_instrument()` once at process start, before your agent makes its first request.
+
+### Manual / advanced — wrap calls yourself
+
+```python
+import asyncio
+
+from sphyr_sdk.client import AsyncSphyrClient
+from sphyr_sdk.errors import SphyrError
+
+
+async def main() -> None:
+    client = AsyncSphyrClient()  # resolves creds from env / ~/.sphyr/config.json
+    try:
+        result = await client.call({"url": "https://api.example.com/data", "mthd": "GET"})
+        print(result)
+    except SphyrError as err:
+        print(err.code, err.retryable, err.docs_url)
+
+
+asyncio.run(main())
+```
+
+### 4. Add the MCP Server (Claude Desktop, Cursor, etc.)
+
+**Recommended — one command:**
+
+```bash
+npx @sphyr/cli guard init
+```
+
+This opens your browser, signs you in, and writes per-IDE configs automatically — including the `SPHYR_CREDENTIAL` env var. MCP server setup uses the Node-based `sphyr-mcp` binary from `@sphyr/sdk`.
+
+See [sphyr.io/docs/mcp](https://sphyr.io/docs/mcp) for per-client setup (Claude Desktop, Claude Code CLI, Cursor, Antigravity, OpenAI Codex).
+
+Full reference (retry policy, custom transport, timeout config, error catalog): [sphyr.io/docs](https://sphyr.io/docs)
+
+## What traffic is intercepted (and what is not)
+
+`instrument()` / `auto_instrument()` work by patching specific HTTP client libraries. Traffic from anything else flows **directly to the network, unguarded** — there is no OS-level interception.
+
+| Transport | Intercepted? |
+|---|---|
+| `requests` (Session-based and module-level) | ✅ yes |
+| `httpx` (`Client` and `AsyncClient`) | ✅ yes |
+| `aiohttp` | ❌ no — flows unguarded |
+| `urllib` / `urllib.request` / `http.client` | ❌ no — flows unguarded |
+| `urllib3` (used directly, not via requests) | ❌ no — flows unguarded |
+| `pycurl` / subprocess `curl` | ❌ no — flows unguarded |
+
+If your agent uses an unsupported transport, route those calls through `SphyrClient.call()` explicitly, or switch the agent's HTTP layer to `requests`/`httpx`.
+
+**Local/private traffic exclusions.** To prevent gateway loops and keep local development working, intercepted clients pass traffic to `localhost`, RFC 1918 ranges (`10/8`, `172.16/12`, `192.168/16`), generic link-local (`169.254/16`), and IPv6 ULA/link-local **directly to the real transport, unguarded**. One deliberate exception: the cloud metadata endpoints (`169.254.169.254`, `fd00:ec2::254`) are always routed through the gateway, which blocks and audits the attempt — these are the primary SSRF targets a prompt-injected agent probes.
+
+## Tool Schema Drift Detection
+
+When `SphyrClient.instrument()` is active, the SDK automatically detects changes to an MCP server's `tools/list` response between sessions. The first response per origin sets the baseline; subsequent changes raise `SphyrDriftError` (in `BLOCK` mode) or emit a telemetry event and continue (in `LOG` mode, the default).
+
+```python
+from sphyr_sdk import SphyrClient, SphyrDriftError
+
+try:
+    result = await client.call({"url": "https://mcp.example.com/...", "mthd": "GET"})
+except SphyrDriftError as err:
+    # Tool schema changed unexpectedly — halt and alert
+    print(err.code)  # "TOOL_SCHEMA_DRIFT"
+```
+
+`SphyrDriftError` is also importable from `sdk.agent_guard_utils` for legacy integrations. The enforcement mode (`LOG` or `BLOCK`) is set per API key via `key_flags.tool_drift_mode` in the admin console.
+
+## User-Agent header (custom integrations)
+
+This SDK sends `User-Agent: sphyr-sdk-python/<version>` on every request to the Sphyr gateway. You do not need to do anything to enable this — it is set automatically.
+
+If you are **building a custom MCP client** that talks to the Sphyr gateway directly (i.e. not using this SDK), you must set a `User-Agent` header on your requests. Cloudflare's WAF blocks Python `urllib`'s default `Python-urllib/3.X` User-Agent as a bot — requests fail with HTTP 403 / Error 1010 (`browser_signature_banned`) before they reach the Worker. Any non-empty descriptive value (e.g. `your-app/1.0`) is sufficient.

sphyr_sdk-2.0.0b1/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sphyr-sdk"
+version = "2.0.0-beta.1"
+description = "Python SDK for Sphyr Agent Guard"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+  "httpx>=0.28.0,<1.0",
+  "pydantic>=2.13.0,<3.0",
+  # Phase 134 D-12: Ed25519 verification for offline denial-proof verify helper.
+  "cryptography>=42.0,<49.0",
+  # requests is mandatory (not an optional extra) so the default `pip install sphyr-sdk`
+  # guarantees auto_instrument() can patch requests — the dominant agent HTTP library.
+  # Previously optional ([instrument] extra); a user who installed without the extra and
+  # relied on the SDK to guard requests calls got a silent no-op. Making it mandatory closes
+  # that gap at the source without a runtime warning. The [instrument] extra is retained below
+  # for backward-compatibility of `pip install sphyr-sdk[instrument]`.
+  "requests>=2.32,<3.0",
+]
+
+[project.optional-dependencies]
+# Retained for backward-compat — requests is now a mandatory dependency (see above).
+instrument = ["requests>=2.32,<3.0"]
+# Dev tooling for coverage (F-009/F-019/F-020) and freezegun timing tests (F-046, plan 92-04 handoff).
+dev = ["pytest-cov>=7.0,<8.0", "freezegun>=1.5,<2.0", "pytest-asyncio>=0.25,<2.0", "requests>=2.32,<3.0"]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["sphyr_sdk*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+# Coverage measurement on every pytest run (F-019 enables branch coverage; fail_under=79 from [tool.coverage.report]).
+addopts = "-q --cov --cov-report=term-missing"
+asyncio_mode = "auto"
+pythonpath = [".", "../.."]
+
+# F-019: enable branch coverage for sdk/python (previously UNMEASURED).
+[tool.coverage.run]
+branch = true
+source = ["sphyr_sdk"]
+
+# F-009: enforce coverage floor per 92-RESEARCH §3 ratchet plan.
+# Floor stays at 79% — proxy.py removal removes the excluded file but the
+# measured core coverage has not been re-baselined yet. Raise after next CI run.
+[tool.coverage.report]
+fail_under = 79
+show_missing = true

sphyr_sdk-2.0.0b1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sphyr_sdk-2.0.0b1/sphyr_sdk/__init__.py

@@ -0,0 +1,150 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Sphyr Agent Guard Contributors
+
+"""Python SDK package for Sphyr Agent Guard."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, Optional
+
+from sphyr_sdk.client import SphyrClient, AsyncSphyrClient
+from sphyr_sdk._session_models import AuditSessResponse
+from sphyr_sdk.errors import (
+    SphyrError,
+    SphyrAuthError,
+    SphyrRateLimitError,
+    SphyrSecurityError,
+    SphyrDriftError,
+    SphyrNetworkError,
+    SphyrBillingError,
+    SphyrConfigError,
+    SphyrRequestError,
+    DegradedModeError,
+    make_sphyr_error,
+)
+from sphyr_sdk.verify import verify_denial_proof_locally, VerifyResult
+
+# _signing is intentionally excluded — it is an internal primitive, not public API.
+
+
+@dataclass
+class LibStatus:
+    """Per-library instrumentation status returned by auto_instrument().
+
+    status:
+        'patched'       — the HTTP library was found and successfully patched.
+        'not_installed' — the library is not installed in this environment.
+    reason:
+        Optional human-readable note (e.g. an edge-case explanation). None in
+        the common cases — 'not_installed' is self-explanatory.
+    """
+
+    status: Literal["patched", "not_installed"]
+    reason: Optional[str] = None
+
+
+@dataclass
+class PatchReport:
+    """Structured report of which HTTP libraries were patched by auto_instrument().
+
+    Breaking change (v0.27.0): auto_instrument() now returns a PatchReport
+    instead of a SphyrClient. Callers that did `client = auto_instrument(...)`
+    must update — uninstrumentation is via the module-level sentinels in
+    sphyr_sdk._instrument, or by constructing a SphyrClient and calling
+    .uninstrument() directly.
+
+    Attributes:
+        requests: Status of the `requests` library patch.
+        httpx:    Status of the `httpx` library patch (covers both sync and async clients).
+    """
+
+    requests: LibStatus
+    httpx: LibStatus
+
+
+def auto_instrument(
+    *,
+    credential: Optional[str] = None,
+    mcp_url: Optional[str] = None,
+    fail_closed: bool = True,
+) -> PatchReport:
+    """One-line Sphyr setup: patches all HTTP libraries and returns a PatchReport.
+
+    Mirrors the sentry_sdk.init() pattern. After this call, every outbound
+    request via `requests` or `httpx` is automatically signed, scanned, and
+    audited through Sphyr.
+
+    Credential resolves inside SphyrClient with precedence: explicit credential >
+    SPHYR_CREDENTIAL env > ~/.sphyr/config.json. So `auto_instrument()` with no
+    arguments works after `npx sphyr login`.
+
+    Args:
+        credential: Single sphyr_v1_<keyId>.<signingSecret> credential string.
+                    Optional — falls back to SPHYR_CREDENTIAL env, then config file.
+        mcp_url: Sphyr MCP gateway URL. Optional — falls back to SPHYR_MCP_URL, config file, then public endpoint.
+        fail_closed: If True (default), raise SphyrNetworkError when the gateway is
+                     unreachable so nothing leaves unscreened. Set False to log an
+                     UNGUARDED warning and pass through (uptime over strict enforcement).
+
+    Returns:
+        PatchReport — per-library instrumentation status. Use to confirm which
+        HTTP libraries were patched. The internal SphyrClient is NOT returned;
+        use SphyrClient(...).instrument() directly if you need a client reference.
+
+    Example:
+        >>> from sphyr_sdk import auto_instrument
+        >>> report = auto_instrument(
+        ...     credential=os.environ["SPHYR_CREDENTIAL"],
+        ... )
+        >>> print(report.requests.status)  # 'patched' or 'not_installed'
+        >>> # Every requests.get() / httpx.get() call is now signed automatically.
+    """
+    # WR-05: warn if instrumentation is already active so silent credential-rotation
+    # bugs are detectable. Lazy import mirrors the pattern below.
+    import warnings  # noqa: PLC0415
+    from sphyr_sdk import _instrument as _instr_check  # noqa: PLC0415
+    if _instr_check._orig_session_init is not None or _instr_check._orig_client_init is not None:
+        warnings.warn(
+            "[sphyr] auto_instrument() called while instrumentation is already active. "
+            "New credentials ignored — call uninstrument() first if you need to re-instrument.",
+            stacklevel=2,
+        )
+    client = SphyrClient(credential=credential, mcp_url=mcp_url)
+    client.instrument(fail_closed=fail_closed)
+    # Query actual module-level sentinels to determine which libs were patched.
+    # Lazy import avoids top-level import cycle (client.py also imports _instrument lazily).
+    from sphyr_sdk import _instrument  # noqa: PLC0415
+    req_status: Literal["patched", "not_installed"] = (
+        "patched" if _instrument._orig_session_init is not None else "not_installed"
+    )
+    httpx_status: Literal["patched", "not_installed"] = (
+        "patched" if _instrument._orig_client_init is not None else "not_installed"
+    )
+    return PatchReport(
+        requests=LibStatus(status=req_status),
+        httpx=LibStatus(status=httpx_status),
+    )
+
+
+__all__ = [
+    "SphyrClient",
+    "AsyncSphyrClient",
+    "AuditSessResponse",
+    "SphyrError",
+    "SphyrAuthError",
+    "SphyrRateLimitError",
+    "SphyrSecurityError",
+    "SphyrDriftError",
+    "SphyrNetworkError",
+    "SphyrBillingError",
+    "SphyrConfigError",
+    "SphyrRequestError",
+    "DegradedModeError",
+    "make_sphyr_error",
+    "auto_instrument",
+    "verify_denial_proof_locally",
+    "VerifyResult",
+    "LibStatus",
+    "PatchReport",
+]

sphyr_sdk-2.0.0b1/sphyr_sdk/__main__.py

@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Sphyr Agent Guard Contributors
+
+"""Argparse dispatcher for `python -m sphyr_sdk`.
+
+Subcommands (D-02):
+  login   — device-flow login via RFC 8628, writes ~/.sphyr/config.json
+  verify  — connectivity verify: audit_sess handshake + agent_guard_up round-trip
+
+Usage:
+  python -m sphyr_sdk login
+  python -m sphyr_sdk verify [--json]
+
+No subcommand or unknown subcommand prints help and exits 1 (Pitfall 8).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+def main() -> None:
+    """Parse argv and dispatch to the appropriate subcommand."""
+    parser = argparse.ArgumentParser(
+        prog="python -m sphyr_sdk",
+        description="Sphyr Agent Guard SDK CLI",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    # login subcommand
+    subparsers.add_parser(
+        "login",
+        help="Device-flow login — opens a browser and writes ~/.sphyr/config.json",
+    )
+
+    # verify subcommand
+    verify_parser = subparsers.add_parser(
+        "verify",
+        help="Verify gateway connectivity (audit_sess handshake + agent_guard_up)",
+    )
+    verify_parser.add_argument(
+        "--json",
+        action="store_true",
+        default=False,
+        help="Emit machine-readable JSON output matching the TS sphyr guard verify schema",
+    )
+
+    args = parser.parse_args()
+
+    # Pitfall 8: no subcommand → print help and exit 1
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+
+    if args.command == "login":
+        from sphyr_sdk._login import run_login_command  # noqa: PLC0415
+        sys.exit(run_login_command())
+
+    if args.command == "verify":
+        from sphyr_sdk._connectivity import run_verify_command  # noqa: PLC0415
+        sys.exit(run_verify_command(json_mode=getattr(args, "json", False)))
+
+    # Unknown command (defensive — argparse should handle most cases above)
+    parser.print_help()
+    sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()