Metadata-Version: 2.4
Name: autosana
Version: 0.6.0
Summary: Local testing infrastructure for Autosana — mobile and web
Project-URL: Homepage, https://autosana.ai
License: Proprietary
Requires-Python: >=3.9
Requires-Dist: filelock>=3.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: typer>=0.9.0
Description-Content-Type: text/markdown

# Autosana CLI

Connect local simulators, emulators, physical devices, and dev servers to [Autosana](https://autosana.ai) to test locally.

## Install

```
pipx install autosana
```

Or with uv:

```
uv tool install autosana
```

## Quick Start

```bash
# Check prerequisites
autosana doctor

# Auto-install Node.js + Appium + cloudflared
autosana doctor --fix

# Start local session (iOS)
autosana up --platform ios

# Start local session on a physical iPhone by UDID
autosana up --platform ios --device 00008140-00064D5930E3C01C --detach --json

# Diagnose a physical iPhone setup before running flows
autosana doctor --platform ios --device 00008140-00064D5930E3C01C --json

# Start local session (web — point to your dev server, http or https)
# The scheme (http vs https) is auto-detected. HTTPS dev servers like
# `next dev --experimental-https` and `vite --https` work out of the box.
autosana up --platform web --port 3000

# Multi-device — start sessions for all booted simulators
autosana up --platform ios --all-devices --detach --json

# Or start specific devices by name/UDID
autosana up --platform ios --device "iPhone 16 Pro" --detach --json
autosana up --platform ios --device "iPhone 17 Pro" --detach --json

# Check running sessions (includes device and screenshot readiness checks)
autosana status

# Recover a degraded session without a full restart when possible
autosana recover --session-id <SESSION_ID> --json

# Stop all sessions
autosana down --all
```

## Multi-Device Parallel Testing

Test across multiple simulators simultaneously:

1. Boot multiple iOS Simulators or Android Emulators
2. Run `autosana up --platform ios --all-devices --detach --json` to start sessions for all devices
3. Your coding agent dispatches flows to different devices in parallel via `device_tunnel_map`
4. All flows execute simultaneously — 3 devices = 3x faster

Works with both iOS and Android. Each device gets its own Appium server and Cloudflare tunnel.

## Device Health Checks

`autosana up` and `autosana status` verify that devices are actually responsive — not just listed by ADB/simctl:

- **Android**: runs `adb shell echo ok` with a 5s timeout to detect zombie emulators
- **iOS Simulators**: runs `xcrun simctl getenv` with a 5s timeout to detect frozen simulators
- **Physical iOS devices**: uses Xcode CoreDevice (`xcrun devicectl`) to verify the device is paired, connected, awake, and available to Xcode. If the device is locked, unplugged, offline, or missing a Trust This Computer prompt, `autosana up` exits before starting Appium.
- **Web**: probes `http://127.0.0.1:<port>` and `https://127.0.0.1:<port>` in parallel (3 attempts with backoff, to cover dev servers still booting). The responding scheme is used for the Cloudflare tunnel origin, preferring https on tie. HTTPS origins skip TLS verification on loopback — self-signed certs from mkcert, `next dev --experimental-https`, and `vite --https` just work. Verification is intentionally disabled here because the cloudflared origin is `127.0.0.1` (no MITM surface); to lock cloudflared back into strict verification with a trusted CA, you'd run cloudflared yourself instead of via `autosana up`.

If a mobile device is unresponsive, `autosana up` fast-fails before wasting time on Appium/tunnel setup. `autosana status --json` reports `device_responsive: false` with an actionable issue message.

`autosana status --json` also includes `components`, `next_action`, and each session's `session_id`. Agents should read these before every local run. If a Cloudflare tunnel or local proxy process died, run `autosana recover --session-id <SESSION_ID> --json` using the matching `status.sessions[].session_id` first. Recovery restarts the smallest failed scope when possible: tunnel first, local proxy next, and full session restart only when Appium/WebDriverAgent needs it.

The detected scheme is reported in `autosana up --json` as `scheme: "http"` or `scheme: "https"`.

## Physical iPhone Readiness

Physical iPhone local runs use Appium/WebDriverAgent (WDA) for both control and screenshots. WDA is installed on the device by `autosana up` and validated with a real screenshot capture before the session reports ready — no extra brew installs are required. For physical iOS sessions, `autosana up --platform ios --device <UDID> --detach --json` starts a local Autosana proxy in front of Appium and tunnels that proxy. The proxy exposes:

- `/_autosana/health`
- `/_autosana/screenshot`
- `/_autosana/diagnostics`

`autosana up` fails fast if no real screenshot provider is ready. `autosana status --json` includes physical-readiness fields:

- `screenshot_ready`
- `screenshot_provider`
- `screen_non_black`
- `wda_ready`
- `screenshot_diagnostics`
- `local_proxy_token` (physical iPhone only, internal token for Autosana proxy screenshots)
- `components`
- `next_action`

Treat `local_proxy_token` as a secret. Read it from `autosana status --json`, pass it directly to Autosana MCP tools for physical iPhone runs, and do not paste real token values into bug reports, chat logs, or public docs. Re-read status after recovery or restart because the token can change. If recovery rotates the token during an in-flight run, start a fresh `flows_run` with the new session values.

Run `autosana doctor --platform ios --device <UDID> --json` when physical setup fails. It checks CoreDevice connectivity, pairing/trust, Developer Mode, DDI services, WebDriverAgent signing, and the optional iPhone Mirroring host capture fallback. WDA screenshots are validated by `autosana up` itself at session start, so doctor warnings on the optional fallback do not block `up` — the doctor only surfaces the concrete blocker when the WDA path itself fails.

Keep the iPhone awake, unlocked, trusted, in Developer Mode, and plugged into power during physical local runs. If the display turns off, WDA may still return an accessibility tree, but Autosana treats black screenshots as a hard error and will not reconstruct a fake screenshot from accessibility data.

## Requirements

- **iOS Simulator**: macOS with one or more booted iOS Simulators
- **Physical iOS**: macOS with Xcode, a paired/unlocked iPhone in Developer Mode, and an Apple Development signing identity (with private key) available to Xcode. After WebDriverAgent first installs on the device, you must trust the developer certificate: **Settings → General → VPN & Device Management → tap your "Apple Development" entry → Trust**. For team-specific WebDriverAgent signing, set `AUTOSANA_IOS_XCODE_ORG_ID` and optionally `AUTOSANA_IOS_UPDATED_WDA_BUNDLE_ID`.
- **Android**: macOS, Linux, or Windows with one or more booted Android Emulators
- **Web**: a local dev server running on any OS
- An [Autosana](https://autosana.ai) account
