appium-pilot 0.1.0__tar.gz

appium_pilot-0.1.0/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Read(//Users/marcoperugini/.claude/skills/**)",
+      "Read(//Users/marcoperugini/.claude/skills/playwright-cli/**)"
+    ]
+  }
+}

appium_pilot-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+build/
+*.pyc
+
+# appium-pilot artifact output (when run from this dir)
+/appium-pilot/
+
+# test artifacts
+.pytest_cache/
+tests/_apps/
+
+# editor
+.vscode/
+.idea/
+
+# internal notes (not tracked)
+/notes/

appium_pilot-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marco Perugini
+
+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.

appium_pilot-0.1.0/Makefile

@@ -0,0 +1,28 @@
+VENV ?= .venv
+ifeq ($(OS),Windows_NT)
+BIN := $(VENV)/Scripts
+else
+BIN := $(VENV)/bin
+endif
+PY := $(BIN)/python
+PYTEST := $(BIN)/pytest
+
+.PHONY: install test test-e2e test-e2e-ios test-e2e-android lint
+
+install:  ## install the package + dev deps into the venv
+	$(PY) -m pip install -e ".[dev]"
+
+test:  ## fast unit tests, no device (the after-every-change default)
+	$(PYTEST)
+
+test-e2e-android:  ## device-backed E2E against an Android emulator
+	$(PYTEST) -m e2e --platform=android
+
+test-e2e-ios:  ## device-backed E2E against an iOS simulator
+	$(PYTEST) -m e2e --platform=ios
+
+test-e2e:  ## device-backed E2E on both platforms
+	$(PYTEST) -m e2e --platform=both
+
+lint:  ## ruff lint (config in pyproject)
+	$(BIN)/ruff check src tests

