# Ligne de commande

Pilotez votre iPhone, iPad, appareil Android ou simulateur depuis Terminal, des scripts shell et la CI avec device-mcp-cli, la ligne de commande de Device MCP. Chaque commande peut répondre en JSON.

`device-mcp-cli` est la ligne de commande de Device MCP. Ce que vous faites dans l'app, ou demandez à votre agent IA de faire, vous pouvez l'exécuter depuis Terminal, un script shell, un Makefile ou la CI : lister vos appareils, prendre des captures d'écran, lire l'écran, toucher et saisir du texte, lancer et installer des apps, définir la position, et gérer votre licence.

Chaque commande peut répondre en JSON : vos scripts lisent le résultat avec `jq` au lieu d'analyser du texte.

## 1. Installation
* **Homebrew** : `brew install --cask device-mcp` place `device-mcp-cli` dans votre `PATH`.
* **Téléchargé depuis le site web** : exécutez ceci une fois dans Terminal pour l'ajouter à votre `PATH` :

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

Le lien continue de fonctionner quand Device MCP se met à jour. Vérifiez-le avec :

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

## 2. Fonctionnement
* **Device MCP exécute vos commandes.** Les commandes d'appareil sont envoyées à l'app Device MCP sur votre Mac. Si elle n'est pas en cours d'exécution, la commande vous demande avant de l'ouvrir : `--launch` l'ouvre sans demander (à utiliser dans les scripts), `--no-launch` ne l'ouvre jamais. `status`, `mcp`, `tools` et `logs` ne l'ouvrent jamais.
* **Quel appareil** : ajoutez `--device` (ou `-d`) suivi du nom ou de l'UDID d'un appareil. Sans cette option, les commandes utilisent l'appareil que vous avez choisi avec `devices select`, sinon celui qui est sélectionné dans Device MCP.
* **JSON** : ajoutez `--json` à n'importe quelle commande. Les erreurs sont elles aussi renvoyées en JSON.
* **Vous gardez le contrôle** : l'installation et la suppression d'apps, l'ouverture de liens, la lecture ou la modification du presse-papiers et Build & Run demandent d'abord votre accord dans Device MCP, comme pour un agent IA. Consultez [Approbations](ai-agents/approvals.md). La dissociation d'un appareil et la désactivation de votre licence demandent toujours votre accord.
* **Version gratuite et Pro** : toutes les commandes fonctionnent avec Device MCP Free, sauf Build & Run, l'installation d'apps et l'inspecteur de vues 3D, qui nécessitent [Device MCP Pro](license.md). Device MCP Free recopie un appareil à la fois.

## 3. Commandes
`<device>` est le nom ou l'UDID d'un appareil. Toutes les commandes acceptent `--json` ; les commandes d'appareil acceptent `--device`.

### Appareils
| Commande | Ce qu'elle fait |
| --- | --- |
| `devices` | Liste vos appareils : nom, type, OS, connexion, état et UDID. `--all` ajoute tous les simulateurs et émulateurs, ainsi que les modèles possibles pour un nouveau simulateur. |
| `devices info` | Le modèle d'un appareil, son OS, la taille de son écran, l'état de sa recopie et de son verrouillage. `--settings` ajoute ses réglages d'apparence et d'accessibilité. |
| `devices select <device>` | Choisit l'appareil qu'utilisent les commandes suivantes, et l'affiche dans Device MCP. |
| `devices start-mirroring`, `devices stop-mirroring` | Démarre ou arrête la recopie d'un appareil. |
| `devices reconnect` | Reconnecte un appareil dont la recopie s'est figée. |
| `devices unpair <device>` | Dissocie un iPhone ou un iPad de votre Mac. |
| `devices remove <device>` | Retire un appareil de la liste de Device MCP. |
| `simulators` | Liste vos simulateurs iOS et watchOS et vos émulateurs Android. |
| `simulators start <name>` | Démarre un simulateur ou un émulateur et attend qu'il soit en cours d'exécution. `--model "iPhone 17 Pro"` crée un nouveau simulateur. |
| `simulators stop <name>` | Éteint un simulateur ou un émulateur. |

