# Linha de comando

Controle seu iPhone, iPad, dispositivo Android ou simulador pelo Terminal, por scripts de shell e em CI com o device-mcp-cli, a linha de comando do Device MCP. Todo comando pode responder em JSON.

O `device-mcp-cli` é a linha de comando do Device MCP. O que você faz no app, ou pede ao seu agente de IA, você também pode executar no Terminal, em um script de shell, em um Makefile ou em CI: listar seus dispositivos, fazer capturas de tela, ler a tela, tocar e digitar, abrir e instalar apps, definir a localização e gerenciar sua licença.

Todo comando pode responder em JSON, então seus scripts leem o resultado com `jq` em vez de analisar texto.

## 1. Instalação
* **Homebrew**: `brew install --cask device-mcp` coloca o `device-mcp-cli` no seu `PATH`.
* **Baixado do site**: execute isto uma vez no Terminal para colocá-lo no seu `PATH`:

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

O link continua funcionando quando o Device MCP se atualiza. Confira com:

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

## 2. Como funciona
* **O Device MCP executa seus comandos.** Os comandos de dispositivo vão para o app Device MCP no seu Mac. Se ele não estiver em execução, o comando pergunta antes de abri-lo: `--launch` o abre sem perguntar (use em scripts), `--no-launch` nunca o abre. `status`, `mcp`, `tools` e `logs` nunca o abrem.
* **Qual dispositivo**: adicione `--device` (ou `-d`) com o nome ou o UDID de um dispositivo. Sem ele, os comandos usam o dispositivo que você escolheu com `devices select`; se não houver, o que está selecionado no Device MCP.
* **JSON**: adicione `--json` a qualquer comando. Os erros também vêm em JSON.
* **Você no comando**: instalar e remover apps, abrir links, ler ou alterar a área de transferência e o Build & Run pedem sua aprovação no Device MCP antes, como acontece com um agente de IA. Veja [Aprovações](ai-agents/approvals.md). Desfazer o pareamento de um dispositivo e desativar sua licença sempre pedem confirmação.
* **Gratuito e Pro**: todos os comandos funcionam no Device MCP Free, exceto o Build & Run, a instalação de apps e o inspetor de views em 3D, que exigem o [Device MCP Pro](license.md). O Device MCP Free espelha um dispositivo por vez.

## 3. Comandos
`<device>` é o nome ou o UDID de um dispositivo. Todo comando aceita `--json`; os comandos de dispositivo aceitam `--device`.

### Dispositivos
| Comando | O que faz |
| --- | --- |
| `devices` | Lista seus dispositivos: nome, tipo, sistema, conexão, estado e UDID. `--all` adiciona todos os simuladores e emuladores, e os modelos que um novo simulador pode ter. |
| `devices info` | O modelo, o sistema, o tamanho da tela e o estado do espelhamento e do bloqueio de um dispositivo. `--settings` adiciona os ajustes de aparência e de acessibilidade dele. |
| `devices select <device>` | Escolhe o dispositivo que os próximos comandos usam e o mostra no Device MCP. |
| `devices start-mirroring`, `devices stop-mirroring` | Inicia ou para o espelhamento de um dispositivo. |
| `devices reconnect` | Reconecta um dispositivo cujo espelhamento congelou. |
| `devices unpair <device>` | Desfaz o pareamento entre um iPhone ou iPad e o seu Mac. |
| `devices remove <device>` | Tira um dispositivo da lista do Device MCP. |
| `simulators` | Lista seus simuladores do iOS e do watchOS e seus emuladores Android. |
| `simulators start <name>` | Inicia um simulador ou emulador e espera até ele estar em execução. `--model "iPhone 17 Pro"` cria um novo simulador. |
| `simulators stop <name>` | Desliga um simulador ou emulador. |

### A tela
| Comando | O que faz |
| --- | --- |
| `screenshot` | Salva uma captura de tela em resolução máxima. `-o` escolhe o arquivo (`.png` ou `.jpg`) ou a pasta; o padrão é `~/Pictures/Device MCP`. |
| `record start`, `record stop` | Grava a tela em um vídeo em `~/Movies/Device MCP`. |
| `elements` | Lista o que está na tela: o tipo, o rótulo, o valor, o frame e a ref (`e12`) de cada elemento, para usar com `tap --ref`. |

### Toque e teclas
| Comando | O que faz |
| --- | --- |
| `tap` | Toca em um elemento pelo texto (`--text "Sign In"`), pela ref (`--ref e12`) ou em um ponto (`-x 120 -y 640`). `--double` toca duas vezes, `--long` faz um toque longo. |
| `type <text>` | Digita no campo em foco. `--field "Email"` preenche um campo: toca nele, apaga o conteúdo e digita. `--submit` pressiona Return. `-` lê o texto de um pipe ou de um arquivo. |
| `scroll up\|down\|left\|right` | Rola a tela. `--distance 300` move o conteúdo exatamente esse número de pontos. |
| `swipe --from x,y --to x,y` | Desliza o dedo de um ponto a outro. |
| `press <button>` | Pressiona `home`, `lock`, `volume_up`, `volume_down`, `mute`, `siri` ou `back`. |
| `key <key>` | Pressiona uma tecla do teclado, com `--modifier command` e outros modificadores. |
| `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` | Oculta o teclado na tela. |
| `wait-for <text>` | Espera até o texto aparecer na tela (`--gone`: até ele sumir), por no máximo `--timeout` segundos. |
| `alert accept\|dismiss` | Responde a um alerta do sistema, como um pedido de permissão. `--button` toca em um botão pelo texto. |

