tapscope-CLI-Referenz: JSON-Befehle für iOS und Android

Installieren

Den Befehl unter Einstellungen › Allgemein oder mit tapscope install-cli installieren, siehe Installation. Mit tapscope version und tapscope doctor prüfen. Der erste Befehl startet den Hintergrunddienst, falls er nicht läuft.

Ausgabe und Exit-Codes

--json an einen beliebigen Befehl hängen. Ausgegeben wird genau eine Zeile JSON:

{"command":"version","data":{"arch":"arm64","build":"1","platform":"macos","version":"0.1.0"},"ok":true}

Fehler haben dieselbe Form mit einem Objekt error statt 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 Erfolg, 1 Fehler (siehe error.code), 2 falsche Argumente. Die Texte der CLI sind englisch.

Ein typischer Ablauf

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.png

Befehle

Befehl	Funktion
`status`	Daemon, CDP-Endpunkt und Anzahl der Targets; startet den Daemon bei Bedarf.
`doctor`	Prüft die ganze Einrichtung und nennt für jedes Problem den nächsten Schritt.
`stop` / `version`	Beendet den Hintergrunddienst / zeigt die Version.
`devices list`	iPhones und iPads (USB, WLAN), Simulatoren, Android-Geräte, Netzwerk-Targets.
`devices create "<Name>" "<Typ>" [Laufzeit]`	Legt einen Simulator an, standardmäßig mit dem neuesten iOS.
`devices boot <udid>`	Bootet einen Simulator.
`targets list`	Listet die Seiten; `*` markiert die Seite dieser Sitzung.
`targets use <id>` / `targets use auto`	Wählt die Seite der Sitzung / zurück zur automatischen Wahl.
`open <url>`	Öffnet einen neuen Tab auf dem aktiven Gerät; er wird zur Seite der Sitzung.
`navigate <url>` / `reload`	Lädt eine URL in die Seite der Sitzung / lädt sie neu und wartet darauf.
`snapshot [--interactive]`	Lesbarer Seitenbaum; `--interactive` listet anklickbare und bearbeitbare Elemente als `@eN`.
`click @eN`	Klickt ein Element aus dem letzten interaktiven Snapshot.
`type @eN "<Text>"`	Ersetzt den Text eines Feldes.
`scroll [--to @eN] [--up]`	Scrollt eine Bildschirmhöhe nach unten oder oben oder zu einem Element.
`screenshot [--out <Pfad>]`	PNG des Viewports; Standardordner `~/.tapscope/screenshots/`.
`console list [--types …] [--after <id>]`	Gepufferte Konsolenmeldungen und Exceptions; Typen `error,exception,warning,log,info,debug`.
`network list [--failed] [--after <id>]`	Abgeschlossene Anfragen; `--failed` heißt Status ab 400 oder nicht abgeschlossen.
`eval "<js>"`	Führt JavaScript in der Seite aus; Promises werden abgewartet.
`devtools`	Zeigt die Chrome DevTools der Sitzungsseite in der App.
`cdp`	CDP-Endpunkte: HTTP, Browser-WebSocket, WebSocket und DevTools-URL der Seite.
`account`	Tarif und heute noch freie Sitzungen.
`login <Schlüssel>` / `logout`	Aktiviert einen Lizenzschlüssel auf diesem Mac / gibt ihn frei.
`upgrade pass` / `upgrade pro`	Öffnet den Kauf eines Pass oder Pro.
`agent-context`	Die vollständige Referenz für Coding Agents, passend zur installierten Version.
`skills list` / `skills get <Name>`	Anleitungen: `mobile-debugging`, `vscode-debugging`, `puppeteer`.
`install-cli [--dir <Ordner>]`	Verlinkt `tapscope` nach `/usr/local/bin` oder `~/.local/bin`.

Sitzungen

--session <Name> (Standard default) behält eine eigene Seitenwahl und eigene Element-Referenzen, damit mehrere Agenten oder Skripte nebeneinander arbeiten können. Welche Seite eine Sitzung nutzt:

die mit targets use <id> gewählte Seite,
sonst die Seite, die sie mit open geöffnet hat,
sonst die zuletzt von irgendeiner Sitzung geöffnete Seite,
sonst die erste Seite des aktiven Geräts.

targets use <id> in der Sitzung default legt außerdem fest, welches Gerät der CDP-Endpunkt auf Port 9222 zeigt; targets use auto hebt das auf.

Element-Referenzen

snapshot --interactive listet Knöpfe, Links und Felder als @e1, @e2 … Sie gelten bis zum nächsten interaktiven Snapshot der Sitzung oder bis zu einer Navigation. Eine ältere Referenz liefert STALE_REF: einen neuen Snapshot machen.

Nur neue Ereignisse lesen

Konsolenmeldungen und Anfragen haben je Seite aufsteigende IDs. Jede Liste endet mit lastEventId; mit --after liest du nur, was seitdem passiert ist:

tapscope console list --types error,exception --after 42

Fehlercodes

Code	Bedeutung
`INVALID_ARGUMENTS`	Falsche oder fehlende Argumente (Exit-Code 2).
`DAEMON_NOT_RUNNING`, `DAEMON_START_FAILED`	Der Hintergrunddienst war nicht erreichbar oder startete nicht.
`NO_TARGET`	Keine Seite zum Arbeiten: eine öffnen oder `devices list` prüfen.
`NO_DEVICE`	Kein Simulator gebootet und kein Gerät verbunden.
`TARGET_NOT_FOUND`, `TARGET_GONE`	Die Seiten-ID gibt es nicht (mehr); `targets list` ausführen.
`STALE_REF`	Die Referenz `@eN` stammt aus einem älteren Snapshot, oder das Element ist weg.
`ACTION_FAILED`	Das Element unterstützt die Aktion nicht, etwa Tippen in einen Knopf.
`PAGE_NOT_RESPONDING`	Gerät gesperrt oder Safari/App im Hintergrund.
`OPEN_FAILED`	Der neue Tab ist nicht erschienen; auf einem echten Gerät muss Safari offen sein.
`SIMCTL_FAILED`	simctl hat die Anfrage abgelehnt, etwa einen unbekannten Gerätetyp.
`CDP_ERROR`	Die Seite hat einen Protokollbefehl abgelehnt; die Meldung nennt Details.
`SUBSCRIPTION_REQUIRED`	Free-Tarif: Die Sitzungen für heute sind aufgebraucht; der Hinweis nennt den nächsten freien Zeitpunkt.
`LICENSE_INVALID`	Der Schlüssel ist unbekannt, abgelaufen, gesperrt oder auf zu vielen Macs aktiv.
`LICENSE_SERVER_UNAVAILABLE`	Der Lizenzserver ist nicht erreichbar.

Fehler mit retryable können bei einem späteren Versuch klappen, etwa nach dem Entsperren des Geräts.

Freie Befehle

Listen und Diagnose verbrauchen nie eine Debug-Sitzung: targets list, devices …, status, doctor, account, login, upgrade, agent-context und skills. Befehle, die auf eine Seite wirken, zählen zu den täglichen Sitzungen des Free-Tarifs, siehe Tarife und Abrechnung.