### L'écran
| Commande | Ce qu'elle fait |
| --- | --- |
| `screenshot` | Enregistre une capture d'écran en pleine résolution. `-o` choisit le fichier (`.png` ou `.jpg`) ou le dossier ; par défaut, `~/Pictures/Device MCP`. |
| `record start`, `record stop` | Enregistre l'écran dans une vidéo, dans `~/Movies/Device MCP`. |
| `elements` | Liste ce qui est à l'écran : le type, le libellé, la valeur, le cadre et la référence (`e12`) de chaque élément, pour `tap --ref`. |

### Toucher et clavier
| Commande | Ce qu'elle fait |
| --- | --- |
| `tap` | Touche un élément par son texte (`--text "Sign In"`), par sa référence (`--ref e12`) ou à un point donné (`-x 120 -y 640`). `--double` touche deux fois, `--long` touche de manière prolongée. |
| `type <text>` | Saisit du texte dans le champ actif. `--field "Email"` remplit un champ : le touche, le vide, puis saisit le texte. `--submit` appuie sur Retour. `-` lit le texte depuis un pipe ou un fichier. |
| `scroll up\|down\|left\|right` | Fait défiler. `--distance 300` déplace le contenu d'exactement ce nombre de points. |
| `swipe --from x,y --to x,y` | Balaie d'un point à un autre. |
| `press <button>` | Appuie sur `home`, `lock`, `volume_up`, `volume_down`, `mute`, `siri` ou `back`. |
| `key <key>` | Appuie sur une touche du clavier, avec `--modifier command` ou un autre modificateur. |
| `gesture <gesture>` | `go_home`, `app_switcher`, `control_center`, `notification_center` ou `spotlight`. |
| `rotate <orientation>` | `portrait`, `landscape_left`, `landscape_right` ou `portrait_upside_down`. |
| `hide-keyboard` | Masque le clavier à l'écran. |
| `wait-for <text>` | Attend que le texte apparaisse à l'écran (`--gone` : qu'il disparaisse), pendant `--timeout` secondes au plus. |
| `alert accept\|dismiss` | Répond à une alerte système, comme une demande d'autorisation. `--button` touche un bouton par son texte. |

### Apps
| Commande | Ce qu'elle fait |
| --- | --- |
| `apps` | Liste les apps installées : nom, identifiant de bundle et version. `--user` ne liste que les apps que vous avez installées. |
| `apps foreground` | L'app au premier plan, avec son identifiant de bundle. |
| `apps launch <app>` | Lance une app par son identifiant de bundle ou son nom. `--language`, `--locale`, `--arg` et `--env` pour un lancement de test. |
| `apps terminate <bundle-id>` | Quitte une app en cours d'exécution. |
| `apps install <path>` | Installe un fichier `.ipa`, `.app` ou `.apk`. Device MCP Pro. |
| `apps uninstall <bundle-id>` | Supprime une app et ses données. |
| `apps container <bundle-id>` | Télécharge les données d'une app de développement sous forme de paquet `.xcappdata`, comme Xcode. |
| `open-url <url>` | Ouvre une page web ou un lien profond (`myapp://…`). |
| `build-and-run <project>` | Compile votre projet Xcode, l'installe et le lance. Device MCP Pro. Consultez [Build & Run](ai-agents/build-and-run.md). |
| `crashes` | Liste les rapports de plantage, du plus récent au plus ancien. `--app` filtre par app. |
| `crashes show <path>` | Affiche un rapport de plantage : ce qui a planté, et où. `--app` affiche le plantage le plus récent d'une app. |

### Réglages de l'appareil
| Commande | Ce qu'elle fait |
| --- | --- |
| `location set <latitude> <longitude>` | Simule une position. `location clear` revient à la position réelle. |
| `appearance light\|dark` | Passe l'appareil en mode clair ou sombre. |
| `clipboard get`, `clipboard set <text>` | Lit ou remplace le texte du presse-papiers de l'appareil. |

