Autosana CLI

Connect local simulators, emulators, physical devices, and dev servers to Autosana to test locally.

Install

pipx install autosana

Or with uv:

uv tool install autosana

Quick Start

# 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

Working with flows

Store your end-to-end tests as YAML under a .autosana/ folder (code-managed flows), then validate, export, and run them from the terminal.

# Validate your .autosana/ flow & suite files offline (same rules the sync applies)
autosana flows validate

# Export existing dashboard flows/suites to .autosana/ YAML for review + commit
autosana flows export --all

# Run your branch's flows in the cloud (attributed to the current git ref), no PR needed
autosana flows run --flow login --bundle-id com.acme.app --platform ios

Run a flow on your local simulator

Run the flow you're currently editing — your uncommitted .autosana/ YAML — on the simulator you booted with autosana up. No commit, no push, no cloud device.

# 1. Boot a local session (once)
autosana up --platform ios

# 2. Run your working-copy flow on it
autosana run login --local

# ...or a whole suite (its setup_flow runs on the device first)
autosana run --suite checkout --local

# Web: connect your dev server, then target its Autosana app ID
autosana up --platform web --port 3000
autosana run login --local --app-id <APP_ID>

autosana run is shorthand for autosana flows run. Targeting uses sensible defaults, so the everyday command is just autosana run <flow> --local:

• App — web runs use --app-id; mobile runs use --bundle-id, the AUTOSANA_BUNDLE_ID env var, or your org's single app for the platform.
• Platform — web is inferred from --app-id; mobile is taken from your up session. Pass --platform / --session-id only to disambiguate mobile sessions.
• Environment — --environment <name> selects the variable set that ${env:…} references (and your flows) resolve against; required when the app spans multiple environments.

Notes:

• Runs your instructions; hooks are not executed locally (they manipulate the environment, not the device) — a suite's setup_flow gives you on-device setup instead.

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 account