# Befehlszeile

Steuere dein iPhone, iPad, Android-Gerät oder einen Simulator aus dem Terminal, aus Shell-Skripten und aus CI mit device-mcp-cli, der Befehlszeile von Device MCP. Jeder Befehl kann in JSON antworten.

`device-mcp-cli` ist die Befehlszeile von Device MCP. Was du in der App machst oder deinen KI-Agenten machen lässt, kannst du auch im Terminal, in einem Shell-Skript, einem Makefile oder in CI ausführen: deine Geräte auflisten, Bildschirmfotos machen, den Bildschirm lesen, tippen und Text eingeben, Apps starten und installieren, den Standort festlegen und deine Lizenz verwalten.

Jeder Befehl kann in JSON antworten, sodass deine Skripte das Ergebnis mit `jq` lesen, statt Text zu parsen.

## 1. Installation
* **Homebrew**: `brew install --cask device-mcp` legt `device-mcp-cli` in deinen `PATH`.
* **Von der Website geladen**: Führe einmal im Terminal Folgendes aus, um es in deinen `PATH` zu legen:

```bash
sudo ln -sf "/Applications/Device MCP.app/Contents/MacOS/device-mcp-cli" /usr/local/bin/device-mcp-cli
```

Der Link funktioniert weiter, wenn sich Device MCP selbst aktualisiert. Prüfe ihn mit:

```bash
device-mcp-cli --version
device-mcp-cli --help                  # every command
device-mcp-cli help apps launch        # one command, with its options
```

## 2. So funktioniert es
* **Device MCP führt deine Befehle aus.** Gerätebefehle gehen an die App Device MCP auf deinem Mac. Läuft sie nicht, fragt der Befehl, bevor er sie öffnet: `--launch` öffnet sie ohne Rückfrage (nutze das in Skripten), `--no-launch` öffnet sie nie. `status`, `mcp`, `tools` und `logs` öffnen sie nie.
* **Welches Gerät**: Hänge `--device` (oder `-d`) mit dem Namen oder der UDID eines Geräts an. Ohne diese Option verwenden Befehle das Gerät, das du mit `devices select` gewählt hast, sonst das in Device MCP ausgewählte.
* **JSON**: Hänge `--json` an einen beliebigen Befehl an. Auch Fehler kommen dann in JSON.
* **Du behältst die Kontrolle**: Bevor Apps installiert oder entfernt, Links geöffnet, die Zwischenablage gelesen oder geändert oder Build & Run gestartet wird, fragt Device MCP dich, genau wie bei einem KI-Agenten. Siehe [Freigaben](ai-agents/approvals.md). Vor dem Entkoppeln eines Geräts und dem Deaktivieren deiner Lizenz fragt Device MCP immer nach.
* **Free und Pro**: Jeder Befehl funktioniert mit Device MCP Free, außer Build & Run, dem Installieren von Apps und dem 3D-View-Inspector; dafür brauchst du [Device MCP Pro](license.md). Free spiegelt jeweils ein Gerät.

## 3. Befehle
`<device>` ist der Name oder die UDID eines Geräts. Jeder Befehl versteht `--json`, Gerätebefehle zusätzlich `--device`.

### Geräte
| Befehl | Funktion |
| --- | --- |
| `devices` | Listet deine Geräte auf: Name, Art, Betriebssystem, Verbindung, Status und UDID. `--all` ergänzt alle Simulatoren und Emulatoren sowie die Modelle, aus denen du einen neuen Simulator erstellen kannst. |
| `devices info` | Modell, Betriebssystem, Bildschirmgröße sowie Spiegelungs- und Sperrstatus eines Geräts. `--settings` ergänzt seine Einstellungen für Erscheinungsbild und Bedienungshilfen. |
| `devices select <device>` | Wählt das Gerät, das die nächsten Befehle verwenden, und zeigt es in Device MCP an. |
| `devices start-mirroring`, `devices stop-mirroring` | Startet oder beendet die Spiegelung eines Geräts. |
| `devices reconnect` | Verbindet ein Gerät neu, dessen Spiegelung eingefroren ist. |
| `devices unpair <device>` | Entkoppelt ein iPhone oder iPad von deinem Mac. |
| `devices remove <device>` | Entfernt ein Gerät aus der Liste von Device MCP. |
| `simulators` | Listet deine iOS- und watchOS-Simulatoren und Android-Emulatoren auf. |
| `simulators start <name>` | Startet einen Simulator oder Emulator und wartet, bis er läuft. `--model "iPhone 17 Pro"` erstellt einen neuen Simulator. |
| `simulators stop <name>` | Fährt einen Simulator oder Emulator herunter. |

### Der Bildschirm
| Befehl | Funktion |
| --- | --- |
| `screenshot` | Speichert ein Bildschirmfoto in voller Auflösung. `-o` wählt die Datei (`.png` oder `.jpg`) oder den Ordner; Standard ist `~/Pictures/Device MCP`. |
| `record start`, `record stop` | Nimmt den Bildschirm als Video in `~/Movies/Device MCP` auf. |
| `elements` | Listet auf, was auf dem Bildschirm ist: Typ, Beschriftung, Wert, Rahmen und Referenz (`e12`) jedes Elements, für `tap --ref`. |