### Device MCP
| Commande | Ce qu'elle fait |
| --- | --- |
| `status` | Indique si Device MCP est en cours d'exécution, ainsi que sa version, son serveur MCP et votre licence. |
| `app open`, `app quit` | Ouvre Device MCP en arrière-plan, ou le quitte. |
| `mcp` | Indique si le serveur MCP est activé, et son adresse. `mcp on` et `mcp off` l'activent et le désactivent. |
| `mcp setup claude\|codex` | Ajoute Device MCP à Claude Code ou à Codex. `--print` affiche la commande à la place. |
| `mcp config` | Le JSON qu'acceptent les autres clients MCP, comme Cursor. |
| `license` | Votre licence : version gratuite, ou sa formule, sa clé, ses postes et les versions qu'elle couvre. |
| `license activate <key>` | Active une clé de licence sur ce Mac. |
| `license revoke` | Désactive la licence sur ce Mac et libère son poste. |
| `logs` | Le journal de Device MCP, pour un rapport de bug. `-f` continue d'afficher les nouvelles lignes. |

### Tout le reste
| Commande | Ce qu'elle fait |
| --- | --- |
| `call <tool> [name=value…]` | Exécute n'importe quel outil MCP de Device MCP, comme le fait votre agent IA. |
| `tools` | Liste ces outils et leurs arguments. |

## 4. Exemples
### Se connecter et vérifier le résultat
Un test de fumée pour votre app, dans un script shell ou une étape de CI :

```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
}
```

### Prendre une capture d'écran de chaque appareil
```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
```

### Toucher un élément à l'écran
`elements` liste l'écran avec des références. Trouvez-en une avec `jq`, puis touchez-la :

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

### Tester votre app dans une autre langue et à un autre endroit
```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
```

### Compiler et lancer sur un nouveau simulateur
```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
```

### Enregistrer un bug
```bash
device-mcp-cli record start
# reproduce the bug on the device
device-mcp-cli record stop
```

### Configurer un Mac
Sur un Mac de CI ou le Mac d'un nouveau collègue :

```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 et codes de sortie
Avec `--json`, une commande affiche un seul objet JSON. Par exemple, `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"
    }
  ]
}
```

Le `kind` d'un appareil vaut `iphone`, `ipad`, `watch`, `android`, `simulator` ou `emulator`. Son `state` vaut `ready`, `locked`, `blocked` (avec `issue` et `fix`, qui indiquent pourquoi et quoi faire), `connecting`, `running`, `shut_down`, `booting`, `shutting_down`, `creating` ou `starting`.

Une erreur affiche `{"error": {"code": "…", "message": "…"}}` :

| Code | Code de sortie | Signification |
| --- | --- | --- |
| `not_running` | 69 | Device MCP n'est pas en cours d'exécution et n'a pas été ouvert, ou il a quitté avant de répondre. |
| `no_answer` | 69 | Device MCP est en cours d'exécution mais n'a pas répondu : mettez-le à jour, ou quittez-le et rouvrez-le. |
| `not_installed` | 69 | Device MCP n'est pas installé. |
| `invalid_arguments` | 64 | Un argument incorrect ou une clé de licence mal formée. |
| `pro_required` | 1 | La commande nécessite Device MCP Pro. |
| `not_approved` | 1 | Vous l'avez refusée dans Device MCP, ou personne n'a répondu. |
| `timed_out` | 1 | Device MCP n'a pas terminé à temps. |
| `cancelled` | 1 | Vous avez répondu non. |
| `failed` | 1 | Tout le reste : le message indique pourquoi. |

Une commande qui réussit se termine avec le code 0.

## 6. Avec votre agent IA
Votre agent peut aussi utiliser la ligne de commande, par exemple pour écrire un script de test ou une étape de CI pour votre app :

* *« Écris un script qui se connecte sur mon iPhone et échoue si l'écran d'accueil ne se charge pas. »*
* *« Ajoute une étape de CI qui prend une capture d'écran de chaque écran du parcours d'onboarding. »*

Les commandes que lance votre agent apparaissent dans l'onglet **Agent** sous le nom **device-mcp-cli**. Consultez [Activité de l'agent](ai-agents/agent-activity.md).