edgelens-cli 0.2.1__py3-none-any.whl

edgelens_cli/__init__.py

@@ -0,0 +1,8 @@
+"""edgelens CLI — interactive sessions and quick tests without a framework.
+
+Entry point: ``edgelens`` (set via the ``[project.scripts]`` table in
+``pyproject.toml``). For programmatic use, import ``edgelens_cli.main.cli``
+directly.
+"""
+
+__version__ = "0.2.1"

edgelens_cli/client.py

@@ -0,0 +1,42 @@
+"""Common client-construction wrapper for every command.
+
+Resolves API key from (in priority order):
+- ``--api-key`` flag on the command
+- ``EDGELENS_API_KEY`` env var
+- ``~/.edgelens/config.json``
+
+Same for ``--base-url``.
+
+Raises a friendly click error instead of letting an
+``AuthenticationError`` bubble.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import click
+from edgelens import EdgeLensClient
+from edgelens.errors import AuthenticationError
+
+from edgelens_cli.state import load_config
+
+
+def build_client(
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+) -> EdgeLensClient:
+    config = load_config()
+    effective_key = api_key or config.api_key
+    effective_url = base_url or config.base_url
+    if not effective_key:
+        raise click.ClickException(
+            "No API key. Set EDGELENS_API_KEY or run `edgelens login`."
+        )
+    kwargs: dict = {"api_key": effective_key}
+    if effective_url:
+        kwargs["base_url"] = effective_url
+    try:
+        return EdgeLensClient(**kwargs)
+    except AuthenticationError as e:
+        raise click.ClickException(str(e))

edgelens_cli/commands/_resolve.py

@@ -0,0 +1,20 @@
+"""Resolve a session id from explicit argument or current-session state."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import click
+
+from edgelens_cli.state import load_state
+
+
+def resolve_session_id(explicit: Optional[str]) -> str:
+    if explicit:
+        return explicit
+    state = load_state()
+    if state.current_session_id is None:
+        raise click.ClickException(
+            "No current session. Run `edgelens session create ...` or `edgelens use <id>`."
+        )
+    return state.current_session_id

edgelens_cli/commands/device.py

