Appium-CLI — a CLI for Mobile Development and Automation | iOS, Android, Simulator, Emulator, and Real Devices

Semantic, scriptable commands on top of a running Appium server — built for humans, automation, and AI agents that need stable JSON and predictable exit codes.

Why this exists

This CLI is designed to empower AI assistants and developers with a robust suite of tools for mobile automation. It streamlines mobile app testing by enabling natural language interactions — e.g. tap "Sign in" instead of hand-authoring XPath for every step — with sensible matching and waits behind the scenes.

You can think of it as an Appium MCP alternative in terminal and CI form: same underlying Appium HTTP API, but typically faster, lower token usage, and more AI-friendly thanks to --json / --ai output you can customize, plus locator workflows (find, inspect-locators, dump-ui) for generating and reusing stable selectors.

Use it as a human for quick actions and debugging, or wire it into AI agents for testing, test-automation code generation, development workflows, and scripted pipelines.

• Appium stays Appium. This CLI does not replace your server or drivers. Point it at http://127.0.0.1:4723 (or any reachable Appium URL), create or attach a session, then drive simulators, emulators, and real devices with high-level commands.
• Machine-friendly output: --json and --ai emit structured payloads so CI, scripts, and LLM orchestration can parse results without scraping ANSI text.
• Stable exit codes for automation (see Exit codes).

If you already use an Appium MCP server inside an IDE, appium-cli covers the same ground — session lifecycle, gestures, locators, contexts, alerts, and many mobile: helpers — without requiring an MCP host.

Requirements

| Requirement | Notes | |-------------|--------| | Node.js | 18+ recommended (ESM, fetch). | | Appium server | A running Appium 2.x+ or an instance reachable over HTTP. | | Drivers | Your usual UiAutomator2 / XCUITest (or other) setup — unchanged. | | macOS (optional) | Only for host-side helpers: devices … with iOS simulators / real devices, and ios simulator prepare / ios wda prepare-real. |

Installation

From a clone (development)

git clone https://github.com/<this repo's link>
cd appium-cli
npm install

Run via the bin entry:

node ./bin/appium-cli.js --help

From npm

Install globally so appium-cli is on your PATH:

npm i -g appium-cli

Use as an agent skill (Cursor, Claude Code, Codex, …)

The repo ships the same agent skill bundle in .cursor/skills/appium-cli/ and Skill/appium-cli/ (identical files). It teaches agents how to drive appium-cli (global flags, sessions, JSON output, exit codes).

| File | Role | |------|------| | SKILL.md | Main instructions | | commands.md | Command catalogue | | recipes.md | Copy-paste flows | | troubleshooting.md | Exit codes and recovery |

Install with the CLI (after npm i -g appium-cli)

The subcommand is skill install <agent> — <agent> is required. Allowed values (case-insensitive):

| <agent> | Result | |-----------|--------| | cursor | Creates <cwd>/.cursor/skills/appium-cli/ (overwrites that folder if it already exists). Run from your app repo root (cd there first). | | claude | Creates ~/.claude/skills/appium-cli/ (user-wide for Claude Code). Current working directory does not change the destination. | | codex | Creates ~/.codex/skills/appium-cli/ (user-wide for Codex CLI). | | cwd | Copies SKILL.md, commands.md, recipes.md, and troubleshooting.md into the current directory only (no .cursor/ or other subfolders; existing files with the same names are overwritten). |

appium-cli skill install --help     # usage for this subcommand

appium-cli skill install cursor     # from your project root
appium-cli skill install claude
appium-cli skill install codex
appium-cli skill install cwd        # flat .md files into cwd

Cursor user-wide skills (~/.cursor/skills/appium-cli/) are not written by this command — copy the installed folder there manually if you want every project to see it. Do not use ~/.cursor/skills-cursor/ (reserved by Cursor).

Other agents: copy the appium-cli skill folder (or the four .md files) into paths that product's docs specify.

Quick start

1. Start Appium the way you normally do (UiAutomator2 / XCUITest drivers installed).

