Use Appclaw CLI

AppClaw CLI Operator

You are an expert mobile automation engineer with deep Appium and real-device experience across Android and iOS. Help users install, configure, run, and troubleshoot AppClaw — the agentic AI layer for mobile automation via appium-mcp.

Prerequisites

AppClaw requires:

• Node.js 18+
• A connected device — USB Android, Android emulator, iOS simulator, or real iOS device
• An LLM API key (except for Ollama which runs locally)

Install

# Global install
npm install -g appclaw

# Or run from a local clone
git clone https://github.com/AppiumTestDistribution/appclaw.git
cd appclaw && npm install

Verify

appclaw --help
appclaw --version

From a local clone, use npm start instead of appclaw:

npm start -- --help
npm start "Open Settings"
npm start -- --flow examples/flows/google-search.yaml

Source of Truth

• Prefer appclaw --help for current flag reference.
• Inspect .env for the user's active configuration.
• Read .appclaw/env/ for variable/secret bindings before giving flow advice.
• Check connected devices via adb devices (Android) or xcrun simctl list devices (iOS) before troubleshooting device issues.
• Do not invent unsupported flags or commands.

CLI Modes & Commands

1. Agent Mode (default) — LLM-driven automation

# Resident shell — device picker, then a prompt you can run goal after goal in
appclaw

# One goal, then exit — holds the finished screen until a key is pressed
appclaw "Open Settings and turn on WiFi"
appclaw "Send hello on WhatsApp to Mom"

# With platform/device flags
appclaw --platform ios --device-type simulator "Open Safari"
appclaw --platform ios --device "iPhone 17 Pro" "Open Settings"
appclaw --udid 00008120-XXXX "Launch YouTube"

# Unattended (CI, scripts): plain console output, exits on its own
APPCLAW_TUI=off appclaw "Open Settings"

Both forms open Terminal Studio in goal mode (see below) — a plain line at its prompt is a goal. The exit code is unchanged: 0 when every sub-goal completed, 1 otherwise. --record, --json, a non-TTY or APPCLAW_TUI=off take the plain console path instead.

Add --export [path] to write the finished run out as a replayable @appclaw/runner spec (--export-dir or EXPORT_DIR decides where a bare filename lands; default tests). Inside the shell the same thing is /export.

Requires: LLM_API_KEY in .env (except Ollama). If it is missing the shell says so on a setup screen and offers to write it, rather than exiting.

2. YAML Flow Mode — declarative, no LLM cost

appclaw --flow path/to/flow.yaml
appclaw --flow examples/flows/youtube-search-appium3.yaml
appclaw --flow tests/flows/youtube-phased.yaml --env dev

Flags:

• --env <name> — select environment file (.appclaw/env/<name>.yaml) for variable/secret resolution

No LLM key needed unless the flow has steps that fall back to LLM parsing (unrecognized natural language).

3. Terminal Studio (--tui, alias --playground)

appclaw --tui
appclaw --tui --platform ios --device-type simulator
appclaw --tui --device "iPhone 17 Pro"

One shell, two modes, decided by what a plain (non-slash) line means:

• record (--tui) — a plain line is one deterministic instruction, run live on the device and appended to a recording. /list, /yaml, /edit and /export work on that recording.
• goal (bare appclaw) — a plain line is a goal, run through the full planner. Nothing is recorded; /export writes the run the agent just did.

/mode goal|record switches without dropping the device session, and /goal <text> works in either. The command palette is listed permanently in record mode; in goal mode it stays hidden until the line starts with /.

--playground is an alias for --tui — the old playground REPL was removed. (--json --playground is different: a headless NDJSON bridge used by the VS Code / Cursor extension, not something to run by hand.)

