# Línea de comandos

Controla tu iPhone, iPad, dispositivo Android o simulador desde Terminal, scripts de shell y CI con device-mcp-cli, la línea de comandos de Device MCP. Todos los comandos pueden responder en JSON.

`device-mcp-cli` es la línea de comandos de Device MCP. Lo que haces en la app, o le pides a tu agente de IA, también lo puedes ejecutar desde Terminal, un script de shell, un Makefile o CI: ver la lista de tus dispositivos, hacer capturas de pantalla, leer la pantalla, tocar y escribir, abrir e instalar apps, simular la ubicación y gestionar tu licencia.

Todos los comandos pueden responder en JSON, así que tus scripts leen el resultado con `jq` en lugar de analizar texto.

## 1. Instalación
* **Homebrew**: `brew install --cask device-mcp` añade `device-mcp-cli` a tu `PATH`.
* **Descargado desde el sitio web**: ejecuta esto una vez en Terminal para añadirlo a tu `PATH`:

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

El enlace sigue funcionando cuando Device MCP se actualiza. Compruébalo con:

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

## 2. Cómo funciona
* **Device MCP ejecuta tus comandos.** Los comandos de dispositivo van a la app Device MCP de tu Mac. Si no se está ejecutando, el comando pregunta antes de abrirla: `--launch` la abre sin preguntar (úsalo en scripts) y `--no-launch` nunca la abre. `status`, `mcp`, `tools` y `logs` nunca la abren.
* **Qué dispositivo**: añade `--device` (o `-d`) con el nombre o el UDID de un dispositivo. Sin él, los comandos usan el dispositivo que elegiste con `devices select` o, si no, el que está seleccionado en Device MCP.
* **JSON**: añade `--json` a cualquier comando. Los errores también llegan en JSON.
* **Tú tienes el control**: instalar y eliminar apps, abrir enlaces, leer o cambiar el portapapeles y Build & Run te piden permiso primero en Device MCP, igual que con un agente de IA. Consulta [Aprobaciones](ai-agents/approvals.md). Desvincular un dispositivo y desactivar tu licencia siempre piden permiso.
* **Free y Pro**: todos los comandos funcionan con Device MCP Free, salvo Build & Run, la instalación de apps y el inspector de vistas 3D, que requieren [Device MCP Pro](license.md). Free duplica un dispositivo a la vez.

## 3. Comandos
`<device>` es el nombre o el UDID de un dispositivo. Todos los comandos aceptan `--json`; los comandos de dispositivo aceptan `--device`.

### Dispositivos
| Comando | Qué hace |
| --- | --- |
| `devices` | Muestra la lista de tus dispositivos: nombre, tipo, sistema operativo, conexión, estado y UDID. `--all` añade todos los simuladores y emuladores, y los modelos que puede tener un simulador nuevo. |
| `devices info` | El modelo, el sistema operativo y el tamaño de pantalla de un dispositivo, y si se está duplicando y si está bloqueado. `--settings` añade sus ajustes de apariencia y accesibilidad. |
| `devices select <device>` | Elige el dispositivo que usan los comandos siguientes y lo muestra en Device MCP. |
| `devices start-mirroring`, `devices stop-mirroring` | Inicia o detiene la duplicación de un dispositivo. |
| `devices reconnect` | Vuelve a conectar un dispositivo cuya duplicación se congeló. |
| `devices unpair <device>` | Desvincula un iPhone o iPad de tu Mac. |
| `devices remove <device>` | Quita un dispositivo de la lista de Device MCP. |
| `simulators` | Muestra la lista de tus simuladores de iOS y watchOS y tus emuladores de Android. |
| `simulators start <name>` | Inicia un simulador o emulador y espera hasta que se esté ejecutando. `--model "iPhone 17 Pro"` crea un simulador nuevo. |
| `simulators stop <name>` | Apaga un simulador o emulador. |

### La pantalla
| Comando | Qué hace |
| --- | --- |
| `screenshot` | Guarda una captura de pantalla a resolución completa. `-o` elige el archivo (`.png` o `.jpg`) o la carpeta; por defecto, `~/Pictures/Device MCP`. |
| `record start`, `record stop` | Graba la pantalla en un video en `~/Movies/Device MCP`. |
| `elements` | Muestra lo que hay en la pantalla: el tipo, la etiqueta, el valor, el marco y la referencia (`e12`) de cada elemento, para `tap --ref`. |

### Toques y teclas
| Comando | Qué hace |
| --- | --- |
| `tap` | Toca un elemento por su texto (`--text "Sign In"`), por su referencia (`--ref e12`) o en un punto (`-x 120 -y 640`). `--double` toca dos veces y `--long` mantiene presionado. |
| `type <text>` | Escribe en el campo activo. `--field "Email"` rellena un campo: lo toca, lo vacía y escribe. `--submit` presiona Return. `-` lee el texto de una tubería (pipe) o de un archivo. |
| `scroll up\|down\|left\|right` | Se desplaza. `--distance 300` mueve el contenido exactamente esa cantidad de puntos. |
| `swipe --from x,y --to x,y` | Desliza de un punto a otro. |
| `press <button>` | Presiona `home`, `lock`, `volume_up`, `volume_down`, `mute`, `siri` o `back`. |
| `key <key>` | Presiona una tecla del teclado, con `--modifier command` y otros modificadores. |
| `gesture <gesture>` | `go_home`, `app_switcher`, `control_center`, `notification_center` o `spotlight`. |
| `rotate <orientation>` | `portrait`, `landscape_left`, `landscape_right` o `portrait_upside_down`. |
| `hide-keyboard` | Oculta el teclado en pantalla. |
| `wait-for <text>` | Espera hasta que el texto aparezca en la pantalla (`--gone`: hasta que desaparezca), durante `--timeout` segundos como máximo. |
| `alert accept\|dismiss` | Responde a una alerta del sistema, como una solicitud de permiso. `--button` toca un botón por su texto. |