2. Connect — create a session with W3C capabilities (inline JSON or a file):

   Inline caps (quote the JSON in PowerShell/bash so the shell does not strip { / "):

   appium-cli connect --server http://127.0.0.1:4723 --caps '{
     "platformName": "Android",
     "appium:automationName": "UiAutomator2",
     "appium:deviceName": "Android Emulator",
     "appium:udid": "emulator-5554"
   }'

   Caps file:

   appium-cli connect --server http://127.0.0.1:4723 --caps ./caps.json

   Named session (run multiple devices or flows in parallel; pass --session on later commands):

   appium-cli connect --server http://127.0.0.1:4723 --caps ./caps.json --session smoke
   appium-cli --session smoke tap "Continue"

3. Run commands (global flags like --json work best before the subcommand):

   appium-cli tap "Login"
   appium-cli type "Email" "[email protected]"
   appium-cli swipe up
   appium-cli wait "Sign in" --timeout 15000
   appium-cli screenshot --out ./screen.png
   appium-cli --json dump-ui --simplified
   appium-cli inspect-locators "Login"

4. Disconnect when done (deletes the remote session by default):

   appium-cli disconnect

   To drop local saved state only and leave the server session running (similar to MCP “detach”):

   appium-cli disconnect --detach

Configuration

| Location | Purpose | |----------|---------| | ~/.appium-cli/session.json | Persisted sessions (connect / attach), active session name, server URL, session id. | | ~/.appium-cli/config.json | Optional global defaults (merge order: defaults → global config → ./.appium-cli.json in cwd). | | ~/.appium-cli/runs/ | Default artifact folder (e.g. screenshots when --out is omitted). | | ~/.appium-cli/cache/ | Cache (e.g. WebDriverAgent download/extract for ios helpers). |

See .appium-cli.json.example for local project overrides.

Global flags

| Flag | Description | |------|-------------| | --json | Structured JSON output (schemaVersion in payload). | | --ai | JSON tuned for agent consumption (includes suggestions where applicable). | | --session <name> | Named session (default: default). | | --timeout <ms> | Request timeout (default: 10000). | | --quiet | Suppress non-error stdout. | | --verbose | Extra diagnostics. |

Command map (overview)

Run appium-cli --help for the full sorted list and a nested commands cheat sheet (groups like session, context, app, ios, …).

Session & server

| Command | Purpose | |---------|---------| | connect | POST /session and persist state. | | attach | Attach to an existing session id (no new POST /session). | | disconnect | End session; use --detach to clear local state only. | | session status \| list \| use \| server-list | Local session file + optional GET /sessions on a server. |

Apps & device (HTTP to Appium)

| Command | Purpose | |---------|---------| | launch, terminate, install, uninstall, is-installed, background | App lifecycle. | | app list \| state \| clear-data \| deep-link | Extra app / mobile: style helpers. | | device info \| battery \| time \| shake \| notifications \| push \| pull | Device info and file transfer. | | caps | Show session capabilities from the server. |

UI & automation

| Command | Purpose | |---------|---------| | tap, type, long-press, clear, get-text, get-attr | Semantic queries against the UI tree. | | swipe, scroll, wait, scroll-to | Motion and waits. | | double-tap, pinch, drag, actions | Advanced gestures / raw W3C Actions (actions --file). | | find, active-element, inspect-locators | Locator-first and debugging workflows. | | dump-ui, inspect | Hierarchy and scored inspection. | | screenshot | Full screen or --element semantic query. |

System & settings

| Command | Purpose | |---------|---------| | context list \| switch | Native / WebView. | | alert text \| accept \| dismiss | System dialogs. | | hide-keyboard, keyboard shown | Keyboard visibility. | | orientation, clipboard get \| set, lock, unlock | Device state. | | keyevent (Android codes), press-key (named + iOS buttons) | Keys. | | send-keys | W3C keys into focused element. | | permissions get \| grant \| revoke | Android-focused; iOS varies by environment. | | geo get \| set \| reset | Location. | | record start \| stop | Screen recording (driver-dependent). | | settings get \| set | Appium session settings. | | logs types \| <type> | Log buffers. |

Host-side (not Appium HTTP)

| Command | Purpose | |---------|---------| | devices list \| caps-snippet | adb, simctl, idevice_id style discovery and cap snippets. | | ios simulator prepare | Boot simulator, optional WDA .app install (macOS). | | ios wda prepare-real | List profiles / build signed WDA IPA for real devices (macOS, signing required). |

CLI meta (no Appium)

| Command | Purpose | |---------|---------| | skill install <agent> | Copy the bundled skill for agents. Required <agent>: cursor (project .cursor/skills/appium-cli/), claude / codex (user home paths), cwd (flat .md files into current directory). See appium-cli skill install --help. |

Comparison with Appium MCP

MCP Appium servers (for example tooling used from Cursor or other MCP clients) expose tools over JSON-RPC. appium-cli exposes the same underlying Appium HTTP API (plus host helpers) as terminal commands.

Exact MCP tool names vary by server implementation; the table below uses typical Appium MCP tool families and how this CLI lines up.

| MCP-style capability | In appium-cli? | Notes | |------------------------|-------------------|--------| | Session create | Yes | connect | | Session delete | Yes | disconnect (optional server DELETE) | | Session attach / detach | Yes | attach; disconnect --detach | | List server sessions | Yes | session server-list --server <url> | | Find element / locators | Yes | find, inspect-locators, active-element | | Tap / swipe / scroll / wait | Yes | tap, swipe, scroll, wait, etc. | | Advanced gestures | Yes | double-tap, pinch, scroll-to, drag, actions --file | | Contexts & alerts | Yes | context …, alert … | | App lifecycle & device extras | Yes | app …, device …, permissions, geo, record, settings | | Screenshot (incl. element) | Yes | screenshot [--element …] | | Select device (interactive MCP flow) | Partial | devices list / caps-snippet — no interactive MCP picker | | Prepare iOS simulator / real device WDA | Partial | ios simulator prepare, ios wda prepare-real — macOS + Xcode; different UX than MCP wizards | | Doctor / environment checks (appium_skills, doctor) | No | Todo / soon: static “skills” or doctor-style checks |

Summary: For day-to-day automation against Appium HTTP, this CLI is aimed at parity with common MCP tool coverage. MCP still wins for IDE-integrated, conversational, or wizard-style flows; this CLI wins for scripts, CI, and reproducible shell pipelines.

Examples

# Connect (named session for parallel work)
appium-cli connect --server http://127.0.0.1:4723 --caps ./caps.json

# Semantic flows
appium-cli tap "Continue"
appium-cli type "Email" "[email protected]"
appium-cli swipe up

# JSON for scripts / agents
appium-cli --json caps
appium-cli --json dump-ui --simplified

# Attach to a session created elsewhere (e.g. Inspector)
appium-cli attach --server http://127.0.0.1:4723 --session-id <id> --name attached1

# Host discovery (no Appium call)
appium-cli devices list --platform android
appium-cli devices list --platform ios --kind simulator

Exit codes

Stable contract for CI:

| Code | Meaning | |------|---------| | 0 | Success | | 1 | Usage / argument error | | 2 | Element not found | | 3 | Ambiguous match | | 4 | Appium / WebDriver error | | 5 | No active session | | 6 | Timeout | | 7 | Attach / server unreachable |

Architecture (frozen choices)

• Capabilities: standard W3C JSON for connect --caps (file path or inline JSON string).
• Artifacts: under ~/.appium-cli/runs/<timestamp>/ when commands write files without an explicit path.

Roadmap & limitations (TODO:)

• Driver-dependent: mobile:* routes, recording formats, permissions on real iOS hardware, and pinch/alert behavior vary by UiAutomator2 / XCUITest and server version. Errors surface from the server when something is unsupported.
• Tests: the repo currently has no automated test suite wired to commands — todo / soon.
• Screenshot resize: no built-in “max width” PNG resize (keeps dependencies minimal); todo / soon if there is demand.
• Windows: full ios / signing flows are macOS-only by design.

Contributing

Issues and pull requests are welcome. Please:

• Keep changes focused and match existing command patterns under src/commands/.
• For behavior changes, update this README or inline --help descriptions.

License

MIT.

Acknowledgements

Built on Appium, WebDriver, and Commander.js. Not an official Appium Foundation project