TapKit CLI

Control iPhones from the terminal. Built for AI agents and developers.

tapkit tap 200 400
tapkit screenshot --open
tapkit open "Twitter"
tapkit swipe up

TapKit CLI lets you interact with real iPhones through simple shell commands. It's designed as the primary interface for AI agents (Claude Code, Codex, OpenClaw, Cursor) to control iOS devices, and works great for developers who want quick, scriptable phone control.

Install

npm install -g tapkit

Requires Node.js 18+.

Quick Start

# 1. Authenticate
tapkit auth login

# 2. Check your setup
tapkit status

# 3. See connected phones
tapkit phones

# 4. Set your active phone (only needed with multiple phones)
tapkit phone set "iPhone 15 Pro"

# 5. Take a screenshot
tapkit screenshot --open

# 6. Tap, swipe, type
tapkit tap 200 400
tapkit swipe up
tapkit type "Hello from TapKit!"

Prerequisites

• Mac running the TapKit companion app
• iPhone connected via USB or Wi-Fi
• API key from tapkit.ai/dashboard

Commands

Auth & Setup

| Command | Description | |---------|-------------| | tapkit auth login | Authenticate with API key | | tapkit auth status | Show current auth state | | tapkit auth token | Generate session token for CI | | tapkit status | Check auth, Mac app, and phone connection |

Phone Session

Set your phone once — every command after uses it automatically.

| Command | Description | |---------|-------------| | tapkit phones | List all connected phones | | tapkit phone set <name> | Set active phone (persists) | | tapkit phone | Show current active phone | | tapkit phone clear | Unset active phone |

Gestures & Input

| Command | Description | |---------|-------------| | tapkit tap <x> <y> | Tap at coordinates | | tapkit double-tap <x> <y> | Double tap | | tapkit hold <x> <y> | Long press | | tapkit swipe <direction> | Swipe up/down/left/right | | tapkit drag <x1> <y1> <x2> <y2> | Drag between points | | tapkit type <text> | Type into focused field | | tapkit escape | Dismiss keyboard/alert |

Device Control

| Command | Description | |---------|-------------| | tapkit home | Press home button | | tapkit open <app> | Open app by name | | tapkit spotlight [query] | Open Spotlight search | | tapkit lock / unlock | Lock or unlock device | | tapkit volume up / down | Volume control | | tapkit siri | Activate Siri | | tapkit shortcut <index> | Run iOS Shortcut |

Screenshots

| Command | Description | |---------|-------------| | tapkit screenshot | Save screenshot to file | | tapkit screenshot --open | Save and open in Preview | | tapkit screenshot --base64 | Output base64 to stdout | | tapkit screenshot --llm | LLM-optimized (1344px, JPEG) |

Skills

| Command | Description | |---------|-------------| | tapkit skills list | Show installed skills | | tapkit skills add <name> | Install a skill | | tapkit skills remove <name> | Remove a skill |

JSON Output

Every command supports --json for machine-readable output — designed for AI agents and scripts.

tapkit phones --json
# {"ok":true,"phones":[{"name":"iPhone 15 Pro","id":"A1B2C3","width":1179,"height":2556}]}

tapkit screenshot --base64 --json
# {"ok":true,"base64":"iVBOR...","mimeType":"image/png"}

Use with AI Agents

TapKit CLI works with any AI agent that has Bash access. Install TapKit skills to teach your agent how to navigate iOS apps:

# For Claude Code, Codex, Cursor, and 38+ other agents
npx skills add jootsing-research/tapkit-skills

# For OpenClaw
clawhub install tapkit

Skills teach agents two things:

• App knowledge — what the app looks like (tab layout, buttons, navigation)
• Task strategy — what to do (warmup playbooks, engagement patterns)

Configuration

Config is stored at ~/.tapkit/config.json:

{
  "apiKey": "tk_...",
  "phoneId": "A1B2C3D4-...",
  "phoneName": "iPhone 15 Pro"
}

Environment variables override config:

| Variable | Description | |----------|-------------| | TAPKIT_API_KEY | API key (tk_) or session token (ses_) | | TAPKIT_PHONE_ID | Default phone UUID | | TAPKIT_API_URL | Custom API endpoint |

License

MIT