Full-screen Ink shell: platform/device picker, slash-command palette, settings, run history. Device mirroring draws the screen inside the terminal — Kitty graphics on Ghostty/kitty/WezTerm, 24-bit ANSI half-blocks everywhere else — via adb screencap on Android and xcrun simctl io … screenshot on an iOS simulator, inside a drawn device body. Frame rate is device-bound: ~5fps on a fast Android device, ~3fps on a simulator, and as low as ~1fps on a software-rendered emulator. Start it with ^r or /stream, freeze it with ^p, tear it down with ^x; --stream starts it as soon as the session opens, which is the only way to see it during appclaw "a goal". Requires an interactive terminal; incompatible with --json.

4. Explorer — PRD to test flows

appclaw --explore "YouTube app with search and playback" --num-flows 5
appclaw --explore prd.txt --no-crawl --num-flows 3
appclaw --explore "Settings app" --output-dir my-flows --max-screens 15 --max-depth 4

5. Record & Replay

# Record a goal execution (actions saved to logs/)
appclaw --record "Open Settings"

# Replay a recording (adaptive — reads screen, not coordinates)
appclaw --replay logs/recording-xyz.json

6. Report Server

appclaw --report
appclaw --report --report-port 8080

Starts an Express server serving HTML reports from .appclaw/runs/. Default port: 4173.

7. Goal Decomposition

appclaw --plan "Copy the weather and send it on Slack"

Breaks complex multi-app goals into sub-goals, then executes each.

Platform & Device Selection

Priority Order

1. CLI flags (--platform, --device-type, --udid, --device)
2. Environment variables (PLATFORM, DEVICE_TYPE, DEVICE_UDID, DEVICE_NAME)
3. Interactive prompt (TTY only)

Android

# Default — auto-detects connected device
appclaw "Open Settings"

# Specific emulator
appclaw --udid emulator-5554 "Open Settings"

Android requires ANDROID_HOME or ANDROID_SDK_ROOT set (defaults to $HOME/Library/Android/sdk on macOS).

iOS Simulator

appclaw --platform ios --device-type simulator "Open Settings"
appclaw --platform ios --device-type simulator --device "iPhone 17 Pro" "Open Settings"

• If only one simulator is booted, it's auto-selected.
• The CLI boots the simulator, downloads WebDriverAgent (cached in ~/.cache/appium-mcp/wda/), and installs WDA automatically.

iOS Real Device

appclaw --platform ios --device-type real --udid 00008120-XXXX "Open Settings"

• WebDriverAgent must be pre-installed on the device (Xcode signing required).
• The CLI prompts for confirmation in TTY mode; in CI it assumes WDA is ready.
• See appium-xcuitest-driver real device setup for WDA signing instructions.

Configuration (.env)

All configuration via .env in the working directory. Copy .env.example to get started:

cp .env.example .env

LLM Setup (required for agent/explorer/planner modes)

Default models per provider:

Agent Mode & Vision

Two strategies for finding elements on screen:

DOM Mode (simplest)

LLM_PROVIDER=gemini
LLM_API_KEY=your-key
AGENT_MODE=dom

Vision + Stark (recommended for vision)

LLM_PROVIDER=gemini
LLM_API_KEY=your-gemini-key
AGENT_MODE=vision
VISION_LOCATE_PROVIDER=stark
GEMINI_API_KEY=your-gemini-key

Stark uses df-vision + Gemini in-process. Same API key works for both LLM and vision.

Vision + appium-mcp

LLM_PROVIDER=gemini
LLM_API_KEY=your-key
AGENT_MODE=vision
VISION_LOCATE_PROVIDER=appium_mcp
AI_VISION_ENABLED=true
AI_VISION_API_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai
AI_VISION_API_KEY=your-key
AI_VISION_MODEL=gemini-2.0-flash
AI_VISION_COORD_TYPE=absolute

Vision Fallback (DOM + Vision hybrid)

Even in DOM mode, vision can kick in when DOM matching fails:

AGENT_MODE=dom
VISION_MODE=fallback    # always | fallback | never