Install
Install the command from Settings › General or with tapscope install-cli, see Installation. Check it with tapscope version and tapscope doctor. The first command starts the background service if it is not running.
Output and exit codes
Add --json to any command. Exactly one line of JSON is printed:
{"command":"version","data":{"arch":"arm64","build":"1","platform":"macos","version":"0.1.0"},"ok":true}Errors have the same shape with an error object instead of data:
{"command":"eval","error":{"code":"PAGE_NOT_RESPONDING","hint":"Unlock the device and bring Safari or the app to the foreground.","message":"…","retryable":true},"ok":false}Exit codes: 0 success, 1 failure (see error.code), 2 wrong arguments.
A typical run
tapscope devices list
tapscope open https://example.com
tapscope snapshot --interactive
tapscope click @e3
tapscope console list --types error,exception
tapscope network list --failed
tapscope reload
tapscope screenshot --out page.pngCommands
| Command | What it does |
|---|---|
status | Daemon, CDP endpoint and number of targets; starts the daemon if needed. |
doctor | Checks the whole setup and prints a next step for every problem. |
stop / version | Stops the background service / prints the version. |
devices list | iPhones and iPads (USB, Wi-Fi), simulators, Android devices, network targets. |
devices create "<name>" "<type>" [runtime] | Creates a simulator, with the newest iOS by default. |
devices boot <udid> | Boots a simulator. |
targets list | Lists the pages; * marks the one this session works on. |
targets use <id> / targets use auto | Picks the page for this session / goes back to the automatic choice. |
open <url> | Opens a new tab on the active device; it becomes the session’s page. |
navigate <url> / reload | Loads a URL in the session’s page / reloads it, and waits for it. |
snapshot [--interactive] | Readable page tree; --interactive lists clickable and editable elements as @eN. |
click @eN | Clicks an element from the last interactive snapshot. |
type @eN "<text>" | Replaces the text of a field. |
scroll [--to @eN] [--up] | Scrolls a screen down or up, or to an element. |
screenshot [--out <path>] | PNG of the viewport; default folder ~/.tapscope/screenshots/. |
console list [--types …] [--after <id>] | Buffered console messages and exceptions; types error,exception,warning,log,info,debug. |
network list [--failed] [--after <id>] | Finished requests; --failed means status 400 or higher, or not completed. |
eval "<js>" | Evaluates JavaScript in the page; promises are awaited. |
devtools | Shows the Chrome DevTools for the session’s page in the app. |
cdp | CDP endpoints: HTTP, browser WebSocket, the page’s WebSocket and DevTools URL. |
account | Plan and free sessions left today. |
login <key> / logout | Activates a license key on this Mac / releases it. |
upgrade pass / upgrade pro | Opens the checkout for a Pass or Pro. |
agent-context | The full reference for coding agents, matching the installed version. |
skills list / skills get <name> | Task guides: mobile-debugging, vscode-debugging, puppeteer. |
install-cli [--dir <dir>] | Links tapscope into /usr/local/bin or ~/.local/bin. |
Sessions
--session <name> (default default) keeps its own page choice and element references, so several agents or scripts can work side by side. Which page a session uses:
- the page chosen with
targets use <id>, - otherwise the page it opened with
open, - otherwise the page last opened by any session,
- otherwise the first page of the active device.
targets use <id> in the default session also decides which device the CDP endpoint on port 9222 shows; targets use auto releases it.
Element references
snapshot --interactive lists buttons, links and fields as @e1, @e2 … They stay valid until the session’s next interactive snapshot or a navigation. An older reference returns STALE_REF: take a new snapshot.
Reading only new events
Console messages and requests have ascending ids per page. Each list ends with lastEventId; pass it as --after to read only what happened since:
tapscope console list --types error,exception --after 42Error codes
| Code | Meaning |
|---|---|
INVALID_ARGUMENTS | Wrong or missing arguments (exit code 2). |
DAEMON_NOT_RUNNING, DAEMON_START_FAILED | The background service could not be reached or started. |
NO_TARGET | No page to work on: open one or check devices list. |
NO_DEVICE | No simulator booted and no device connected. |
TARGET_NOT_FOUND, TARGET_GONE | The page id does not exist (any more); run targets list. |
STALE_REF | The @eN reference is from an older snapshot or the element is gone. |
ACTION_FAILED | The element does not support the action, for example typing into a button. |
PAGE_NOT_RESPONDING | Device locked or Safari/app in the background. |
OPEN_FAILED | The new tab did not appear; on a real device Safari must be open. |
SIMCTL_FAILED | simctl rejected the request, for example an unknown device type. |
CDP_ERROR | The page rejected a protocol command; the message has details. |
SUBSCRIPTION_REQUIRED | Free plan: today’s sessions are used up; the hint names the next free time. |
LICENSE_INVALID | The key is unknown, expired, disabled or active on too many Macs. |
LICENSE_SERVER_UNAVAILABLE | The license server cannot be reached. |
Errors marked retryable can succeed on a later attempt, for example after unlocking the device.
Free commands
Listing and diagnostics never use a debug session: targets list, devices …, status, doctor, account, login, upgrade, agent-context and skills. Commands that act on a page count towards the Free plan’s daily sessions, see Plans and billing.