### Apps
| Comando | Qué hace |
| --- | --- |
| `apps` | Muestra la lista de apps instaladas: nombre, bundle ID y versión. `--user` muestra solo las apps que instalaste tú. |
| `apps foreground` | La app que está en primer plano, con su bundle ID. |
| `apps launch <app>` | Abre una app por su bundle ID o su nombre. `--language`, `--locale`, `--arg` y `--env` para una ejecución de prueba. |
| `apps terminate <bundle-id>` | Cierra una app en ejecución. |
| `apps install <path>` | Instala un `.ipa`, `.app` o `.apk`. Device MCP Pro. |
| `apps uninstall <bundle-id>` | Elimina una app y sus datos. |
| `apps container <bundle-id>` | Descarga los datos de una app de desarrollo como paquete `.xcappdata`, igual que Xcode. |
| `open-url <url>` | Abre una página web o un enlace profundo (`myapp://…`). |
| `build-and-run <project>` | Compila tu proyecto de Xcode, lo instala y lo abre. Device MCP Pro. Consulta [Build & Run](ai-agents/build-and-run.md). |
| `crashes` | Muestra la lista de informes de fallos, primero los más recientes. `--app` filtra por app. |
| `crashes show <path>` | Muestra un informe de fallos: qué falló y dónde. `--app` muestra el fallo más reciente de una app. |

### Ajustes del dispositivo
| Comando | Qué hace |
| --- | --- |
| `location set <latitude> <longitude>` | Simula una ubicación. `location clear` vuelve a la ubicación real. |
| `appearance light\|dark` | Cambia el dispositivo al modo claro o al modo oscuro. |
| `clipboard get`, `clipboard set <text>` | Lee o reemplaza el texto del portapapeles del dispositivo. |

### Device MCP
| Comando | Qué hace |
| --- | --- |
| `status` | Si Device MCP se está ejecutando, su versión, su servidor MCP y tu licencia. |
| `app open`, `app quit` | Abre Device MCP en segundo plano, o lo cierra. |
| `mcp` | Si el servidor MCP está activado, y su dirección. `mcp on` y `mcp off` lo activan y lo desactivan. |
| `mcp setup claude\|codex` | Añade Device MCP a Claude Code o Codex. `--print` muestra el comando en lugar de ejecutarlo. |
| `mcp config` | El JSON que aceptan otros clientes MCP, como Cursor. |
| `license` | Tu licencia: Free, o su plan, su clave, sus puestos y las versiones que cubre. |
| `license activate <key>` | Activa una clave de licencia en este Mac. |
| `license revoke` | Desactiva la licencia en este Mac y libera su puesto. |
| `logs` | El registro de Device MCP, para un informe de errores. `-f` sigue mostrando las líneas nuevas. |

### Todo lo demás
| Comando | Qué hace |
| --- | --- |
| `call <tool> [name=value…]` | Ejecuta cualquiera de las herramientas MCP de Device MCP, igual que tu agente de IA. |
| `tools` | Muestra la lista de esas herramientas y sus argumentos. |

## 4. Ejemplos
### Inicia sesión y comprueba el resultado
Una prueba de humo (smoke test) para tu app, en un script de shell o un paso 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
}
```

### Haz una captura de pantalla de cada dispositivo
```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
```

### Toca un elemento de la pantalla
`elements` muestra la pantalla con sus referencias. Busca una con `jq` y tócala:

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

### Prueba tu app en otro idioma y otro lugar
```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
```

### Compila y ejecuta en un simulador nuevo
```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
```

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

### Configura un Mac
En un Mac de CI o en el Mac de un nuevo compañero de equipo:

```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 y códigos de salida
Con `--json`, un comando muestra un solo objeto JSON. Por ejemplo, `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"
    }
  ]
}
```

El `kind` de un dispositivo es `iphone`, `ipad`, `watch`, `android`, `simulator` o `emulator`. Su `state` es `ready`, `locked`, `blocked` (con `issue` y `fix`, que indican por qué y qué hacer), `connecting`, `running`, `shut_down`, `booting`, `shutting_down`, `creating` o `starting`.

Un error muestra `{"error": {"code": "…", "message": "…"}}`:

| Código | Código de salida | Significado |
| --- | --- | --- |
| `not_running` | 69 | Device MCP no se está ejecutando y no se abrió, o se cerró antes de responder. |
| `no_answer` | 69 | Device MCP se está ejecutando, pero no respondió: actualízalo, o ciérralo y vuelve a abrirlo. |
| `not_installed` | 69 | Device MCP no está instalado. |
| `invalid_arguments` | 64 | Un argumento incorrecto o una clave de licencia con un formato no válido. |
| `pro_required` | 1 | El comando requiere Device MCP Pro. |
| `not_approved` | 1 | Lo rechazaste en Device MCP, o nadie respondió. |
| `timed_out` | 1 | Device MCP no terminó a tiempo. |
| `cancelled` | 1 | Respondiste que no. |
| `failed` | 1 | Cualquier otro error: el mensaje indica por qué. |

Un comando que funciona sale con el código 0.

## 6. Con tu agente de IA
Tu agente también puede usar la línea de comandos, por ejemplo para escribir un script de prueba o un paso de CI para tu app:

* *"Escribe un script que inicie sesión en mi iPhone y falle si la pantalla principal no se carga."*
* *"Añade un paso de CI que haga una captura de cada pantalla del onboarding."*

Los comandos que ejecuta tu agente aparecen en la pestaña **Agent** como **device-mcp-cli**. Consulta [Actividad del agente](ai-agents/agent-activity.md).