@@ -0,0 +1,163 @@
+"""Device operations on the current (or named) session."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import click
+from edgelens.errors import EdgeLensError
+
+from edgelens_cli.client import build_client
+from edgelens_cli.commands._resolve import resolve_session_id
+from edgelens_cli.output import emit, error
+
+
+def _session_with_device(ctx: click.Context, session_id: Optional[str]):  # type: ignore[no-untyped-def]
+    """Resolve session id → ready Session, or click-error if not ready."""
+    sid = resolve_session_id(session_id)
+    client = build_client(ctx.obj.get("api_key"), ctx.obj.get("base_url"))
+    try:
+        session = client.get_session(sid)
+    except EdgeLensError as e:
+        error(str(e))
+    if session.status.value != "ready":
+        error(
+            f"session {sid} is in state {session.status.value}, not ready. "
+            "Run `edgelens session wait` first.",
+            exit_code=2,
+        )
+    return session
+
+
+@click.command("exec")
+@click.argument("command_str")
+@click.option("--session", "session_id", default=None, help="Session id (default: current).")
+@click.option("--timeout", default=60.0, type=float, help="Command timeout in seconds.")
+@click.pass_context
+def exec_cmd(
+    ctx: click.Context, command_str: str, session_id: Optional[str], timeout: float
+) -> None:
+    """Run a shell command on the camera and print stdout / exit code."""
+    session = _session_with_device(ctx, session_id)
+    try:
+        result = session.device.exec(command_str, timeout=timeout)
+    except EdgeLensError as e:
+        error(str(e))
+
+    payload = {
+        "stdout": result.stdout,
+        "stderr": result.stderr,
+        "exit_code": result.exit_code,
+    }
+    human_parts = []
+    if result.stdout:
+        human_parts.append(result.stdout.rstrip())
+    if result.stderr:
+        human_parts.append(click.style(result.stderr.rstrip(), fg="red"))
+    if not human_parts:
+        human_parts.append(f"(no output, exit={result.exit_code})")
+    emit(payload, json_mode=ctx.obj["json_mode"], human="\n".join(human_parts))
+    if result.exit_code != 0:
+        ctx.exit(result.exit_code if 0 < result.exit_code < 128 else 1)
+
+
+@click.command("deploy")
+@click.argument("model_path", type=click.Path(exists=True, dir_okay=False))
+@click.option("--config", "config_path", type=click.Path(exists=True, dir_okay=False), default=None)
+@click.option(
+    "--file", "extra_files", type=click.Path(exists=True, dir_okay=False),
+    multiple=True, help="Additional supporting files (repeatable).",
+)
+@click.option("--session", "session_id", default=None)
+@click.pass_context
+def deploy_cmd(
+    ctx: click.Context,
+    model_path: str,
+    config_path: Optional[str],
+    extra_files: tuple,
+    session_id: Optional[str],
+) -> None:
+    """Deploy a model file to the camera."""
+    session = _session_with_device(ctx, session_id)
+    try:
+        result = session.device.deploy(
+            model=model_path,
+            config=config_path,
+            files=list(extra_files) or None,
+        )
+    except EdgeLensError as e:
+        error(str(e))
+    emit(
+        result,
+        json_mode=ctx.obj["json_mode"],
+        human=f"✓ deployed {model_path}",
+    )
+
+
+@click.command("info")
+@click.option("--session", "session_id", default=None)
+@click.pass_context
+def info_cmd(ctx: click.Context, session_id: Optional[str]) -> None:
+    """Print the device info report."""
+    session = _session_with_device(ctx, session_id)
+    try:
+        info = session.device.info()
+    except EdgeLensError as e:
+        error(str(e))
+    emit(
+        info.model_dump() if hasattr(info, "model_dump") else info,
+        json_mode=ctx.obj["json_mode"],
+        human=(
+            f"hostname: {info.hostname}\n"
+            f"hardware: {info.hardware}\n"
+            f"firmware: {info.firmware}"
+        ),
+    )
+
+
+@click.command("ssh")
+@click.option("--session", "session_id", default=None)
+@click.option(
+    "--show-password", is_flag=True, default=False,
+    help="Print the SSH password in cleartext (or set EDGELENS_SHOW_PASSWORD=1).",
+)
+@click.pass_context
+def ssh_cmd(
+    ctx: click.Context, session_id: Optional[str], show_password: bool,
+) -> None:
+    """Print SSH connection details.
+
+    Password is masked by default in
+    both --json and human modes. The plaintext is only emitted when
+    --show-password is passed or EDGELENS_SHOW_PASSWORD=1 in the env,
+    so the credential never reaches stdout or CI logs by accident.
+    """
+    import os as _os
+    reveal = show_password or _os.environ.get("EDGELENS_SHOW_PASSWORD") == "1"
+
+    session = _session_with_device(ctx, session_id)
+    try:
+        creds = session.device.ssh()
+    except EdgeLensError as e:
+        error(str(e))
+
+    payload = {
+        "user": creds.user, "host": creds.host, "port": creds.port,
+    }
+    if reveal:
+        payload["password"] = creds.password
+
+    password_line = (
+        f"password: {creds.password}\n"
+        if reveal
+        else "password: <hidden — pass --show-password to reveal>\n"
+    )
+    human = (
+        f"user:     {creds.user}\n"
+        f"host:     {creds.host}\n"
+        f"port:     {creds.port}\n"
+        f"{password_line}"
+        "\n"
+        f"ssh -p {creds.port} {creds.user}@{creds.host}"
+    )
+    emit(payload, json_mode=ctx.obj["json_mode"], human=human)

edgelens_cli/commands/display.py

@@ -0,0 +1,89 @@
+"""``edgelens display`` subcommands."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import click
+from edgelens.errors import EdgeLensError
+
+from edgelens_cli.commands.device import _session_with_device
+from edgelens_cli.output import emit, error
+
+
+@click.group(name="display")
+def display_group() -> None:
+    """Control the camera's external display."""
+
+
+@display_group.command("play")
+@click.argument("source")
+@click.option("--loop/--no-loop", default=False)
+@click.option("--session", "session_id", default=None)
+@click.pass_context
+def display_play(
+    ctx: click.Context, source: str, loop: bool, session_id: Optional[str]
+) -> None:
+    """Play a video on the display."""
+    session = _session_with_device(ctx, session_id)
+    try:
+        session.device.display.play(source, loop=loop)
+    except EdgeLensError as e:
+        error(str(e))
+    emit(
+        {"action": "play", "source": source, "loop": loop},
+        json_mode=ctx.obj["json_mode"],
+        human=f"✓ display playing {source}{' (loop)' if loop else ''}",
+    )
+
+
+@display_group.command("show")
+@click.argument("source")
+@click.option("--session", "session_id", default=None)
+@click.pass_context
+def display_show(ctx: click.Context, source: str, session_id: Optional[str]) -> None:
+    """Show a still image on the display."""
+    session = _session_with_device(ctx, session_id)
+    try:
+        session.device.display.show(source)
+    except EdgeLensError as e:
+        error(str(e))
+    emit(
+        {"action": "show", "source": source},
+        json_mode=ctx.obj["json_mode"],
+        human=f"✓ display showing {source}",
+    )
+
+
+@display_group.command("stop")
+@click.option("--session", "session_id", default=None)
+@click.pass_context
+def display_stop(ctx: click.Context, session_id: Optional[str]) -> None:
+    """Stop display playback."""
+    session = _session_with_device(ctx, session_id)
+    try:
+        session.device.display.stop()
+    except EdgeLensError as e:
+        error(str(e))
+    emit({"action": "stop"}, json_mode=ctx.obj["json_mode"], human="✓ display stopped")
+
+
+@display_group.command("status")
+@click.option("--session", "session_id", default=None)
+@click.pass_context
+def display_status(ctx: click.Context, session_id: Optional[str]) -> None:
+    """Print the current display state."""
+    session = _session_with_device(ctx, session_id)
+    try:
+        state = session.device.display.status()
+    except EdgeLensError as e:
+        error(str(e))
+    emit(
+        state,
+        json_mode=ctx.obj["json_mode"],
+        human=(
+            f"ready:  {state.get('ready')}\n"
+            f"state:  {state.get('state')}\n"
+            f"source: {state.get('source') or '(none)'}"
+        ),
+    )