### Berührungen und Tasten
| Befehl | Funktion |
| --- | --- |
| `tap` | Tippt auf ein Element anhand seines Texts (`--text "Sign In"`), anhand seiner Referenz (`--ref e12`) oder auf einen Punkt (`-x 120 -y 640`). `--double` tippt doppelt, `--long` drückt lange. |
| `type <text>` | Gibt Text in das fokussierte Feld ein. `--field "Email"` füllt ein Feld aus: tippt darauf, leert es und gibt den Text ein. `--submit` drückt die Eingabetaste. `-` liest den Text aus einer Pipe oder einer Datei. |
| `scroll up\|down\|left\|right` | Scrollt. `--distance 300` verschiebt den Inhalt um genau so viele Punkte. |
| `swipe --from x,y --to x,y` | Wischt von einem Punkt zu einem anderen. |
| `press <button>` | Drückt `home`, `lock`, `volume_up`, `volume_down`, `mute`, `siri` oder `back`. |
| `key <key>` | Drückt eine Taste der Tastatur, mit `--modifier command` und weiteren Sondertasten. |
| `gesture <gesture>` | `go_home`, `app_switcher`, `control_center`, `notification_center` oder `spotlight`. |
| `rotate <orientation>` | `portrait`, `landscape_left`, `landscape_right` oder `portrait_upside_down`. |
| `hide-keyboard` | Blendet die Bildschirmtastatur aus. |
| `wait-for <text>` | Wartet, bis der Text auf dem Bildschirm erscheint (`--gone`: bis er verschwindet), höchstens `--timeout` Sekunden. |
| `alert accept\|dismiss` | Beantwortet eine Systemabfrage, etwa eine Anfrage nach einer Berechtigung. `--button` tippt auf einen Button anhand seines Texts. |

### Apps
| Befehl | Funktion |
| --- | --- |
| `apps` | Listet die installierten Apps auf: Name, Bundle-ID und Version. `--user` listet nur die Apps, die du installiert hast. |
| `apps foreground` | Die App im Vordergrund, mit ihrer Bundle-ID. |
| `apps launch <app>` | Startet eine App anhand ihrer Bundle-ID oder ihres Namens. `--language`, `--locale`, `--arg` und `--env` für einen Teststart. |
| `apps terminate <bundle-id>` | Beendet eine laufende App. |
| `apps install <path>` | Installiert eine `.ipa`-, `.app`- oder `.apk`-Datei. Device MCP Pro. |
| `apps uninstall <bundle-id>` | Entfernt eine App und ihre Daten. |
| `apps container <bundle-id>` | Lädt die Daten einer für die Entwicklung installierten App als `.xcappdata`-Paket herunter, wie Xcode. |
| `open-url <url>` | Öffnet eine Webseite oder einen Deep Link (`myapp://…`). |
| `build-and-run <project>` | Baut dein Xcode-Projekt, installiert es und startet es. Device MCP Pro. Siehe [Build & Run](ai-agents/build-and-run.md). |
| `crashes` | Listet Absturzberichte auf, die neuesten zuerst. `--app` filtert nach App. |
| `crashes show <path>` | Zeigt einen Absturzbericht: was abgestürzt ist und wo. `--app` zeigt den neuesten Absturz einer App. |

### Geräteeinstellungen
| Befehl | Funktion |
| --- | --- |
| `location set <latitude> <longitude>` | Simuliert einen Standort. `location clear` kehrt zum echten Standort zurück. |
| `appearance light\|dark` | Schaltet das Gerät in den hellen oder dunklen Modus. |
| `clipboard get`, `clipboard set <text>` | Liest oder ersetzt den Text in der Zwischenablage des Geräts. |

### Device MCP
| Befehl | Funktion |
| --- | --- |
| `status` | Ob Device MCP läuft, seine Version, sein MCP-Server und deine Lizenz. |
| `app open`, `app quit` | Öffnet Device MCP im Hintergrund oder beendet es. |
| `mcp` | Ob der MCP-Server eingeschaltet ist, und seine Adresse. `mcp on` und `mcp off` schalten ihn ein und aus. |
| `mcp setup claude\|codex` | Fügt Device MCP zu Claude Code oder Codex hinzu. `--print` zeigt stattdessen den Befehl. |
| `mcp config` | Das JSON, das andere MCP-Clients wie Cursor erwarten. |
| `license` | Deine Lizenz: Free oder ihr Tarif, Schlüssel, Lizenzplätze und die Versionen, die sie abdeckt. |
| `license activate <key>` | Aktiviert einen Lizenzschlüssel auf diesem Mac. |
| `license revoke` | Deaktiviert die Lizenz auf diesem Mac und gibt ihren Lizenzplatz frei. |
| `logs` | Das Log von Device MCP, für einen Bugreport. `-f` gibt laufend neue Zeilen aus. |

### Alles andere
| Befehl | Funktion |
| --- | --- |
| `call <tool> [name=value…]` | Führt ein beliebiges MCP-Tool von Device MCP aus, so wie dein KI-Agent. |
| `tools` | Listet diese Tools und ihre Argumente auf. |

