--- id: "sistema.emulador-cli" titulo: "Comandos do emulador" resumo: "Referência dos comandos `elyra emulator` para listar, conectar, operar e encerrar um aparelho emulado." idioma: "pt-br" tipo: "referencia" categoria: "ambientes" aplicavelDesde: "0.0.16" capabilities: ["devices.emulator.discovery", "devices.emulator.interact", "devices.emulator.lifecycle", "devices.android.apps", "devices.android.diagnostics"] estadoEditorial: "aprovado" nivelEvidencia: "artefato-distribuido" refFonte: "27574c339b58316408f6be2d62169d59041d07bf" revisaoFonte: "2026-09-24" revisor: "mantenedor (v1, 2026-10-03)" rota: "/docs/pt-br/sistema/emulador-cli/" fonte: "pt-br/sistema/emulador-cli.md" caminhoPublico: "docs/publica/pt-br/sistema/emulador-cli.md" hashFonte: "sha256:881d89ef9323d56fbb0e1a13c02e3be54ff4d5ca161d957d9b3d098dca643884" hashDestaPagina: "sha256:881d89ef9323d56fbb0e1a13c02e3be54ff4d5ca161d957d9b3d098dca643884" traducaoAssistidaPorIA: false traducaoDesatualizada: false corpoRetido: false --- A família `elyra emulator` é a superfície de linha de comando do aparelho emulado: inventário, conexão, interação, ciclo de vida e os verbos exclusivos do Android. Ela corresponde ao que a aba **Emulador** e o cartão de celular do Canvas fazem. ## Uso ```bash elyra emulator list [--workspace ] [--json] elyra emulator devices [--workspace ] [--json] elyra emulator attach [device] [--device |--node ] [--workspace ] [--focus] [--json] elyra emulator tap [--device |--node ] [--workspace ] [--json] elyra emulator type "" [--device |--node ] [--workspace ] [--json] elyra emulator gesture '' [--device |--node ] [--workspace ] [--json] elyra emulator button [--device |--node ] [--workspace ] [--json] elyra emulator rotate [--device |--node ] [--workspace ] [--json] elyra emulator exec --command [--device |--node ] [--workspace ] [--json] elyra emulator kill [--device |--node ] [--workspace ] [--json] elyra emulator shutdown [--device |--node ] [--workspace ] [--json] elyra emulator install [--reinstall] [--device |--node ] [--workspace ] [--json] elyra emulator launch [--activity ] [--device |--node ] [--workspace ] [--json] elyra emulator permissions [--device |--node ] [--workspace ] [--json] elyra emulator permissions reset [--device |--node ] [--workspace ] [--json] elyra emulator ax [--device |--node ] [--workspace ] [--json] elyra emulator logcat [--lines ] [--filters ]... [--device |--node ] [--workspace ] [--json] ``` ## O que cada comando faz | Comando | O que faz | | --- | --- | | `list` / `devices` | Inventário: sessões em execução / todos os dispositivos e AVDs da máquina. | | `attach` | Inicia o auxiliar do dispositivo e o torna **ativo para o workspace**. | | `tap` / `type` / `gesture` | Entrada: um toque, texto, ou uma sequência de gesto com vários pontos. | | `button` / `rotate` | Botão de hardware (como `home` ou `back`) e giro da tela. | | `exec` | Passa um comando bruto para o dispositivo. | | `kill` / `shutdown` | Encerra o auxiliar / encerra o auxiliar **e** desliga o dispositivo. | | `install` / `launch` / `permissions` | Android: instala APK, inicia app por pacote, ajusta permissões de runtime. | | `ax` / `logcat` | Android: despeja a árvore de acessibilidade e captura um recorte do logcat. | ## Flags compartilhadas - `--device ` — o alvo explícito: no Android um serial do `adb` (por exemplo `emulator-5554`) ou o **nome de um AVD**; no iOS o UDID ou o nome do Simulator. - `--node ` — o alvo pelo **cartão de celular do Canvas**, que guarda o id do dispositivo. `--device` e `--node` são mutuamente exclusivos: passar os dois é recusado. `list` e `devices` não aceitam `--node`, porque inventariam a máquina, não um cartão. - Sem nenhum dos dois, o comando age sobre o **dispositivo ativo do workspace** atual. - `--workspace ` — alcança outro workspace e o dispositivo ativo dele. - `--focus` — existe **somente em `attach`**: é o único ponto em que o Elyra traz a aba para a frente. - `--json` — saída estruturada. ## Notas por comando - **`attach` sem alvo resolvido é recusado** a menos que um workspace resolva. Um `--device` explícito pode iniciar o auxiliar sem workspace, mas não cria sessão ativa ali — os comandos seguintes sem alvo falham com `emulator_no_active`. - **`tap`** usa coordenadas normalizadas `0..1`, origem no canto superior esquerdo; fora da faixa é recusado. - **`type`** aceita apenas US ASCII, e texto com espaço precisa estar entre aspas — sem elas cada palavra vira um argumento solto e o comando é recusado. - **`gesture`** recebe JSON com 2 a 64 pontos, cada um `{"type":"begin|move|end","x":0..1,"y":0..1}` e um `"edge"` opcional de 0 a 4. No Android ele vira um arrasto reto entre o primeiro e o último ponto. - **`button`** aceita nomes de botão de hardware — um nome desconhecido é recusado pelo nome — e **`rotate`** aceita `portrait`, `portrait_upside_down`, `landscape_left` ou `landscape_right`. - **`exec`** é passthrough bruto para o dispositivo e **pode alterar o estado do simulador**. No Android ele roda a string no shell do dispositivo e devolve apenas o stdout. - **`kill` e `shutdown` não são sinônimos.** `kill` encerra o auxiliar do Elyra e libera a sessão, deixando o dispositivo ligado. `shutdown` encerra o auxiliar **e** desliga o dispositivo do simulador — use-o apenas num aparelho que o Elyra iniciou, porque ele desliga o seu emulador com a mesma facilidade. - **`install`** recebe o caminho de um APK e `--reinstall` para substituir uma instalação existente; **`launch`** recebe o pacote e, opcionalmente, `--activity `. - **`permissions`** usa a ordem ` `; `reset` não recebe pacote nem permissão e remove todas as concessões de runtime que você deu. - **`logcat`** aceita `--lines ` e `--filters `, repetível uma vez por tag. Cada valor é `TAG:PRIORIDADE`, com prioridade entre `V D I W E F S` e `*` como tag curinga. Uma tag que comece com `-` é recusada pelo nome, porque o logcat a leria como opção. ## Limites e padrões - **`install`, `launch`, `permissions`, `ax` e `logcat` são exclusivos do Android.** Num Simulator eles são recusados com `emulator_unsupported`. Os demais comandos valem nas duas plataformas. - **O `attach` espera até 180 s**, por causa do boot de um AVD desligado; os outros comandos esperam até 60 s. Isso é o tempo que o Elyra espera, não o tempo que o dispositivo leva: um timeout significa que ele parou de acompanhar, não que o trabalho foi desfeito. - **Um AVD que o Elyra liga sozinho roda headless**: a imagem é a aba do Elyra, não uma janela separada. - **Não existe captura de tela nesta família**, em nenhuma plataforma. No Android, o que se lê de volta é a árvore de acessibilidade; no iOS esse verbo é recusado. Também não há verbo para desinstalar um app nem para copiar um arquivo do dispositivo. - **Uma lista vazia não é a mesma coisa que um backend quebrado.** As respostas de inventário trazem os backends que falharam ao lado dos resultados, em vez de encolher a lista em silêncio. Contagens, tempos e mensagens podem mudar entre releases. ## Erros e recuperação | Erro | O que fazer | | --- | --- | | `emulator_no_active` | Nenhum dispositivo ativo no workspace: conecte um no painel do aparelho, ou passe `--device` / `--node`. | | `emulator_device_not_found` | O id não existe nesta máquina: rode `elyra emulator devices --json` e use o id listado. | | `emulator_unsupported` / `emulator_not_macos` | O verbo é exclusivo do Android e o alvo é um Simulator, ou o caminho de iOS foi pedido fora do macOS: troque de dispositivo ou use Android. | | `emulator_helper_failed` | O auxiliar não subiu: releia a mensagem, confira a toolchain e tente o `attach` de novo. | | `emulator_error` | Erro não classificado. A mensagem original vem junto, sem tradução, para você poder pesquisar. | ## Próximos passos - [Emulador de celular](/docs/pt-br/sistema/emulador/) - [Interagir com o aparelho emulado](/docs/pt-br/sistema/emulador-interacao/) - [Instalar, iniciar e ler um app no Android emulado](/docs/pt-br/sistema/emulador-android/)