edgelens_cli/commands/inference.py

@@ -0,0 +1,100 @@
+"""``edgelens inference`` subcommands."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import click
+from edgelens.errors import EdgeLensError
+
+from edgelens_cli.commands.device import _session_with_device
+from edgelens_cli.output import emit, error
+
+
+@click.group(name="inference")
+def inference_group() -> None:
+    """Control on-device inference (stock OS only)."""
+
+
+@inference_group.command("start")
+@click.option("--session", "session_id", default=None)
+@click.pass_context
+def inference_start(ctx: click.Context, session_id: Optional[str]) -> None:
+    session = _session_with_device(ctx, session_id)
+    try:
+        session.device.inference.start()
+    except EdgeLensError as e:
+        error(str(e))
+    emit({"action": "start"}, json_mode=ctx.obj["json_mode"], human="✓ inference started")
+
+
+@inference_group.command("stop")
+@click.option("--session", "session_id", default=None)
+@click.pass_context
+def inference_stop(ctx: click.Context, session_id: Optional[str]) -> None:
+    session = _session_with_device(ctx, session_id)
+    try:
+        session.device.inference.stop()
+    except EdgeLensError as e:
+        error(str(e))
+    emit({"action": "stop"}, json_mode=ctx.obj["json_mode"], human="✓ inference stopped")
+
+
+@inference_group.command("once")
+@click.option("--session", "session_id", default=None)
+@click.pass_context
+def inference_once(ctx: click.Context, session_id: Optional[str]) -> None:
+    """Run a single frame and print the detections."""
+    session = _session_with_device(ctx, session_id)
+    try:
+        result = session.device.inference.once()
+    except EdgeLensError as e:
+        error(str(e))
+    emit(
+        result,
+        json_mode=ctx.obj["json_mode"],
+        human=f"detections: {len(result.get('detections', []))}",
+    )
+
+
+@inference_group.command("stats")
+@click.option("--session", "session_id", default=None)
+@click.pass_context
+def inference_stats(ctx: click.Context, session_id: Optional[str]) -> None:
+    """Print a point-in-time inference snapshot."""
+    session = _session_with_device(ctx, session_id)
+    try:
+        snap = session.device.inference.snapshot()
+    except EdgeLensError as e:
+        error(str(e))
+    payload = snap.model_dump() if hasattr(snap, "model_dump") else snap
+    human = (
+        f"fps:        {snap.fps}\n"
+        f"latency_ms: {snap.latency_ms}\n"
+        f"detections: {snap.detection_count}"
+    )
+    emit(payload, json_mode=ctx.obj["json_mode"], human=human)
+
+
+@inference_group.command("run")
+@click.option("--duration", default=30.0, type=float, help="Seconds to run.")
+@click.option("--collect-frames", is_flag=True, default=False)
+@click.option("--session", "session_id", default=None)
+@click.pass_context
+def inference_run(
+    ctx: click.Context, duration: float, collect_frames: bool, session_id: Optional[str]
+) -> None:
+    """Run inference for a duration and print aggregated stats."""
+    session = _session_with_device(ctx, session_id)
+    try:
+        stats = session.device.inference.run(duration=duration, collect_frames=collect_frames)
+    except EdgeLensError as e:
+        error(str(e))
+    payload = stats.model_dump() if hasattr(stats, "model_dump") else stats
+    human = (
+        f"duration_s:   {stats.duration_s}\n"
+        f"total_frames: {stats.total_frames}\n"
+        f"fps avg:      {stats.fps.avg:.2f}  p95: {stats.fps.p95:.2f}\n"
+        f"latency p95:  {stats.latency_ms.p95:.2f}ms"
+    )
+    emit(payload, json_mode=ctx.obj["json_mode"], human=human)

edgelens_cli/commands/session.py

@@ -0,0 +1,187 @@
+"""``edgelens session`` subcommands."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import click
+from edgelens.errors import EdgeLensError
+
+from edgelens_cli.client import build_client
+from edgelens_cli.commands._resolve import resolve_session_id
+from edgelens_cli.output import emit, error
+from edgelens_cli.state import clear_current_session, load_state, set_current_session
+
+
+@click.group(name="session")
+def session_group() -> None:
+    """Create, inspect, and release device sessions."""
+
+
+@session_group.command("create")
+@click.option(
+    "--device", "device_type", default="recamera-2002",
+    help="Device type to allocate (default: recamera-2002).",
+)
+@click.option(
+    "--os", "os_type", default="stock-os",
+    help="Which OS to flash (default: stock-os; alt: recamagined).",
+)
+@click.option(
+    "--timeout", "timeout_s", default=3600, type=int,
+    help="Max session duration in seconds (default: 3600).",
+)
+@click.option(
+    "--wait/--no-wait", default=True,
+    help="Block until status=ready (default: wait).",
+)
+@click.option(
+    "--wait-timeout", default=300, type=int,
+    help="Seconds to wait for ready (only with --wait, default: 300).",
+)
+@click.pass_context
+def session_create(
+    ctx: click.Context,
+    device_type: str,
+    os_type: str,
+    timeout_s: int,
+    wait: bool,
+    wait_timeout: int,
+) -> None:
+    """Allocate a new device. Sets it as the current session on success."""
+    client = build_client(ctx.obj.get("api_key"), ctx.obj.get("base_url"))
+    try:
+        session = client.create_session(
+            device_type=device_type, os=os_type, timeout=timeout_s,
+        )
+    except EdgeLensError as e:
+        error(str(e))
+    set_current_session(session.id)
+    if wait:
+        try:
+            session.wait_ready(timeout=wait_timeout)
+        except EdgeLensError as e:
+            emit(
+                {"id": session.id, "status": session.status.value, "error": str(e)},
+                json_mode=ctx.obj["json_mode"],
+                human=f"✗ {session.id}: {e}",
+            )
+            ctx.exit(1)
+
+    emit(
+        _session_payload(session),
+        json_mode=ctx.obj["json_mode"],
+        human=_human_session(session),
+    )
+
+
+@session_group.command("get")
+@click.argument("session_id", required=False)
+@click.pass_context
+def session_get(ctx: click.Context, session_id: Optional[str]) -> None:
+    """Show one session. Defaults to the current session."""
+    session_id = resolve_session_id(session_id)
+    client = build_client(ctx.obj.get("api_key"), ctx.obj.get("base_url"))
+    try:
+        session = client.get_session(session_id)
+    except EdgeLensError as e:
+        error(str(e))
+    emit(
+        _session_payload(session),
+        json_mode=ctx.obj["json_mode"],
+        human=_human_session(session),
+    )
+
+
+@session_group.command("wait")
+@click.argument("session_id", required=False)
+@click.option("--timeout", "wait_timeout", default=300, type=int)
+@click.pass_context
+def session_wait(ctx: click.Context, session_id: Optional[str], wait_timeout: int) -> None:
+    """Block until a session reaches status=ready."""
+    session_id = resolve_session_id(session_id)
+    client = build_client(ctx.obj.get("api_key"), ctx.obj.get("base_url"))
+    session = client.get_session(session_id)
+    try:
+        session.wait_ready(timeout=wait_timeout)
+    except EdgeLensError as e:
+        error(str(e))
+    emit(
+        _session_payload(session),
+        json_mode=ctx.obj["json_mode"],
+        human=_human_session(session),
+    )
+
+
+@session_group.command("release")
+@click.argument("session_id", required=False)
+@click.pass_context
+def session_release(ctx: click.Context, session_id: Optional[str]) -> None:
+    """End a session. Defaults to the current session and clears its pointer."""
+    session_id = resolve_session_id(session_id)
+    client = build_client(ctx.obj.get("api_key"), ctx.obj.get("base_url"))
+    try:
+        session = client.get_session(session_id)
+        session.release()
+    except EdgeLensError as e:
+        error(str(e))
+
+    # Clear `current` only if we just released what was pointed at.
+    state = load_state()
+    if state.current_session_id == session_id:
+        clear_current_session()
+
+    emit(
+        {"id": session_id, "status": "released"},
+        json_mode=ctx.obj["json_mode"],
+        human=f"✓ released {session_id}",
+    )
+
+
+@session_group.command("list")
+@click.pass_context
+def session_list(ctx: click.Context) -> None:
+    """Show recently-touched sessions from local state.
+
+    The platform API doesn't yet expose a per-key list endpoint, so
+    this is a local-state echo of the last sessions this CLI touched.
+    """
+    state = load_state()
+    payload = {
+        "current_session_id": state.current_session_id,
+        "recent": state.recent,
+    }
+    human_lines = []
+    if state.current_session_id:
+        human_lines.append(f"* {state.current_session_id} (current)")
+    for sid in state.recent:
+        if sid != state.current_session_id:
+            human_lines.append(f"  {sid}")
+    human = "\n".join(human_lines) if human_lines else "(no recent sessions)"
+    emit(payload, json_mode=ctx.obj["json_mode"], human=human)
+
+
+def _session_payload(session) -> dict:  # type: ignore[no-untyped-def]
+    payload: dict = {"id": session.id, "status": session.status.value}
+    conn = getattr(session, "_connection", None)
+    if conn is not None:
+        payload["device"] = {
+            "mac": conn.mac, "host": conn.host, "ssh_port": conn.ssh_port,
+            "ssh_user": conn.ssh_user, "os": conn.os.value,
+        }
+    if session.expires_at:
+        payload["expires_at"] = session.expires_at
+    return payload
+
+
+def _human_session(session) -> str:  # type: ignore[no-untyped-def]
+    lines = [f"id:     {session.id}", f"status: {session.status.value}"]
+    conn = getattr(session, "_connection", None)
+    if conn is not None:
+        lines.extend([
+            f"device: {conn.os.value} ({conn.mac})",
+            f"ssh:    {conn.ssh_user}@{conn.host}:{conn.ssh_port}",
+        ])
+    if session.expires_at:
+        lines.append(f"expires: {session.expires_at}")
+    return "\n".join(lines)

edgelens_cli/main.py

@@ -0,0 +1,138 @@
+"""CLI entry point.
+
+The top-level group exposes a `--json` flag so every command can emit
+machine-readable output. Subcommands fan out:
+
+  edgelens login                            save credentials
+  edgelens session ...                      create / get / wait / release / list
+  edgelens use SESSION_ID                   set current session for follow-up commands
+  edgelens exec / deploy / info / ssh       device operations on the current session
+  edgelens display ...                      display control
+  edgelens inference ...                    inference control
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Optional
+
+import click
+
+from edgelens_cli import __version__
+from edgelens_cli.commands import device, display, inference, session
+from edgelens_cli.output import emit, error
+from edgelens_cli.state import Config, clear_current_session, save_config, set_current_session
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(__version__, prog_name="edgelens")
+@click.option(
+    "--json", "json_mode", is_flag=True, default=False,
+    help="Emit machine-readable JSON on stdout.",
+)
+@click.option(
+    "--api-key",
+    envvar="EDGELENS_API_KEY",
+    help=(
+        "Override the API key. Default reads EDGELENS_API_KEY or "
+        "~/.edgelens/config.json. Prefer EDGELENS_API_KEY: a key on the "
+        "command line is visible in the process list and shell history."
+    ),
+)
+@click.option(
+    "--base-url",
+    envvar="EDGELENS_BASE_URL",
+    help="Override the platform API base URL.",
+)
+@click.pass_context
+def cli(
+    ctx: click.Context,
+    json_mode: bool,
+    api_key: Optional[str],
+    base_url: Optional[str],
+) -> None:
+    """edgelens — drive remote AI cameras from the command line."""
+    ctx.ensure_object(dict)
+    ctx.obj["json_mode"] = json_mode
+    ctx.obj["api_key"] = api_key
+    ctx.obj["base_url"] = base_url
+
+
+def _stdin_is_tty() -> bool:
+    return sys.stdin.isatty()
+
+
+def _read_api_key() -> str:
+    if _stdin_is_tty():
+        return click.prompt("API key", hide_input=True)
+    return sys.stdin.readline()
+
+
+@cli.command()
+@click.option(
+    "--api-key", default=None,
+    help=(
+        "API key to persist. Omit it to be prompted (input hidden) or to "
+        "pipe the key on stdin. Prefer that: a key on the command line is "
+        "visible in the process list and shell history."
+    ),
+)
+@click.option("--base-url", default=None, help="Optional platform base URL.")
+@click.pass_context
+def login(ctx: click.Context, api_key: Optional[str], base_url: Optional[str]) -> None:
+    """Persist credentials to ~/.edgelens/config.json (chmod 0600).
+
+    The key is read from a hidden prompt, or from stdin when stdin is not
+    a terminal.
+    """
+    if api_key is None:
+        api_key = _read_api_key().strip()
+    if not api_key:
+        error("no API key given", exit_code=2)
+    save_config(Config(api_key=api_key, base_url=base_url))
+    emit(
+        {"saved": True, "config_path": "~/.edgelens/config.json"},
+        json_mode=ctx.obj["json_mode"],
+        human="✓ credentials saved to ~/.edgelens/config.json",
+    )
+
+
+@cli.command()
+@click.pass_context
+def logout(ctx: click.Context) -> None:
+    """Forget credentials + current session pointer."""
+    save_config(Config())
+    clear_current_session()
+    emit(
+        {"cleared": True},
+        json_mode=ctx.obj["json_mode"],
+        human="✓ cleared ~/.edgelens/config.json and ~/.edgelens/state.json",
+    )
+
+
+@cli.command()
+@click.argument("session_id")
+@click.pass_context
+def use(ctx: click.Context, session_id: str) -> None:
+    """Set the current session for follow-up commands (exec, deploy, ...)."""
+    if not session_id.startswith("sess_"):
+        error("session ids start with 'sess_'", exit_code=2)
+    set_current_session(session_id)
+    emit(
+        {"current_session_id": session_id},
+        json_mode=ctx.obj["json_mode"],
+        human=f"✓ current session set to {session_id}",
+    )
+
+
+cli.add_command(session.session_group)
+cli.add_command(device.exec_cmd)
+cli.add_command(device.deploy_cmd)
+cli.add_command(device.info_cmd)
+cli.add_command(device.ssh_cmd)
+cli.add_command(display.display_group)
+cli.add_command(inference.inference_group)
+
+
+if __name__ == "__main__":
+    cli()

edgelens_cli/output.py

@@ -0,0 +1,40 @@
+"""Output helpers — human vs JSON modes."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, Optional
+
+import click
+
+
+def emit(payload: Any, *, json_mode: bool, human: Optional[str] = None) -> None:
+    """Emit ``payload`` as JSON or as the supplied ``human`` string.
+
+    When ``json_mode`` is True, the JSON form goes to stdout
+    regardless of ``human``. When False and ``human`` is None, we
+    fall back to ``str(payload)``.
+    """
+    if json_mode:
+        click.echo(json.dumps(payload, indent=2, default=_default))
+        return
+    click.echo(human if human is not None else str(payload))
+
+
+def warn(msg: str) -> None:
+    click.echo(click.style(f"warning: {msg}", fg="yellow"), err=True)
+
+
+def error(msg: str, *, exit_code: int = 1) -> None:
+    click.echo(click.style(f"error: {msg}", fg="red"), err=True)
+    sys.exit(exit_code)
+
+
+def _default(o: Any) -> Any:
+    # pydantic v2 models expose model_dump
+    if hasattr(o, "model_dump"):
+        return o.model_dump()
+    if hasattr(o, "__dict__"):
+        return {k: v for k, v in o.__dict__.items() if not k.startswith("_")}
+    return str(o)

edgelens_cli/state.py

@@ -0,0 +1,157 @@
+"""Persistent CLI state (api key, current session) at ``~/.edgelens/``.
+
+The state is split:
+
+- ``~/.edgelens/config.json`` — auth + base URL. Written by ``edgelens login``.
+- ``~/.edgelens/state.json``  — current-session pointer + recent sessions.
+  Written by ``edgelens session create`` / ``edgelens use``.
+
+Both files have ``0o600`` permissions; absence of either is treated as
+empty.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+
+DEFAULT_DIR = Path.home() / ".edgelens"
+CONFIG_PATH = DEFAULT_DIR / "config.json"
+STATE_PATH = DEFAULT_DIR / "state.json"
+
+
+def _fingerprint(api_key: Optional[str]) -> str:
+    """Render a key so two different keys look different and neither is readable.
+
+    A prefix of a secret is a piece of the secret, so the mask is a
+    one-way digest rather than a truncation: six hex characters of
+    sha256 identify a key to someone who already holds it and give
+    nothing to someone who does not.
+    """
+    if api_key is None:
+        return "None"
+    return f"<set sha256:{hashlib.sha256(api_key.encode()).hexdigest()[:6]}>"
+
+
+@dataclass
+class Config:
+    api_key: Optional[str] = field(default=None, repr=False)
+    base_url: Optional[str] = None
+
+    def __repr__(self) -> str:
+        # Any traceback carrying a Config reaches the operator's
+        # terminal or CI log; `asdict` is unaffected, so what gets
+        # persisted to config.json does not change.
+        return (
+            f"Config(api_key={_fingerprint(self.api_key)}, "
+            f"base_url={self.base_url!r})"
+        )
+
+
+@dataclass
+class State:
+    current_session_id: Optional[str] = None
+    recent: list[str] = field(default_factory=list)
+
+
+def _read_json(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text())
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def _write_json(path: Path, data: dict[str, Any]) -> None:
+    """Atomic create with 0o600 in a
+    single syscall instead of write-then-chmod.
+
+    Creating the file with default perms and chmod-ing it afterwards
+    would leave a TOCTOU window in which another user on a multi-user
+    host could read the API key.
+    ``os.open(path, O_WRONLY|O_CREAT|O_TRUNC, 0o600)`` creates the
+    file with 0o600 atomically, so that window never exists.
+    When os.chmod is the only available knob (Windows, overlay FS,
+    network shares), emit a clear warning so the operator knows the
+    config file may not be owner-restricted.
+    """
+    import logging as _logging
+    _log = _logging.getLogger(__name__)
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    body = json.dumps(data, indent=2)
+
+    try:
+        fd = os.open(
+            str(path), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600
+        )
+    except OSError:
+        # Windows / overlay paths where O_CREAT with mode is unsupported.
+        # Fall back to write_text + best-effort chmod, but loudly.
+        _log.warning(
+            "%s: atomic 0o600 create unavailable; falling back to "
+            "write_text + chmod (file may end up world-readable on "
+            "this platform).", path,
+        )
+        path.write_text(body)
+        try:
+            os.chmod(path, 0o600)
+        except OSError as e:
+            _log.warning(
+                "%s: chmod 0o600 also failed: %s. The API key in this "
+                "file may be readable by other local users.", path, e,
+            )
+        return
+
+    with os.fdopen(fd, "w") as f:
+        f.write(body)
+
+
+def load_config() -> Config:
+    """Load ``~/.edgelens/config.json``. ``EDGELENS_*`` env vars override."""
+    raw = _read_json(CONFIG_PATH)
+    return Config(
+        api_key=os.environ.get("EDGELENS_API_KEY") or raw.get("api_key"),
+        base_url=os.environ.get("EDGELENS_BASE_URL") or raw.get("base_url"),
+    )
+
+
+def save_config(config: Config) -> None:
+    """Write ``~/.edgelens/config.json``. Empty fields are stripped."""
+    payload = {k: v for k, v in asdict(config).items() if v is not None}
+    _write_json(CONFIG_PATH, payload)
+
+
+def load_state() -> State:
+    raw = _read_json(STATE_PATH)
+    return State(
+        current_session_id=raw.get("current_session_id"),
+        recent=list(raw.get("recent") or []),
+    )
+
+
+def save_state(state: State) -> None:
+    _write_json(STATE_PATH, asdict(state))
+
+
+def set_current_session(session_id: str, *, remember: int = 10) -> None:
+    """Mark ``session_id`` as the current session and remember it."""
+    state = load_state()
+    state.current_session_id = session_id
+    if session_id in state.recent:
+        state.recent.remove(session_id)
+    state.recent.insert(0, session_id)
+    state.recent = state.recent[:remember]
+    save_state(state)
+
+
+def clear_current_session() -> None:
+    state = load_state()
+    state.current_session_id = None
+    save_state(state)

edgelens_cli-0.2.1.dist-info/METADATA

@@ -0,0 +1,116 @@
+Metadata-Version: 2.5
+Name: edgelens-cli
+Version: 0.2.1
+Summary: Command-line interface for the EdgeLens Edge AI Device Farm.
+Project-URL: Homepage, https://edgelens.ai
+Project-URL: Repository, https://github.com/edgelens-ai/edgelens-sdk
+Project-URL: Issues, https://github.com/edgelens-ai/edgelens-sdk/issues
+Author-email: EdgeLens <support@edgelens.ai>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.9
+Requires-Dist: click>=8.1
+Requires-Dist: edgelens-sdk<0.3,>=0.2.1
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# edgelens-cli
+
+Command-line interface for the EdgeLens Edge AI Device Farm. Drives the
+same `EdgeLensClient` as the Python SDK; useful for ad-hoc sessions,
+quick experiments, and shell scripts.
+
+## Install
+
+```sh
+pip install edgelens-cli
+# or
+pipx install edgelens-cli
+```
+
+Adds an `edgelens` executable to your PATH.
+
+## Quickstart
+
+```sh
+edgelens login            # prompts for the key; input is hidden
+edgelens session create --device recamera-2002 --os stock-os --timeout 600
+# session id is remembered as 'current' — follow-up commands target it
+edgelens info
+edgelens exec 'uname -a'
+edgelens deploy ./face.cvimodel
+edgelens inference run --duration 30
+edgelens session release
+```
+
+In a script, pipe the key on stdin instead of passing it as an argument:
+
+```sh
+printf '%s\n' "$EDGELENS_API_KEY" | edgelens login
+```
+
+`--json` on the root command emits machine-readable JSON on every call,
+useful for shell pipelines or CI:
+
+```sh
+edgelens --json session create --no-wait | jq -r .id
+```
+
+## Commands
+
+```
+edgelens login                            persist credentials (~/.edgelens/config.json)
+edgelens logout                           forget credentials + current-session pointer
+edgelens use <SESSION_ID>                 set current session for follow-up commands
+
+edgelens session create [--device --os --timeout --wait/--no-wait]
+edgelens session get [SESSION_ID]         defaults to current
+edgelens session wait [SESSION_ID]        block until status=ready
+edgelens session release [SESSION_ID]
+edgelens session list                     recent sessions (from local state)
+
+edgelens exec '<command>'                 run via SSH (proxied)
+edgelens deploy <model_path> [--config --file ...]
+edgelens info                             device info report
+edgelens ssh                              print SSH connection details
+
+edgelens display play <url> [--loop]
+edgelens display show <url>
+edgelens display stop
+edgelens display status
+
+edgelens inference start
+edgelens inference stop
+edgelens inference once
+edgelens inference stats
+edgelens inference run [--duration N --collect-frames]
+```
+
+## Configuration
+
+| Source | Used for |
+|---|---|
+| `EDGELENS_API_KEY`, `EDGELENS_BASE_URL` env vars | Shell-session-scoped; the recommended way to pass a key in CI |
+| `--base-url` flag | One-off override |
+| `~/.edgelens/config.json` (chmod 0600) | Persistent default — set via `edgelens login` |
+
+Current-session state lives at `~/.edgelens/state.json` (chmod 0600).
+Session ids touched in the last ten commands are kept under `recent`
+so `edgelens session list` shows what you were doing.
+
+## Develop
+
+```sh
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+

edgelens_cli-0.2.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+edgelens_cli/__init__.py,sha256=oVSerpnUWzvsL82iEP0LKhQ2qa9UJn-tuZOJS2z2E4I,262
+edgelens_cli/client.py,sha256=ugNfFm7kkcWly0KQWOkgA0sPI8urIL8j05_h7CVzjFs,1137
+edgelens_cli/main.py,sha256=gOHyhLF3zCe0FGTm-gqQ3uDLyU-1L5QzVHZPv6dgBhY,4296
+edgelens_cli/output.py,sha256=kHydpl2KOg23XT6lBhPlA9IhT7VJBbgkv51jr7frnBk,1145
+edgelens_cli/state.py,sha256=_SdFvZSDEjeA905fBLu7XlRVyXKXYa8Dw58PwGF-F2I,4972
+edgelens_cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+edgelens_cli/commands/_resolve.py,sha256=PmBwKOPSTKxXMyF0FSj9aKCESJ9DeWe38NQdPlAZpB8,537
+edgelens_cli/commands/device.py,sha256=cH8XSxEcaSw-rdXaqWl5SrjJmWLbGZj4E7zggX5JAxk,5340
+edgelens_cli/commands/display.py,sha256=Log76k03bXoXCIGxBkifZyjCkbBU7IlIubkUCB12ijY,2727
+edgelens_cli/commands/inference.py,sha256=UWBtZmJydUnYZkgTgJo7O6ujwsI6nbuYJk4qK9nTBQ8,3506
+edgelens_cli/commands/session.py,sha256=eeuWmqPIzjrGum1QrxiNjsir_YVjd6DnbXHFjAPXg5I,6161
+edgelens_cli-0.2.1.dist-info/METADATA,sha256=dfCuqaOo4yqfbFSrYal85mUsxxR4H61mBWtlp39klXU,3607
+edgelens_cli-0.2.1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+edgelens_cli-0.2.1.dist-info/entry_points.txt,sha256=MjdPv8zj4sGwSPRE88lw43mFes8Uw4bvlzLu0gw4TNI,51
+edgelens_cli-0.2.1.dist-info/licenses/LICENSE,sha256=JR_6_gvFCZzmYkGGa1BL36k0ZzhakowmxnXVhhPPKpc,1065
+edgelens_cli-0.2.1.dist-info/RECORD,,

edgelens_cli-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

edgelens_cli-0.2.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+edgelens = edgelens_cli.main:cli

edgelens_cli-0.2.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EdgeLens
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.