## 4. Beispiele
### Anmelden und das Ergebnis prüfen
Ein Smoke-Test für deine App, in einem Shell-Skript oder einem CI-Schritt:

```bash
set -e
device-mcp-cli apps launch com.example.myapp --launch
device-mcp-cli wait-for "Sign In"
device-mcp-cli type "test@example.com" --field "Email"
device-mcp-cli type - --field "Password" < password.txt
device-mcp-cli tap --text "Sign In"
device-mcp-cli wait-for "Welcome" --timeout 20 || {
  device-mcp-cli screenshot -o failure.png
  exit 1
}
```

### Ein Bildschirmfoto von jedem Gerät machen
```bash
device-mcp-cli devices --json |
  jq -r '.devices[] | select(.state == "ready" or .state == "running") | .udid' |
  while read -r udid; do device-mcp-cli screenshot --device "$udid" -o ~/Desktop/; done
```

### Auf ein Element auf dem Bildschirm tippen
`elements` listet den Bildschirm mit Referenzen auf. Finde eine mit `jq` und tippe dann darauf:

```bash
REF=$(device-mcp-cli elements --json | jq -r '.elements[] | select(.label == "General") | .ref')
device-mcp-cli tap --ref "$REF"
```

### Deine App in einer anderen Sprache und an einem anderen Ort testen
```bash
device-mcp-cli apps launch com.example.myapp --language fr --locale fr_FR
device-mcp-cli location set 48.8584 2.2945
device-mcp-cli open-url "myapp://map"
device-mcp-cli appearance dark
```

### Auf einem neuen Simulator bauen und ausführen
```bash
device-mcp-cli simulators start --model "iPhone 17 Pro" --launch
device-mcp-cli build-and-run ~/Projects/MyApp/MyApp.xcodeproj --scheme MyApp
device-mcp-cli screenshot -o ~/Desktop/myapp.png
```

### Einen Bug aufnehmen
```bash
device-mcp-cli record start
# reproduce the bug on the device
device-mcp-cli record stop
```

### Einen Mac einrichten
Auf einem CI-Mac oder dem Mac eines neuen Teammitglieds:

```bash
device-mcp-cli license activate --launch < license-key.txt
device-mcp-cli mcp on
device-mcp-cli mcp setup claude
device-mcp-cli status
```

## 5. JSON und Exit-Codes
Mit `--json` gibt ein Befehl ein einziges JSON-Objekt aus. Zum Beispiel `device-mcp-cli devices --json`:

```json
{
  "devices" : [
    {
      "connection" : "USB",
      "current" : true,
      "kind" : "iphone",
      "mirroringStopped" : false,
      "model" : "iPhone 17 Pro",
      "name" : "My iPhone",
      "osVersion" : "27.0.1",
      "platform" : "iOS",
      "state" : "ready",
      "udid" : "00008150-000A1B2C3D4E5F60"
    }
  ]
}
```

Das Feld `kind` eines Geräts ist `iphone`, `ipad`, `watch`, `android`, `simulator` oder `emulator`. Sein `state` ist `ready`, `locked`, `blocked` (dann sagen `issue` und `fix`, warum und was zu tun ist), `connecting`, `running`, `shut_down`, `booting`, `shutting_down`, `creating` oder `starting`.

Ein Fehler gibt `{"error": {"code": "…", "message": "…"}}` aus:

| Code | Exit-Code | Bedeutung |
| --- | --- | --- |
| `not_running` | 69 | Device MCP läuft nicht und wurde nicht geöffnet, oder es wurde beendet, bevor es geantwortet hat. |
| `no_answer` | 69 | Device MCP läuft, hat aber nicht geantwortet: Aktualisiere es oder beende es und öffne es erneut. |
| `not_installed` | 69 | Device MCP ist nicht installiert. |
| `invalid_arguments` | 64 | Ein falsches Argument oder ein fehlerhafter Lizenzschlüssel. |
| `pro_required` | 1 | Der Befehl erfordert Device MCP Pro. |
| `not_approved` | 1 | Du hast ihn in Device MCP abgelehnt, oder niemand hat geantwortet. |
| `timed_out` | 1 | Device MCP ist nicht rechtzeitig fertig geworden. |
| `cancelled` | 1 | Du hast mit Nein geantwortet. |
| `failed` | 1 | Alles andere: Die Meldung sagt, warum. |

Ein Befehl, der klappt, endet mit dem Exit-Code 0.

## 6. Mit deinem KI-Agenten
Auch dein Agent kann die Befehlszeile nutzen, zum Beispiel um ein Testskript oder einen CI-Schritt für deine App zu schreiben:

* *„Schreib ein Skript, das sich auf meinem iPhone anmeldet und fehlschlägt, wenn der Startbildschirm nicht lädt.“*
* *„Füg einen CI-Schritt hinzu, der von jedem Bildschirm des Onboardings ein Bildschirmfoto macht.“*

Befehle, die dein Agent ausführt, erscheinen im Tab **Agent** als **device-mcp-cli**. Siehe [Agent-Aktivität](ai-agents/agent-activity.md).