wildedge cli runner

README.md

@@ -26,6 +26,55 @@ client = wildedge.WildEdge(
 )
 ```
 
+## CLI wrapper
+
+Use `wildedge run` to execute an existing Python entrypoint with WildEdge runtime initialization and integration instrumentation enabled before user code starts:
+
+```bash
+wildedge run --dsn "https://<secret>@ingest.wildedge.dev/<key>" -- python app.py
+```
+
+End-to-end CLI wrapper example:
+
+```bash
+WILDEDGE_DSN="https://<secret>@ingest.wildedge.dev/<key>" \
+wildedge run --print-startup-report --integrations timm -- \
+python examples/cli/cli_wrapper_example.py
+```
+
+See `examples/cli/cli_wrapper_example.py` for a script that has no WildEdge SDK calls in user code.
+Use `examples/cli/demo.sh` for a single-script linear flow (sync, doctor, run).
+This demo uses `examples/cli/pyproject.toml`, so dependency management is delegated to `uv`.
+
+Module entrypoints are supported:
+
+```bash
+wildedge run -- python -m your_package.main --arg value
+```
+
+Validate local runtime readiness:
+
+```bash
+wildedge doctor --integrations all
+```
+
+Machine-readable diagnostics:
+
+```bash
+wildedge doctor --format json --integrations all
+```
+
+Optional DSN reachability probe:
+
+```bash
+wildedge doctor --network-check --dsn "https://<secret>@ingest.wildedge.dev/<key>"
+```
+
+Useful run flags:
+- `--strict-integrations`: fail startup if a requested integration cannot be instrumented.
+- `--no-propagate`: do not propagate WildEdge runtime env vars to nested child processes.
+- `--print-startup-report`: print startup diagnostics with per-integration status.
+
 ## Integrations
 
 Call `client.instrument()` to activate auto-tracking for a supported library. Models created afterwards are registered and timed automatically with no changes to existing call sites.

examples/cli/cli_wrapper_example.py

@@ -0,0 +1,17 @@
+"""CLI wrapper example.
+
+Run this example with:
+  export WILDEDGE_DSN="https://<secret>@ingest.wildedge.dev/<key>"
+  ./examples/cli/demo.sh
+"""
+
+import timm
+import torch
+
+model = timm.create_model("resnet18", pretrained=False).eval()
+batch = torch.randn(1, 3, 224, 224)
+
+with torch.inference_mode():
+    output = model(batch)
+
+print("output shape:", tuple(output.shape))

examples/cli/demo.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ -z "${WILDEDGE_DSN:-}" ]]; then
+  echo 'Set WILDEDGE_DSN first, e.g. export WILDEDGE_DSN="https://<secret>@ingest.wildedge.dev/<key>"' >&2
+  exit 1
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_DIR="${SCRIPT_DIR}"
+EXAMPLE_SCRIPT="${PROJECT_DIR}/cli_wrapper_example.py"
+
+cd "${PROJECT_DIR}"
+
+uv sync
+
+uv run wildedge doctor --integrations timm
+
+uv run wildedge run \
+  --print-startup-report --integrations timm -- \
+  "${EXAMPLE_SCRIPT}"

examples/cli/pyproject.toml

@@ -0,0 +1,12 @@
+[project]
+name = "wildedge-cli-demo"
+version = "0.1.0"
+requires-python = ">=3.10"
+dependencies = [
+    "wildedge-sdk",
+    "torch",
+    "timm",
+]
+
+[tool.uv.sources]
+wildedge-sdk = { path = "../..", editable = true }

pyproject.toml

@@ -4,6 +4,9 @@ version = "0.1.0"
 requires-python = ">=3.10"
 dependencies = []
 
+[project.scripts]
+wildedge = "wildedge.cli:main"
+
 
 [build-system]
 requires = ["hatchling"]

scripts/compat_matrix.py

@@ -56,7 +56,7 @@
         },
         "current": {
             "3.14": ["torch==2.10.0", "numpy==2.1.3"],
-        }
+        },
     },
     "timm": {
         "min": {
@@ -80,7 +80,7 @@
                 "timm==1.0.15",
                 "numpy==2.1.3",
             ],
-        }
+        },
     },
 }
 

scripts/run_compat_local.py

@@ -29,10 +29,7 @@ class Row:
         if not (py == "3.13" and integration == "tensorflow")
     ],
     # compat-canary-314 job
-    *[
-        Row("3.14", integration, "current")
-        for integration in ("torch", "timm")
-    ],
+    *[Row("3.14", integration, "current") for integration in ("torch", "timm")],
 ]
 
 
@@ -55,7 +52,9 @@ def get_deps(row: Row) -> list[str]:
         "--python-version",
         row.python_version,
     ]
-    result = subprocess.run(cmd, check=False, capture_output=True, text=True, cwd=REPO_ROOT)
+    result = subprocess.run(
+        cmd, check=False, capture_output=True, text=True, cwd=REPO_ROOT
+    )
     if result.returncode != 0:
         raise RuntimeError(result.stderr.strip() or result.stdout.strip())
     return [line.strip() for line in result.stdout.splitlines() if line.strip()]
@@ -75,9 +74,19 @@ def run_row(row: Row) -> tuple[str, str]:
     ]
     for dep in deps:
         cmd.extend(["--with", dep])
-    cmd.extend(["python", "-m", "pytest", f"tests/compat/test_{row.integration}_compat.py", "-q"])
+    cmd.extend(
+        [
+            "python",
+            "-m",
+            "pytest",
+            f"tests/compat/test_{row.integration}_compat.py",
+            "-q",
+        ]
+    )
 
-    result = subprocess.run(cmd, check=False, capture_output=True, text=True, cwd=REPO_ROOT)
+    result = subprocess.run(
+        cmd, check=False, capture_output=True, text=True, cwd=REPO_ROOT
+    )
     output = f"{result.stdout}\n{result.stderr}".strip()
 
     if result.returncode == 0: