android-emu-agent 0.1.3__py3-none-any.whl

android_emu_agent/cli/commands/emulator.py

@@ -0,0 +1,46 @@
+"""Emulator management CLI commands."""
+
+from __future__ import annotations
+
+import typer
+
+from android_emu_agent.cli.daemon_client import DaemonClient
+from android_emu_agent.cli.utils import handle_response
+
+app = typer.Typer(help="Emulator management commands")
+snapshot_app = typer.Typer(help="Emulator snapshot commands")
+app.add_typer(snapshot_app, name="snapshot")
+
+
+@snapshot_app.command("save")
+def emulator_snapshot_save(
+    serial: str = typer.Argument(..., help="Emulator serial (e.g., emulator-5554)"),
+    name: str = typer.Argument(..., help="Snapshot name"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Save emulator snapshot."""
+    client = DaemonClient()
+    resp = client.request(
+        "POST",
+        "/emulator/snapshot_save",
+        json_body={"serial": serial, "name": name},
+    )
+    client.close()
+    handle_response(resp, json_output=json_output)
+
+
+@snapshot_app.command("restore")
+def emulator_snapshot_restore(
+    serial: str = typer.Argument(..., help="Emulator serial (e.g., emulator-5554)"),
+    name: str = typer.Argument(..., help="Snapshot name"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Restore emulator snapshot."""
+    client = DaemonClient()
+    resp = client.request(
+        "POST",
+        "/emulator/snapshot_restore",
+        json_body={"serial": serial, "name": name},
+    )
+    client.close()
+    handle_response(resp, json_output=json_output)

android_emu_agent/cli/commands/file.py

@@ -0,0 +1,139 @@
+"""File transfer CLI commands."""
+
+from __future__ import annotations
+
+import typer
+
+from android_emu_agent.cli.daemon_client import DaemonClient
+from android_emu_agent.cli.utils import (
+    FILE_APP_TRANSFER_TIMEOUT,
+    FILE_TRANSFER_TIMEOUT,
+    handle_output_response,
+    handle_response,
+    require_target,
+)
+
+app = typer.Typer(help="File transfer commands")
+app_private = typer.Typer(help="App-private file operations (rooted/emulator)")
+app.add_typer(app_private, name="app")
+
+
+@app.command("push")
+def file_push(
+    local_path: str = typer.Argument(..., help="Local file or directory"),
+    remote_path: str | None = typer.Option(
+        None,
+        "--remote",
+        help="Remote path (default: /sdcard/Download/<name>)",
+    ),
+    device: str | None = typer.Option(None, "--device", "-d", help="Device serial"),
+    session_id: str | None = typer.Option(None, "--session", "-s", help="Session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Push a local file to shared storage (sdcard)."""
+    payload = require_target(device, session_id)
+    payload.update({"local_path": local_path, "remote_path": remote_path})
+    client = DaemonClient(timeout=FILE_TRANSFER_TIMEOUT)
+    resp = client.request("POST", "/files/push", json_body=payload)
+    client.close()
+    handle_response(resp, json_output=json_output)
+
+
+@app.command("pull")
+def file_pull(
+    remote_path: str = typer.Argument(..., help="Remote file or directory"),
+    local_path: str | None = typer.Option(None, "--local", help="Local output path"),
+    device: str | None = typer.Option(None, "--device", "-d", help="Device serial"),
+    session_id: str | None = typer.Option(None, "--session", "-s", help="Session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Pull a file from shared storage (sdcard)."""
+    payload = require_target(device, session_id)
+    payload.update({"remote_path": remote_path, "local_path": local_path})
+    client = DaemonClient(timeout=FILE_TRANSFER_TIMEOUT)
+    resp = client.request("POST", "/files/pull", json_body=payload)
+    client.close()
+    handle_response(resp, json_output=json_output)
+
+
+@app.command("find")
+def file_find(
+    path: str = typer.Argument(..., help="Root directory to search"),
+    name: str = typer.Option(..., "--name", help="Filename glob (e.g. *.db or cache*)"),
+    kind: str = typer.Option("any", "--type", help="file|dir|any"),
+    max_depth: int = typer.Option(4, "--max-depth", help="Max directory depth"),
+    device: str | None = typer.Option(None, "--device", "-d", help="Device serial"),
+    session_id: str | None = typer.Option(None, "--session", "-s", help="Session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Find files/folders and return metadata (rooted/emulator)."""
+    payload = require_target(device, session_id)
+    payload.update(
+        {
+            "path": path,
+            "name": name,
+            "kind": kind,
+            "max_depth": max_depth,
+        }
+    )
+    client = DaemonClient(timeout=FILE_TRANSFER_TIMEOUT)
+    resp = client.request("POST", "/files/find", json_body=payload)
+    client.close()
+    handle_output_response(resp, json_output=json_output)
+
+
+@app.command("list")
+def file_list(
+    path: str = typer.Argument(..., help="Directory to list"),
+    kind: str = typer.Option("any", "--type", help="file|dir|any"),
+    device: str | None = typer.Option(None, "--device", "-d", help="Device serial"),
+    session_id: str | None = typer.Option(None, "--session", "-s", help="Session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """List files/folders in a directory (rooted/emulator)."""
+    payload = require_target(device, session_id)
+    payload.update({"path": path, "kind": kind})
+    client = DaemonClient(timeout=FILE_TRANSFER_TIMEOUT)
+    resp = client.request("POST", "/files/list", json_body=payload)
+    client.close()
+    handle_output_response(resp, json_output=json_output)
+
+
+@app_private.command("push")
+def file_app_push(
+    package: str = typer.Argument(..., help="Package name"),
+    local_path: str = typer.Argument(..., help="Local file or directory"),
+    remote_path: str | None = typer.Option(
+        None,
+        "--remote",
+        help="App data path (default: files/<name>)",
+    ),
+    device: str | None = typer.Option(None, "--device", "-d", help="Device serial"),
+    session_id: str | None = typer.Option(None, "--session", "-s", help="Session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Push a file into app-private storage (rooted/emulator)."""
+    payload = require_target(device, session_id)
+    payload.update({"package": package, "local_path": local_path, "remote_path": remote_path})
+    client = DaemonClient(timeout=FILE_APP_TRANSFER_TIMEOUT)
+    resp = client.request("POST", "/files/app_push", json_body=payload)
+    client.close()
+    handle_response(resp, json_output=json_output)
+
+
+@app_private.command("pull")
+def file_app_pull(
+    package: str = typer.Argument(..., help="Package name"),
+    remote_path: str = typer.Argument(..., help="App data path (relative or absolute)"),
+    local_path: str | None = typer.Option(None, "--local", help="Local output path"),
+    device: str | None = typer.Option(None, "--device", "-d", help="Device serial"),
+    session_id: str | None = typer.Option(None, "--session", "-s", help="Session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Pull a file from app-private storage (rooted/emulator)."""
+    payload = require_target(device, session_id)
+    payload.update({"package": package, "remote_path": remote_path, "local_path": local_path})
+    client = DaemonClient(timeout=FILE_APP_TRANSFER_TIMEOUT)
+    resp = client.request("POST", "/files/app_pull", json_body=payload)
+    client.close()
+    handle_response(resp, json_output=json_output)

android_emu_agent/cli/commands/reliability.py

@@ -0,0 +1,310 @@
+"""Reliability and forensics CLI commands."""
+
+from __future__ import annotations
+
+import typer
+
+from android_emu_agent.cli.daemon_client import DaemonClient
+from android_emu_agent.cli.utils import (
+    RELIABILITY_BUGREPORT_TIMEOUT,
+    RELIABILITY_DUMPHEAP_TIMEOUT,
+    RELIABILITY_PULL_TIMEOUT,
+    RELIABILITY_TIMEOUT,
+    handle_output_response,
+    handle_response,
+    require_target,
+)
+
+app = typer.Typer(help="Reliability and forensics commands")
+dropbox_app = typer.Typer(help="DropBoxManager commands")
+pull_app = typer.Typer(help="Pull protected artifacts (rooted/emulator)")
+app.add_typer(dropbox_app, name="dropbox")
+app.add_typer(pull_app, name="pull")
+
+
+@app.command("exit-info")
+def reliability_exit_info(
+    package: str = typer.Argument(..., help="Package name"),
+    device: str | None = typer.Option(None, "--device", "-d", help="Device serial"),
+    session_id: str | None = typer.Option(None, "--session", "-s", help="Session ID"),
+    list_only: bool = typer.Option(False, "--list", help="List exit-info entries only"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Show ApplicationExitInfo for a package."""
+    payload = require_target(device, session_id)
+    payload.update({"package": package, "list_only": list_only})
+    client = DaemonClient(timeout=RELIABILITY_TIMEOUT)
+    resp = client.request("POST", "/reliability/exit_info", json_body=payload)
+    client.close()
+    handle_output_response(resp, json_output=json_output)
+
+
+@app.command("bugreport")
+def reliability_bugreport(
+    device: str | None = typer.Option(None, "--device", "-d", help="Device serial"),
+    session_id: str | None = typer.Option(None, "--session", "-s", help="Session ID"),
+    output: str | None = typer.Option(None, "--output", help="Output filename (.zip)"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Capture a system bugreport."""
+    payload = require_target(device, session_id)
+    payload.update({"filename": output})
+    client = DaemonClient(timeout=RELIABILITY_BUGREPORT_TIMEOUT)
+    resp = client.request("POST", "/reliability/bugreport", json_body=payload)
+    client.close()
+    handle_response(resp, json_output=json_output)
+
+
+@app.command("events")
+def reliability_events(
+    device: str | None = typer.Option(None, "--device", "-d", help="Device serial"),
+    session_id: str | None = typer.Option(None, "--session", "-s", help="Session ID"),
+    pattern: str | None = typer.Option(None, "--pattern", help="Regex filter for events"),
+    package: str | None = typer.Option(None, "--package", help="Filter for package name"),
+    since: str | None = typer.Option(None, "--since", help="Logcat -t value"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Dump ActivityManager events log."""
+    payload = require_target(device, session_id)
+    payload.update({"pattern": pattern, "package": package, "since": since})
+    client = DaemonClient(timeout=RELIABILITY_TIMEOUT)
+    resp = client.request("POST", "/reliability/events", json_body=payload)
+    client.close()
+    handle_output_response(resp, json_output=json_output)
+
+
+@dropbox_app.command("list")
+def reliability_dropbox_list(
+    device: str | None = typer.Option(None, "--device", "-d", help="Device serial"),
+    session_id: str | None = typer.Option(None, "--session", "-s", help="Session ID"),
+    package: str | None = typer.Option(None, "--package", help="Filter for package name"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """List DropBoxManager entries."""
+    payload = require_target(device, session_id)
+    payload.update({"package": package})
+    client = DaemonClient(timeout=RELIABILITY_TIMEOUT)
+    resp = client.request("POST", "/reliability/dropbox_list", json_body=payload)
+    client.close()
+    handle_output_response(resp, json_output=json_output)
+
+
+@dropbox_app.command("print")
+def reliability_dropbox_print(
+    tag: str = typer.Argument(..., help="DropBox tag (e.g., data_app_crash)"),
+    device: str | None = typer.Option(None, "--device", "-d", help="Device serial"),
+    session_id: str | None = typer.Option(None, "--session", "-s", help="Session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Print a DropBoxManager entry."""
+    payload = require_target(device, session_id)
+    payload.update({"tag": tag})
+    client = DaemonClient(timeout=RELIABILITY_TIMEOUT)
+    resp = client.request("POST", "/reliability/dropbox_print", json_body=payload)
+    client.close()
+    handle_output_response(resp, json_output=json_output)
+
+
+@app.command("background")
+def reliability_background(
+    package: str = typer.Argument(..., help="Package name"),
+    device: str | None = typer.Option(None, "--device", "-d", help="Device serial"),
+    session_id: str | None = typer.Option(None, "--session", "-s", help="Session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Check background restrictions and standby bucket."""
+    payload = require_target(device, session_id)
+    payload.update({"package": package})
+    client = DaemonClient(timeout=RELIABILITY_TIMEOUT)
+    resp = client.request("POST", "/reliability/background", json_body=payload)
+    client.close()
+    handle_output_response(resp, json_output=json_output)
+
+
+@app.command("last-anr")
+def reliability_last_anr(
+    device: str | None = typer.Option(None, "--device", "-d", help="Device serial"),
+    session_id: str | None = typer.Option(None, "--session", "-s", help="Session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Show the last ANR summary from ActivityManager."""
+    payload = require_target(device, session_id)
+    client = DaemonClient(timeout=RELIABILITY_TIMEOUT)
+    resp = client.request("POST", "/reliability/last_anr", json_body=payload)
+    client.close()
+    handle_output_response(resp, json_output=json_output)
+
+
+@app.command("jobscheduler")
+def reliability_jobscheduler(
+    package: str = typer.Argument(..., help="Package name"),
+    device: str | None = typer.Option(None, "--device", "-d", help="Device serial"),
+    session_id: str | None = typer.Option(None, "--session", "-s", help="Session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Inspect JobScheduler constraints for a package."""
+    payload = require_target(device, session_id)
+    payload.update({"package": package})
+    client = DaemonClient(timeout=RELIABILITY_TIMEOUT)
+    resp = client.request("POST", "/reliability/jobscheduler", json_body=payload)
+    client.close()
+    handle_output_response(resp, json_output=json_output)
+
+
+@app.command("compile")
+def reliability_compile(
+    package: str = typer.Argument(..., help="Package name"),
+    mode: str = typer.Option("reset", "--mode", help="reset|speed"),
+    device: str | None = typer.Option(None, "--device", "-d", help="Device serial"),
+    session_id: str | None = typer.Option(None, "--session", "-s", help="Session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Reset or force package compilation."""
+    payload = require_target(device, session_id)
+    payload.update({"package": package, "mode": mode})
+    client = DaemonClient(timeout=RELIABILITY_TIMEOUT)
+    resp = client.request("POST", "/reliability/compile", json_body=payload)
+    client.close()
+    handle_output_response(resp, json_output=json_output)
+
+
+@app.command("always-finish")
+def reliability_always_finish(
+    state: str = typer.Argument(..., help="on|off"),
+    device: str | None = typer.Option(None, "--device", "-d", help="Device serial"),
+    session_id: str | None = typer.Option(None, "--session", "-s", help="Session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Toggle always-finish-activities developer setting."""
+    payload = require_target(device, session_id)
+    payload.update({"state": state})
+    client = DaemonClient(timeout=RELIABILITY_TIMEOUT)
+    resp = client.request("POST", "/reliability/always_finish", json_body=payload)
+    client.close()
+    handle_response(resp, json_output=json_output)
+
+
+@app.command("run-as-ls")
+def reliability_run_as_ls(
+    package: str = typer.Argument(..., help="Package name"),
+    path: str = typer.Option("files/", "--path", help="Relative path under app data"),
+    device: str | None = typer.Option(None, "--device", "-d", help="Device serial"),
+    session_id: str | None = typer.Option(None, "--session", "-s", help="Session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """List app-private files for debuggable apps using run-as."""
+    payload = require_target(device, session_id)
+    payload.update({"package": package, "path": path})
+    client = DaemonClient(timeout=RELIABILITY_TIMEOUT)
+    resp = client.request("POST", "/reliability/run_as_ls", json_body=payload)
+    client.close()
+    handle_output_response(resp, json_output=json_output)
+
+
+@app.command("dumpheap")
+def reliability_dumpheap(
+    package: str = typer.Argument(..., help="Package name"),
+    keep_remote: bool = typer.Option(False, "--keep-remote", help="Keep heap on device"),
+    device: str | None = typer.Option(None, "--device", "-d", help="Device serial"),
+    session_id: str | None = typer.Option(None, "--session", "-s", help="Session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Dump a heap profile and pull it locally."""
+    payload = require_target(device, session_id)
+    payload.update({"package": package, "keep_remote": keep_remote})
+    client = DaemonClient(timeout=RELIABILITY_DUMPHEAP_TIMEOUT)
+    resp = client.request("POST", "/reliability/dumpheap", json_body=payload)
+    client.close()
+    handle_response(resp, json_output=json_output)
+
+
+@app.command("sigquit")
+def reliability_sigquit(
+    package: str = typer.Argument(..., help="Package name"),
+    device: str | None = typer.Option(None, "--device", "-d", help="Device serial"),
+    session_id: str | None = typer.Option(None, "--session", "-s", help="Session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Send SIGQUIT to dump thread stacks."""
+    payload = require_target(device, session_id)
+    payload.update({"package": package})
+    client = DaemonClient(timeout=RELIABILITY_TIMEOUT)
+    resp = client.request("POST", "/reliability/sigquit", json_body=payload)
+    client.close()
+    handle_response(resp, json_output=json_output)
+
+
+@app.command("oom-adj")
+def reliability_oom_adj(
+    package: str = typer.Argument(..., help="Package name"),
+    score: int = typer.Option(1000, "--score", help="oom_score_adj value"),
+    device: str | None = typer.Option(None, "--device", "-d", help="Device serial"),
+    session_id: str | None = typer.Option(None, "--session", "-s", help="Session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Adjust oom_score_adj to make a process more killable (root required)."""
+    payload = require_target(device, session_id)
+    payload.update({"package": package, "score": score})
+    client = DaemonClient(timeout=RELIABILITY_TIMEOUT)
+    resp = client.request("POST", "/reliability/oom_adj", json_body=payload)
+    client.close()
+    handle_response(resp, json_output=json_output)
+
+
+@app.command("trim-memory")
+def reliability_trim_memory(
+    package: str = typer.Argument(..., help="Package name"),
+    level: str = typer.Option("RUNNING_CRITICAL", "--level", help="Trim level constant"),
+    device: str | None = typer.Option(None, "--device", "-d", help="Device serial"),
+    session_id: str | None = typer.Option(None, "--session", "-s", help="Session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Send a trim memory signal to the app."""
+    payload = require_target(device, session_id)
+    payload.update({"package": package, "level": level})
+    client = DaemonClient(timeout=RELIABILITY_TIMEOUT)
+    resp = client.request("POST", "/reliability/trim_memory", json_body=payload)
+    client.close()
+    handle_output_response(resp, json_output=json_output)
+
+
+@pull_app.command("anr")
+def reliability_pull_anr(
+    device: str | None = typer.Option(None, "--device", "-d", help="Device serial"),
+    session_id: str | None = typer.Option(None, "--session", "-s", help="Session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Pull /data/anr (root required)."""
+    payload = require_target(device, session_id)
+    client = DaemonClient(timeout=RELIABILITY_PULL_TIMEOUT)
+    resp = client.request("POST", "/reliability/pull_anr", json_body=payload)
+    client.close()
+    handle_response(resp, json_output=json_output)
+
+
+@pull_app.command("tombstones")
+def reliability_pull_tombstones(
+    device: str | None = typer.Option(None, "--device", "-d", help="Device serial"),
+    session_id: str | None = typer.Option(None, "--session", "-s", help="Session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Pull /data/tombstones (root required)."""
+    payload = require_target(device, session_id)
+    client = DaemonClient(timeout=RELIABILITY_PULL_TIMEOUT)
+    resp = client.request("POST", "/reliability/pull_tombstones", json_body=payload)
+    client.close()
+    handle_response(resp, json_output=json_output)
+
+
+@pull_app.command("dropbox")
+def reliability_pull_dropbox(
+    device: str | None = typer.Option(None, "--device", "-d", help="Device serial"),
+    session_id: str | None = typer.Option(None, "--session", "-s", help="Session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Pull /data/system/dropbox (root required)."""
+    payload = require_target(device, session_id)
+    client = DaemonClient(timeout=RELIABILITY_PULL_TIMEOUT)
+    resp = client.request("POST", "/reliability/pull_dropbox", json_body=payload)
+    client.close()
+    handle_response(resp, json_output=json_output)

android_emu_agent/cli/commands/session.py

@@ -0,0 +1,65 @@
+"""Session management CLI commands."""
+
+from __future__ import annotations
+
+import typer
+
+from android_emu_agent.cli.daemon_client import DaemonClient, format_json
+from android_emu_agent.cli.utils import handle_response
+
+app = typer.Typer(help="Session management commands")
+
+
+@app.command("start")
+def session_start(
+    device: str = typer.Option(..., "--device", "-d", help="Device serial"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Start a new session on a device."""
+    client = DaemonClient()
+    resp = client.request("POST", "/sessions/start", json_body={"device_serial": device})
+    client.close()
+
+    data = resp.json()
+    if json_output:
+        typer.echo(format_json(data))
+        return
+
+    if data.get("status") == "done":
+        typer.echo(data.get("session_id"))
+        return
+
+    handle_response(resp, json_output=json_output)
+
+
+@app.command("stop")
+def session_stop(
+    session_id: str = typer.Argument(..., help="Session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Stop a session."""
+    client = DaemonClient()
+    resp = client.request("POST", "/sessions/stop", json_body={"session_id": session_id})
+    client.close()
+    handle_response(resp, json_output=json_output)
+
+
+@app.command("info")
+def session_info(
+    session_id: str = typer.Argument(..., help="Session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Show session info."""
+    client = DaemonClient()
+    resp = client.request("GET", f"/sessions/{session_id}")
+    client.close()
+    handle_response(resp, json_output=json_output)
+
+
+@app.command("list")
+def session_list(json_output: bool = typer.Option(False, "--json", help="Output JSON")) -> None:
+    """List active sessions."""
+    client = DaemonClient()
+    resp = client.request("GET", "/sessions")
+    client.close()
+    handle_response(resp, json_output=json_output)

android_emu_agent/cli/commands/ui.py

@@ -0,0 +1,112 @@
+"""UI observation CLI commands."""
+
+from __future__ import annotations
+
+import typer
+
+from android_emu_agent.cli.daemon_client import DaemonClient, format_json
+from android_emu_agent.cli.utils import (
+    handle_response_with_pull,
+    require_target,
+    resolve_session_id,
+)
+
+app = typer.Typer(help="UI observation commands")
+
+
+def _validate_snapshot_flags(full: bool, raw: bool) -> str:
+    """Validate and determine snapshot mode from CLI flags.
+
+    Args:
+        full: True if --full flag was provided
+        raw: True if --raw flag was provided
+
+    Returns:
+        The mode string: "compact", "full", or "raw"
+
+    Raises:
+        typer.BadParameter: If both --full and --raw are provided
+    """
+    if full and raw:
+        raise typer.BadParameter("--full and --raw are mutually exclusive")
+    if raw:
+        return "raw"
+    if full:
+        return "full"
+    return "compact"
+
+
+@app.command("snapshot")
+def ui_snapshot(
+    session_id: str = typer.Argument(..., help="Session ID"),
+    full: bool = typer.Option(False, "--full", help="Include all nodes (JSON)"),
+    raw: bool = typer.Option(False, "--raw", help="Return raw XML hierarchy"),
+    format_: str = typer.Option("json", "--format", "-f", help="Output format: json|text"),
+) -> None:
+    """Take a UI snapshot.
+
+    Modes (mutually exclusive):
+    - Default (compact): Interactive elements only, JSON format
+    - --full: All elements, JSON format
+    - --raw: Original XML hierarchy string
+    """
+    try:
+        mode = _validate_snapshot_flags(full, raw)
+    except typer.BadParameter as exc:
+        typer.echo(f"Error: {exc}")
+        raise typer.Exit(code=1) from None
+
+    client = DaemonClient()
+    resp = client.request(
+        "POST",
+        "/ui/snapshot",
+        json_body={"session_id": session_id, "mode": mode},
+    )
+    client.close()
+
+    content_type = resp.headers.get("content-type", "")
+    if "application/xml" in content_type:
+        typer.echo(resp.text)
+        return
+
+    data = resp.json()
+    if format_ == "text" and not data.get("error"):
+        elements = data.get("elements", [])
+        header = (
+            f"session={data.get('session_id')} generation={data.get('generation')} "
+            f"elements={len(elements)}"
+        )
+        typer.echo(header)
+        for elem in elements:
+            label = elem.get("label") or elem.get("text") or ""
+            role = elem.get("role") or "element"
+            rid = elem.get("resource_id") or "-"
+            typer.echo(f"{elem['ref']} {role} '{label}' id={rid} bounds={elem.get('bounds')}")
+        return
+
+    typer.echo(format_json(data))
+
+
+@app.command("screenshot")
+def ui_screenshot(
+    session_id: str | None = typer.Argument(None, help="Session ID"),
+    device: str | None = typer.Option(None, "--device", "-d", help="Device serial"),
+    session: str | None = typer.Option(None, "--session", "-s", help="Session ID"),
+    pull: bool = typer.Option(False, "--pull", help="Copy screenshot to local path"),
+    output: str | None = typer.Option(
+        None, "--output", "-o", help="Output path (file or directory)"
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """Capture a screenshot."""
+    try:
+        resolved_session = resolve_session_id(session_id, session)
+    except typer.BadParameter as exc:
+        typer.echo(f"Error: {exc}")
+        raise typer.Exit(code=1) from None
+
+    payload = require_target(device, resolved_session)
+    client = DaemonClient()
+    resp = client.request("POST", "/ui/screenshot", json_body=payload)
+    client.close()
+    handle_response_with_pull(resp, json_output=json_output, pull=pull, output=output)