### Apps
| Comando | O que faz |
| --- | --- |
| `apps` | Lista os apps instalados: nome, bundle ID e versão. `--user` lista só os apps que você instalou. |
| `apps foreground` | O app em primeiro plano, com o bundle ID dele. |
| `apps launch <app>` | Abre um app pelo bundle ID ou pelo nome. `--language`, `--locale`, `--arg` e `--env` para uma abertura de teste. |
| `apps terminate <bundle-id>` | Encerra um app em execução. |
| `apps install <path>` | Instala um `.ipa`, `.app` ou `.apk`. Device MCP Pro. |
| `apps uninstall <bundle-id>` | Remove um app e os dados dele. |
| `apps container <bundle-id>` | Baixa os dados de um app de desenvolvimento como um pacote `.xcappdata`, como o Xcode. |
| `open-url <url>` | Abre uma página da web ou um deep link (`myapp://…`). |
| `build-and-run <project>` | Compila seu projeto Xcode, instala e abre o app. Device MCP Pro. Veja [Build & Run](ai-agents/build-and-run.md). |
| `crashes` | Lista os relatórios de falhas, do mais recente ao mais antigo. `--app` filtra por app. |
| `crashes show <path>` | Mostra um relatório de falhas: o que falhou e onde. `--app` mostra a falha mais recente de um app. |

### Ajustes do dispositivo
| Comando | O que faz |
| --- | --- |
| `location set <latitude> <longitude>` | Simula uma localização. `location clear` volta à localização real. |
| `appearance light\|dark` | Muda o dispositivo para o modo claro ou escuro. |
| `clipboard get`, `clipboard set <text>` | Lê ou substitui o texto da área de transferência do dispositivo. |

### Device MCP
| Comando | O que faz |
| --- | --- |
| `status` | Se o Device MCP está em execução, a versão dele, o servidor MCP e sua licença. |
| `app open`, `app quit` | Abre o Device MCP em segundo plano ou o encerra. |
| `mcp` | Se o servidor MCP está ativado, e o endereço dele. `mcp on` e `mcp off` o ativam e desativam. |
| `mcp setup claude\|codex` | Adiciona o Device MCP ao Claude Code ou ao Codex. `--print` mostra o comando em vez de executá-lo. |
| `mcp config` | O JSON que outros clientes MCP, como o Cursor, usam. |
| `license` | Sua licença: Free, ou o plano, a chave, os assentos e as versões que ela cobre. |
| `license activate <key>` | Ativa uma chave de licença neste Mac. |
| `license revoke` | Desativa a licença neste Mac e libera o assento dela. |
| `logs` | O log do Device MCP, para um relatório de bug. `-f` continua mostrando as linhas novas. |

### Todo o resto
| Comando | O que faz |
| --- | --- |
| `call <tool> [name=value…]` | Executa qualquer uma das ferramentas MCP do Device MCP, do jeito que seu agente de IA faz. |
| `tools` | Lista essas ferramentas e os argumentos delas. |

## 4. Exemplos
### Faça login e confira o resultado
Um smoke test do seu app, em um script de shell ou em uma etapa 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
}
```

### Faça uma captura de tela 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
```

### Toque em um elemento da tela
`elements` lista a tela com as refs. Encontre uma com `jq` e toque nela:

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

### Teste seu app em outro idioma e outro 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
```

### Compile e execute em um novo simulador
```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
```

### Grave um bug
```bash
device-mcp-cli record start
# reproduce the bug on the device
device-mcp-cli record stop
```

### Configure um Mac
Em um Mac de CI ou no Mac de um novo colega de equipe:

```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 e códigos de saída
Com `--json`, um comando imprime um único objeto JSON. Por exemplo, `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"
    }
  ]
}
```

O `kind` de um dispositivo é `iphone`, `ipad`, `watch`, `android`, `simulator` ou `emulator`. O `state` dele é `ready`, `locked`, `blocked` (com `issue` e `fix` dizendo o motivo e o que fazer), `connecting`, `running`, `shut_down`, `booting`, `shutting_down`, `creating` ou `starting`.

Um erro imprime `{"error": {"code": "…", "message": "…"}}`:

| Código | Código de saída | Significado |
| --- | --- | --- |
| `not_running` | 69 | O Device MCP não está em execução e não foi aberto, ou foi encerrado antes de responder. |
| `no_answer` | 69 | O Device MCP está em execução, mas não respondeu: atualize-o, ou encerre-o e abra-o de novo. |
| `not_installed` | 69 | O Device MCP não está instalado. |
| `invalid_arguments` | 64 | Um argumento errado ou uma chave de licença malformada. |
| `pro_required` | 1 | O comando exige o Device MCP Pro. |
| `not_approved` | 1 | Você recusou no Device MCP, ou ninguém respondeu. |
| `timed_out` | 1 | O Device MCP não terminou a tempo. |
| `cancelled` | 1 | Você respondeu que não. |
| `failed` | 1 | Qualquer outro erro: a mensagem diz o motivo. |

Um comando bem-sucedido termina com o código 0.

## 6. Com seu agente de IA
Seu agente também pode usar a linha de comando, por exemplo, para escrever um script de teste ou uma etapa de CI para o seu app:

* *"Escreva um script que faça login no meu iPhone e falhe se a tela inicial não carregar."*
* *"Adicione uma etapa de CI que faça uma captura de tela de cada tela do onboarding."*

Os comandos que seu agente executa aparecem na aba **Agent** como **device-mcp-cli**. Veja [Atividade do agente](ai-agents/agent-activity.md).