appium_pilot-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: appium-pilot
+Version: 0.1.0
+Summary: Agent-first, session-based CLI for driving mobile apps via Appium
+Project-URL: Homepage, https://github.com/theperu/appium-pilot
+Project-URL: Repository, https://github.com/theperu/appium-pilot
+Project-URL: Issues, https://github.com/theperu/appium-pilot/issues
+Author: Marco Perugini
+License: MIT
+License-File: LICENSE
+Keywords: agent,android,appium,automation,cli,ios,llm,mobile,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: appium-python-client>=4.0.0
+Requires-Dist: selenium>=4.20.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# appium-pilot
+
+An agent-first, session-based CLI for driving native mobile apps via Appium.
+One verb per invocation, state persisted across calls, output tuned for an LLM
+agent: `snapshot` the screen to get element refs, then act on them by ref.
+
+## Install
+
+```bash
+pipx install .          # or: pip install -e .
+```
+
+You also need Node + the Appium server and drivers (appium-pilot does not install
+them — run `appium-pilot doctor` to see what's missing):
+
+```bash
+npm i -g appium
+appium driver install uiautomator2   # Android
+appium driver install xcuitest       # iOS
+```
+
+## Quick start
+
+```bash
+# Launch an installed Android app (auto-picks a booted emulator)
+appium-pilot open --platform android --app-package com.example.app
+
+# Or an iOS Simulator app bundle
+appium-pilot open --platform ios --app /path/to/MyApp.app
+
+# Inspect the screen — returns filtered XML with e1..eN refs
+appium-pilot snapshot
+
+# Act on a ref from the latest snapshot
+appium-pilot tap e7
+
+# Multiple parallel sessions
+appium-pilot -s=checkout open --platform ios --app /path/to/MyApp.app
+```
+
+Session state lives under `~/.appium-pilot/` (so any invocation can reattach
+regardless of cwd). Artifacts you want to find — screenshots and videos — are
+written to `./appium-pilot/` in the current directory (override with
+`APPIUM_PILOT_OUTPUT`).
+
+## Use from AI coding agents
+
+A skill ships inside the package so agents discover the commands and drive the
+CLI themselves. Install it into whichever tool you use — no manual symlink:
+
+```bash
+appium-pilot skills install                # Claude Code (~/.claude/skills/), the default
+appium-pilot skills install --tool cursor  # Cursor       (.cursor/rules/)
+appium-pilot skills install --tool copilot # GitHub Copilot (.github/copilot-instructions.md)
+appium-pilot skills install --tool agents  # AGENTS.md (the cross-tool standard)
+appium-pilot skills install --tool all     # all of the above
+appium-pilot skills uninstall --tool all   # remove
+```
+
+`claude` installs user-level (once, for every project); the others write into the
+current project. The skill source lives at `src/appium_pilot/skilldata/SKILL.md`;
+re-run `skills install` after editing it.
+
+## Platform support
+
+- **macOS** — full: iOS Simulator + Android Emulator.
+- **Windows / Linux** — Android only (iOS needs a Mac). External tools are
+  resolved through `shutil.which` (honoring `PATHEXT`, so `appium.cmd`/`adb.exe`
+  work) and background processes detach via OS-appropriate flags. On Windows,
+  `make` is uncommon — run the underlying commands directly
+  (`.venv\Scripts\pytest`, `python -m appium_pilot ...`). The Windows path is
+  implemented but not yet exercised on a Windows host.
+
+## Testing
+
+Two tiers (see `tests/`):
+
+```bash
+make install          # pip install -e ".[dev]"
+make test             # fast unit tests, no device — run after every change
+make test-e2e-android # device-backed E2E (auto-boots an emulator)
+make test-e2e-ios     # device-backed E2E (auto-boots a simulator)
+make test-e2e         # both platforms
+```
+
+- **Unit** (`tests/unit/`, ~0.2s, no device): locks in the snapshot filtering,
+  per-platform locators, quoting, output/JSON contract, parsing and config logic.
+  `pytest` runs only these by default.
+- **E2E** (`tests/e2e/`, marked `e2e`): drives the real CLI against official
+  Appium sample apps — ApiDemos (Android) and TestApp (iOS, built on demand) —
+  covering every command on both platforms. Apps are cached under `tests/_apps/`;
+  tests skip cleanly if a device/toolchain is unavailable.
+
+## Status
+
+All v1 commands implemented and smoke-tested end-to-end on an iOS Simulator
+(open → snapshot → tap → re-snapshot → screenshot → stale-ref handling → close):
+
+`open` · `close` · `list` · `close-all` · `kill-all` · `snapshot [--raw]` ·
+`source` · `screenshot [ref]` · `devices` · `doctor` · `tap` · `type` · `clear` ·
+`swipe` · `scroll` · `press` · `hide-keyboard` · `orientation` · `wait` ·
+`video-start`/`video-stop` ·
+`launch`/`activate`/`terminate`/`background`/`install`/`remove`/`reset`.
+
+Targets iOS Simulator + Android Emulator. Deferred to v2: hybrid webview,
+geolocation, network conditions, deep links, real devices, cloud farms.

appium_pilot-0.1.0/README.md

@@ -0,0 +1,106 @@
+# appium-pilot
+
+An agent-first, session-based CLI for driving native mobile apps via Appium.
+One verb per invocation, state persisted across calls, output tuned for an LLM
+agent: `snapshot` the screen to get element refs, then act on them by ref.
+
+## Install
+
+```bash
+pipx install .          # or: pip install -e .
+```
+
+You also need Node + the Appium server and drivers (appium-pilot does not install
+them — run `appium-pilot doctor` to see what's missing):
+
+```bash
+npm i -g appium
+appium driver install uiautomator2   # Android
+appium driver install xcuitest       # iOS
+```
+
+## Quick start
+
+```bash
+# Launch an installed Android app (auto-picks a booted emulator)
+appium-pilot open --platform android --app-package com.example.app
+
+# Or an iOS Simulator app bundle
+appium-pilot open --platform ios --app /path/to/MyApp.app
+
+# Inspect the screen — returns filtered XML with e1..eN refs
+appium-pilot snapshot
+
+# Act on a ref from the latest snapshot
+appium-pilot tap e7
+
+# Multiple parallel sessions
+appium-pilot -s=checkout open --platform ios --app /path/to/MyApp.app
+```
+
+Session state lives under `~/.appium-pilot/` (so any invocation can reattach
+regardless of cwd). Artifacts you want to find — screenshots and videos — are
+written to `./appium-pilot/` in the current directory (override with
+`APPIUM_PILOT_OUTPUT`).
+
+## Use from AI coding agents
+
+A skill ships inside the package so agents discover the commands and drive the
+CLI themselves. Install it into whichever tool you use — no manual symlink:
+
+```bash
+appium-pilot skills install                # Claude Code (~/.claude/skills/), the default
+appium-pilot skills install --tool cursor  # Cursor       (.cursor/rules/)
+appium-pilot skills install --tool copilot # GitHub Copilot (.github/copilot-instructions.md)
+appium-pilot skills install --tool agents  # AGENTS.md (the cross-tool standard)
+appium-pilot skills install --tool all     # all of the above
+appium-pilot skills uninstall --tool all   # remove
+```
+
+`claude` installs user-level (once, for every project); the others write into the
+current project. The skill source lives at `src/appium_pilot/skilldata/SKILL.md`;
+re-run `skills install` after editing it.
+
+## Platform support
+
+- **macOS** — full: iOS Simulator + Android Emulator.
+- **Windows / Linux** — Android only (iOS needs a Mac). External tools are
+  resolved through `shutil.which` (honoring `PATHEXT`, so `appium.cmd`/`adb.exe`
+  work) and background processes detach via OS-appropriate flags. On Windows,
+  `make` is uncommon — run the underlying commands directly
+  (`.venv\Scripts\pytest`, `python -m appium_pilot ...`). The Windows path is
+  implemented but not yet exercised on a Windows host.
+
+## Testing
+
+Two tiers (see `tests/`):
+
+```bash
+make install          # pip install -e ".[dev]"
+make test             # fast unit tests, no device — run after every change
+make test-e2e-android # device-backed E2E (auto-boots an emulator)
+make test-e2e-ios     # device-backed E2E (auto-boots a simulator)
+make test-e2e         # both platforms
+```
+
+- **Unit** (`tests/unit/`, ~0.2s, no device): locks in the snapshot filtering,
+  per-platform locators, quoting, output/JSON contract, parsing and config logic.
+  `pytest` runs only these by default.
+- **E2E** (`tests/e2e/`, marked `e2e`): drives the real CLI against official
+  Appium sample apps — ApiDemos (Android) and TestApp (iOS, built on demand) —
+  covering every command on both platforms. Apps are cached under `tests/_apps/`;
+  tests skip cleanly if a device/toolchain is unavailable.
+
+## Status
+
+All v1 commands implemented and smoke-tested end-to-end on an iOS Simulator
+(open → snapshot → tap → re-snapshot → screenshot → stale-ref handling → close):
+
+`open` · `close` · `list` · `close-all` · `kill-all` · `snapshot [--raw]` ·
+`source` · `screenshot [ref]` · `devices` · `doctor` · `tap` · `type` · `clear` ·
+`swipe` · `scroll` · `press` · `hide-keyboard` · `orientation` · `wait` ·
+`video-start`/`video-stop` ·
+`launch`/`activate`/`terminate`/`background`/`install`/`remove`/`reset`.
+
+Targets iOS Simulator + Android Emulator. Deferred to v2: hybrid webview,
+geolocation, network conditions, deep links, real devices, cloud farms.

appium_pilot-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "appium-pilot"
+version = "0.1.0"
+description = "Agent-first, session-based CLI for driving mobile apps via Appium"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Marco Perugini" }]
+keywords = ["appium", "mobile", "automation", "cli", "android", "ios", "testing", "agent", "llm"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Testing",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "Appium-Python-Client>=4.0.0",
+    "selenium>=4.20.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/theperu/appium-pilot"
+Repository = "https://github.com/theperu/appium-pilot"
+Issues = "https://github.com/theperu/appium-pilot/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff"]
+
+[project.scripts]
+appium-pilot = "appium_pilot.cli:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra -m 'not e2e'"
+markers = [
+    "e2e: device-backed end-to-end test (needs a simulator/emulator)",
+    "ios: iOS-specific test",
+    "android: Android-specific test",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/appium_pilot"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/appium_pilot/skilldata/SKILL.md" = "appium_pilot/skilldata/SKILL.md"
+
+[tool.ruff]
+line-length = 110
+target-version = "py310"

appium_pilot-0.1.0/src/appium_pilot/__init__.py

@@ -0,0 +1,3 @@
+"""appium-pilot — agent-first, session-based CLI for driving mobile apps via Appium."""
+
+__version__ = "0.1.0"

appium_pilot-0.1.0/src/appium_pilot/__main__.py

@@ -0,0 +1,4 @@
+from appium_pilot.cli import main
+
+if __name__ == "__main__":
+    main()

appium_pilot-0.1.0/src/appium_pilot/cli.py

@@ -0,0 +1,96 @@
+"""appium-pilot front-end: global flags, subcommand dispatch, error mapping.
+
+Supports `-s=<name>` session selection (default "default") placed anywhere
+before the subcommand.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from selenium.common.exceptions import WebDriverException
+
+from appium_pilot import __version__
+from appium_pilot.commands import (
+    app_cmd,
+    capture_cmd,
+    devices_cmd,
+    doctor_cmd,
+    gesture_cmd,
+    open_cmd,
+    session_cmd,
+    skills_cmd,
+    snapshot_cmd,
+    tap_cmd,
+    type_cmd,
+    video_cmd,
+    wait_cmd,
+)
+from appium_pilot.output import CommandError, fail, set_json_mode
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="appium-pilot",
+        description="Agent-first, session-based CLI for driving mobile apps via Appium.",
+    )
+    parser.add_argument("-s", "--session", default="default", help="session name (default: default)")
+    parser.add_argument("--json", action="store_true", help="emit structured JSON output")
+    parser.add_argument("--version", action="version", version=f"appium-pilot {__version__}")
+
+    sub = parser.add_subparsers(dest="command", required=True, metavar="<command>")
+    for module in (
+        open_cmd,
+        snapshot_cmd,
+        capture_cmd,
+        tap_cmd,
+        type_cmd,
+        gesture_cmd,
+        wait_cmd,
+        video_cmd,
+        app_cmd,
+        devices_cmd,
+        session_cmd,
+        skills_cmd,
+        doctor_cmd,
+    ):
+        module.add_parser(sub)
+    return parser
+
+
+def _normalize_session_flag(argv: list[str]) -> list[str]:
+    """Allow `-s=name` in addition to argparse's `-s name`."""
+    out: list[str] = []
+    for arg in argv:
+        if arg.startswith("-s=") or arg.startswith("--session="):
+            out.append("--session")
+            out.append(arg.split("=", 1)[1])
+        else:
+            out.append(arg)
+    return out
+
+
+def main(argv: list[str] | None = None) -> None:
+    argv = _normalize_session_flag(list(argv if argv is not None else sys.argv[1:]))
+    args = build_parser().parse_args(argv)
+    set_json_mode(args.json)
+
+    try:
+        args.func(args)
+    except CommandError as exc:
+        fail(str(exc), code=exc.code, **exc.data)
+    except WebDriverException as exc:
+        # Driver-level failures (e.g. an action the app/platform rejects) become a
+        # clean one-line error, not a traceback. Set APPIUM_PILOT_DEBUG=1 to see it.
+        if os.environ.get("APPIUM_PILOT_DEBUG"):
+            raise
+        msg = (getattr(exc, "msg", None) or str(exc)).strip().splitlines()[0]
+        fail(f"driver error: {msg}")
+    except KeyboardInterrupt:
+        fail("interrupted", code=130)
+
+
+if __name__ == "__main__":
+    main()

appium_pilot-0.1.0/src/appium_pilot/commands/__init__.py

@@ -0,0 +1 @@
+"""Command handlers."""

appium_pilot-0.1.0/src/appium_pilot/commands/app_cmd.py

@@ -0,0 +1,106 @@
+"""App lifecycle (`launch`/`terminate`/`activate`/`background`/`install`/`remove`/`reset`)
+and `orientation`."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from appium_pilot.output import CommandError, emit
+from appium_pilot.session import Session
+
+
+def add_parser(sub: argparse._SubParsersAction) -> None:
+    for name, help_text in [
+        ("launch", "activate (foreground) the app under test"),
+        ("activate", "activate (foreground) the app under test"),
+        ("terminate", "terminate the app under test"),
+    ]:
+        p = sub.add_parser(name, help=help_text)
+        p.add_argument("app_id", nargs="?", help="app id (default: the session's app)")
+        p.set_defaults(func=_make_lifecycle(name))
+
+    bg = sub.add_parser("background", help="background the app for N seconds (-1 = indefinitely)")
+    bg.add_argument("seconds", nargs="?", type=int, default=-1)
+    bg.set_defaults(func=run_background)
+
+    inst = sub.add_parser("install", help="install an app artifact on the device")
+    inst.add_argument("path", help="path to .apk/.app/.ipa")
+    inst.set_defaults(func=run_install)
+
+    rm = sub.add_parser("remove", help="uninstall an app from the device")
+    rm.add_argument("app_id", nargs="?", help="app id (default: the session's app)")
+    rm.set_defaults(func=run_remove)
+
+    rs = sub.add_parser("reset", help="terminate then re-activate the app under test")
+    rs.set_defaults(func=run_reset)
+
+    o = sub.add_parser("orientation", help="get or set screen orientation")
+    o.add_argument("value", nargs="?", choices=["portrait", "landscape"],
+                   help="omit to read the current orientation")
+    o.set_defaults(func=run_orientation)
+
+
+def _app_id(session: Session, explicit: str | None) -> str:
+    app_id = explicit or session.app_id
+    if not app_id:
+        raise CommandError("no app id known for this session; pass one explicitly")
+    return app_id
+
+
+def _make_lifecycle(action: str):
+    def run(args) -> None:
+        session = Session.load(args.session)
+        driver = session.attach()
+        app_id = _app_id(session, args.app_id)
+        if action in ("launch", "activate"):
+            driver.activate_app(app_id)
+            emit(f"activated {app_id}", app=app_id)
+        elif action == "terminate":
+            driver.terminate_app(app_id)
+            emit(f"terminated {app_id}", app=app_id)
+
+    return run
+
+
+def run_background(args) -> None:
+    session = Session.load(args.session)
+    driver = session.attach()
+    driver.background_app(args.seconds)
+    emit(f"backgrounded app for {args.seconds}s")
+
+
+def run_install(args) -> None:
+    session = Session.load(args.session)
+    driver = session.attach()
+    path = str(Path(args.path).expanduser().resolve())
+    driver.install_app(path)
+    emit(f"installed {path}", path=path)
+
+
+def run_remove(args) -> None:
+    session = Session.load(args.session)
+    driver = session.attach()
+    app_id = _app_id(session, args.app_id)
+    driver.remove_app(app_id)
+    emit(f"removed {app_id}", app=app_id)
+
+
+def run_reset(args) -> None:
+    session = Session.load(args.session)
+    driver = session.attach()
+    app_id = _app_id(session, None)
+    driver.terminate_app(app_id)
+    driver.activate_app(app_id)
+    emit(f"reset {app_id}", app=app_id)
+
+
+def run_orientation(args) -> None:
+    session = Session.load(args.session)
+    driver = session.attach()
+    if args.value:
+        driver.orientation = args.value.upper()
+        emit(f"orientation set to {args.value}", orientation=args.value.upper())
+    else:
+        current = driver.orientation
+        emit(current, orientation=current)

appium_pilot-0.1.0/src/appium_pilot/commands/capture_cmd.py

@@ -0,0 +1,48 @@
+"""`screenshot` and `source` — pull pixels / raw page source off the device."""
+
+from __future__ import annotations
+
+import argparse
+import time
+
+from appium_pilot import config
+from appium_pilot.output import emit, raw
+from appium_pilot.resolve import find_ref
+from appium_pilot.session import Session
+
+
+def add_parser(sub: argparse._SubParsersAction) -> None:
+    sh = sub.add_parser("screenshot", help="save a PNG of the screen (or an element) and print its path")
+    sh.add_argument("ref", nargs="?", help="optional element ref to screenshot instead of the screen")
+    sh.add_argument("-o", "--out", help="output path (default: session screenshots dir)")
+    sh.set_defaults(func=run_screenshot)
+
+    src = sub.add_parser("source", help="print the full raw page source")
+    src.set_defaults(func=run_source)
+
+
+def run_screenshot(args) -> None:
+    session = Session.load(args.session)
+    driver = session.attach()
+
+    if args.out:
+        path = args.out
+    else:
+        shots = config.screenshots_dir()
+        shots.mkdir(parents=True, exist_ok=True)
+        path = str(shots / f"shot-{time.strftime('%Y%m%d-%H%M%S')}.png")
+
+    if args.ref:
+        locator = session.locator_for(args.ref)
+        element = find_ref(driver, locator, args.ref)
+        element.screenshot(path)
+    else:
+        driver.get_screenshot_as_file(path)
+
+    emit(path, path=path)
+
+
+def run_source(args) -> None:
+    session = Session.load(args.session)
+    driver = session.attach()
+    raw(driver.page_source)

appium_pilot-0.1.0/src/appium_pilot/commands/devices_cmd.py

@@ -0,0 +1,30 @@
+"""`devices` — list available simulators/emulators."""
+
+from __future__ import annotations
+
+import argparse
+
+from appium_pilot import devices
+from appium_pilot.output import emit, json_mode
+
+
+def add_parser(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("devices", help="list available iOS simulators / Android emulators")
+    p.set_defaults(func=run)
+
+
+def run(args) -> None:
+    found = devices.list_all()
+    payload = [
+        {"platform": d.platform, "udid": d.udid, "name": d.name, "booted": d.booted}
+        for d in found
+    ]
+    if json_mode():
+        emit(f"{len(found)} devices", devices=payload)
+        return
+    if not found:
+        emit("no devices found (no booted simulators/emulators or AVDs)")
+        return
+    for d in found:
+        state = "booted" if d.booted else "available"
+        print(f"{d.platform:8} {state:10} {d.name}  ({d.udid})")