use-appclaw-cli

name	use-appclaw-cli
description	Use the AppClaw CLI to run YAML flows, start interactive playground, explore apps, record/replay sessions, configure devices, and troubleshoot. Trigger for any request involving appclaw commands, device setup, .env configuration, running flows, vision setup, or debugging execution failures.

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

# Interactive — prompts for platform, device, goal
appclaw

# Pass goal directly
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"

Requires: LLM_API_KEY in .env (except Ollama).

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. Playground — interactive REPL

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

Type natural language commands that execute live on the device. Steps accumulate and can be exported to a YAML flow.

REPL commands: /help, /steps, /export, /clear, /device, /disconnect

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

Flag	Default	Purpose
--num-flows <N>	5	Number of flows to generate
--no-crawl	false	Skip device crawling (PRD-only analysis)
--output-dir <dir>	generated-flows	Where to write generated YAML files
--max-screens <N>	10	Max screens to crawl
--max-depth <N>	3	Max navigation depth during crawl

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)

Variable	Default	Options
LLM_PROVIDER	anthropic	anthropic, openai, gemini, groq, ollama
LLM_API_KEY	—	Your provider's API key (not needed for Ollama)
LLM_MODEL	auto	Override model ID (see defaults below)

Default models per provider:

Provider	Default Model
anthropic	claude-sonnet-4-20250514
openai	gpt-4o
gemini	gemini-2.0-flash
groq	llama-3.3-70b-versatile
ollama	llama3.2

Agent Mode & Vision

Two strategies for finding elements on screen:

Setup	AGENT_MODE	Best For
DOM mode	dom	Standard apps with good accessibility labels. Uses XML page source. Works with any LLM.
Vision mode	vision	Custom views, canvas-rendered UI, games. Screenshot-first with AI vision.

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

Tuning Parameters

Variable	Default	Purpose
MAX_STEPS	30	Max steps per goal before stopping
STEP_DELAY	500	Milliseconds between steps
MAX_ELEMENTS	40	Max interactive elements per screen capture
MAX_HISTORY_STEPS	10	Previous steps kept in LLM context
LLM_THINKING	on	Extended thinking/reasoning (on or off)
LLM_THINKING_BUDGET	128	Token budget for thinking
LLM_SCREENSHOT_MAX_EDGE_PX	0	Downscale screenshots for LLM (try 384 or 768 to reduce cost)
SHOW_TOKEN_USAGE	false	Print token usage and cost per step

MCP Transport

Variable	Default	Purpose
MCP_TRANSPORT	stdio	stdio (auto-launches appium-mcp) or sse (connect to running server)
MCP_HOST	localhost	SSE transport: hostname
MCP_PORT	8080	SSE transport: port

stdio (default) — AppClaw spawns npx appium-mcp@latest as a subprocess. No manual server setup.

SSE — Connect to an already-running appium-mcp server. Useful for shared environments or debugging.

Episodic Memory

EPISODIC_MEMORY=on    # off by default

Records successful trajectories to ~/.appclaw/trajectories.json and reuses them for similar goals in future runs.

---

Safety Policy

Safe without approval:

• appclaw --help, appclaw --version
• appclaw --flow (YAML execution — predictable, no LLM)
• appclaw --report (read-only report server)
• Reading .env, .appclaw/env/, flow YAML files

Ask before executing:

• appclaw "goal" (agent mode — uses LLM credits, takes actions on device)
• appclaw --explore (LLM credits + device crawling)
• appclaw --record (agent mode + saves recording)
• appclaw --playground (interactive device session)

Why: agent and explorer modes consume LLM API credits and take real actions on the connected device.

---

Troubleshooting

Device Issues

Problem	Diagnosis	Fix
"No devices found"	adb devices / xcrun simctl list devices	Connect device, boot emulator/simulator
Android not detected	Check ANDROID_HOME	export ANDROID_HOME=$HOME/Library/Android/sdk
iOS simulator WDA failure	WDA cache issue	Delete ~/.cache/appium-mcp/wda/ and retry
iOS real device WDA	Signing required	Follow appium-xcuitest-driver real device setup guide
Wrong device selected	Multiple devices connected	Use --udid or --device to specify

MCP Connection Issues

Problem	Fix
"Failed to connect to MCP"	Check that npx appium-mcp@latest runs standalone
SSE connection refused	Verify MCP_HOST and MCP_PORT match running server
Tool call timeout	Check device USB/network, restart appium-mcp

Vision Issues

Problem	Fix
Stark vision fails	Verify GEMINI_API_KEY or STARK_VISION_API_KEY is set and valid
appium-mcp vision fails	Check all AI_VISION_* vars are set; verify the API URL is reachable
Vision returns wrong coordinates	Try AI_VISION_COORD_TYPE=absolute for Gemini
Element not found (DOM or vision)	Enable vision fallback: VISION_MODE=fallback

Flow Execution Issues

Problem	Fix
"Undefined secret"	Export the shell variable: export VAR_NAME=value
"Undefined variable"	Add the key to .appclaw/env/<name>.yaml under variables:
launchApp fails	Set appId in the YAML header
Tap misses element	Use more specific label text; enable vision fallback
Natural language step not recognized	Use structured syntax instead (e.g., tap: "Login")

LLM Issues

Problem	Fix
"API key required"	Set LLM_API_KEY in .env
Model not found	Check LLM_MODEL matches provider's model ID
High cost	Use cheaper models (gemini-2.0-flash, gpt-4o-mini), reduce LLM_THINKING_BUDGET, set LLM_SCREENSHOT_MAX_EDGE_PX=384
Stuck in loop	Stuck detection kicks in after 3 repeated screens. Increase MAX_STEPS or simplify the goal

---

Common Workflows

Run a YAML flow on Android

appclaw --flow examples/flows/settings-wifi-on.yaml

Run a flow with environment variables

appclaw --flow tests/flows/youtube-phased.yaml --env dev

Quick test on iOS simulator

appclaw --platform ios --device-type simulator --playground
# In REPL: type commands, test them, /export to YAML

Generate test flows from a PRD

appclaw --explore "E-commerce app with cart and checkout" --num-flows 10 --output-dir flows/

View execution reports

appclaw --report
# Open http://localhost:4173 in browser

Cost-effective setup (Gemini)

LLM_PROVIDER=gemini
LLM_API_KEY=your-key
LLM_MODEL=gemini-2.0-flash
AGENT_MODE=vision
VISION_LOCATE_PROVIDER=stark
GEMINI_API_KEY=your-key
LLM_SCREENSHOT_MAX_EDGE_PX=512

Gemini Flash is the cheapest vision-capable model ($0.10/M input tokens). One key covers both LLM and Stark vision.

Free local setup (Ollama)

LLM_PROVIDER=ollama
LLM_MODEL=llama3.2
AGENT_MODE=dom

No API key needed. Requires Ollama running locally. DOM mode recommended since local models lack vision capability.

---

IDE Integration (VSCode Extension)

AppClaw has a VSCode extension that communicates via JSON mode:

appclaw --json "Open Settings"

The --json flag enables structured JSON event output and silences the rich terminal UI. This is used by the VSCode extension bridge — users don't need to use this flag directly.

---

Coordination

• For creating or editing YAML flow files, route to the generate-appclaw-flow skill.
• For reviewing code changes to the AppClaw codebase itself, route to the review-changes skill.