--- id: "sistema.emulador-cli" titulo: "Emulator commands" resumo: "Reference for the `elyra emulator` commands that list, connect, operate and stop an emulated device." idioma: "en" 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/en/sistema/emulador-cli/" fonte: "pt-br/sistema/emulador-cli.md" caminhoPublico: "docs/publica/en/sistema/emulador-cli.md" hashFonte: "sha256:881d89ef9323d56fbb0e1a13c02e3be54ff4d5ca161d957d9b3d098dca643884" hashDestaPagina: "sha256:e18440e6af83460eb50686e412b2ad9227955451882133f90881db7c243f459c" traducaoAssistidaPorIA: true traducaoDesatualizada: false corpoRetido: false --- The `elyra emulator` family is the command-line surface of the emulated device: inventory, connection, interaction, lifecycle and the Android-only verbs. It corresponds to what the **Emulator** tab and the Canvas phone card do. ## Usage ```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] ``` ## What each command does | Command | What it does | | --- | --- | | `list` / `devices` | Inventory: running sessions / every device and AVD on the machine. | | `attach` | Starts the device's helper and makes it **active for the workspace**. | | `tap` / `type` / `gesture` | Input: a tap, text, or a gesture sequence with several points. | | `button` / `rotate` | Hardware button (such as `home` or `back`) and screen rotation. | | `exec` | Passes a raw command to the device. | | `kill` / `shutdown` | Stops the helper / stops the helper **and** powers the device off. | | `install` / `launch` / `permissions` | Android: installs an APK, launches an app by package, adjusts runtime permissions. | | `ax` / `logcat` | Android: dumps the accessibility tree and captures a logcat excerpt. | ## Shared flags - `--device ` — the explicit target: on Android an `adb` serial (for example `emulator-5554`) or the **name of an AVD**; on iOS the UDID or the Simulator name. - `--node ` — the target through the **Canvas phone card**, which stores the device id. `--device` and `--node` are mutually exclusive: passing both is refused. `list` and `devices` do not accept `--node`, because they inventory the machine, not a card. - With neither, the command acts on the **active device of the current workspace**. - `--workspace ` — reaches another workspace and its active device. - `--focus` — exists **only on `attach`**: it is the only point where Elyra brings the tab forward. - `--json` — structured output. ## Notes per command - **`attach` without a resolved target is refused** unless a workspace resolves. An explicit `--device` can start the helper without a workspace, but does not create an active session there — the following commands without a target fail with `emulator_no_active`. - **`tap`** uses normalised `0..1` coordinates, origin at the top-left corner; outside that range it is refused. - **`type`** accepts US ASCII only, and text with a space must be quoted — without them each word becomes a loose argument and the command is refused. - **`gesture`** takes JSON with 2 to 64 points, each `{"type":"begin|move|end","x":0..1,"y":0..1}` and an optional `"edge"` from 0 to 4. On Android it becomes a straight drag between the first and last point. - **`button`** accepts hardware button names — an unknown name is refused by name — and **`rotate`** accepts `portrait`, `portrait_upside_down`, `landscape_left` or `landscape_right`. - **`exec`** is a raw passthrough to the device and **can change the simulator's state**. On Android it runs the string in the device shell and returns only stdout. - **`kill` and `shutdown` are not synonyms.** `kill` stops Elyra's helper and frees the session, leaving the device on. `shutdown` stops the helper **and** powers off the simulator device — use it only on a device Elyra started, because it shuts down your own emulator just as readily. - **`install`** takes the path of an APK and `--reinstall` to replace an existing install; **`launch`** takes the package and, optionally, `--activity `. - **`permissions`** uses the order ` `; `reset` takes neither a package nor a permission and removes every runtime grant you gave. - **`logcat`** accepts `--lines ` and `--filters `, repeatable once per tag. Each value is `TAG:PRIORITY`, with priority among `V D I W E F S` and `*` as the wildcard tag. A tag starting with `-` is refused by name, because logcat would read it as an option. ## Limits and defaults - **`install`, `launch`, `permissions`, `ax` and `logcat` are Android-only.** On a Simulator they are refused with `emulator_unsupported`. The other commands work on both platforms. - **`attach` waits up to 180 s**, because of booting a powered-off AVD; the other commands wait up to 60 s. That is how long Elyra waits, not how long the device takes: a timeout means it stopped watching, not that the work was undone. - **An AVD that Elyra boots on its own runs headless**: the picture is the Elyra tab, not a separate window. - **There is no screenshot in this family**, on either platform. On Android, what you read back is the accessibility tree; on iOS that verb is refused. There is also no verb to uninstall an app or to copy a file off the device. - **An empty list is not the same thing as a broken backend.** Inventory replies carry the backends that failed next to the results, instead of silently shrinking the list. Counts, times and messages can change between releases. ## Errors and recovery | Error | What to do | | --- | --- | | `emulator_no_active` | No active device in the workspace: connect one in the device panel, or pass `--device` / `--node`. | | `emulator_device_not_found` | The id does not exist on this machine: run `elyra emulator devices --json` and use the listed id. | | `emulator_unsupported` / `emulator_not_macos` | The verb is Android-only and the target is a Simulator, or the iOS path was asked for outside macOS: switch device or use Android. | | `emulator_helper_failed` | The helper did not start: re-read the message, check the toolchain and try `attach` again. | | `emulator_error` | Unclassified error. The original message comes with it, untranslated, so you can search for it. | ## Next steps - [Mobile emulator](/docs/en/sistema/emulador/) - [Interact with the emulated device](/docs/en/sistema/emulador-interacao/) - [Install, launch and read an app on the emulated Android](/docs/en/sistema/emulador-android/)