Skip to content
ELYRA

Emulator commands

Reference for the `elyra emulator` commands that list, connect, operate and stop an emulated device.

View Markdown

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

Janela do terminal
elyra emulator list [--workspace <selector>] [--json]
elyra emulator devices [--workspace <selector>] [--json]
elyra emulator attach [device] [--device <id>|--node <id|title>] [--workspace <selector>] [--focus] [--json]
elyra emulator tap <x> <y> [--device <id>|--node <id|title>] [--workspace <selector>] [--json]
elyra emulator type "<text>" [--device <id>|--node <id|title>] [--workspace <selector>] [--json]
elyra emulator gesture '<json>' [--device <id>|--node <id|title>] [--workspace <selector>] [--json]
elyra emulator button <name> [--device <id>|--node <id|title>] [--workspace <selector>] [--json]
elyra emulator rotate <portrait|portrait_upside_down|landscape_left|landscape_right> [--device <id>|--node <id|title>] [--workspace <selector>] [--json]
elyra emulator exec --command <cmd> [--device <id>|--node <id|title>] [--workspace <selector>] [--json]
elyra emulator kill [--device <id>|--node <id|title>] [--workspace <selector>] [--json]
elyra emulator shutdown [--device <id>|--node <id|title>] [--workspace <selector>] [--json]
elyra emulator install <path> [--reinstall] [--device <id>|--node <id|title>] [--workspace <selector>] [--json]
elyra emulator launch <package> [--activity <name>] [--device <id>|--node <id|title>] [--workspace <selector>] [--json]
elyra emulator permissions <grant|revoke> <package> <permission> [--device <id>|--node <id|title>] [--workspace <selector>] [--json]
elyra emulator permissions reset [--device <id>|--node <id|title>] [--workspace <selector>] [--json]
elyra emulator ax [--device <id>|--node <id|title>] [--workspace <selector>] [--json]
elyra emulator logcat [--lines <n>] [--filters <filterspec>]... [--device <id>|--node <id|title>] [--workspace <selector>] [--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 <id> — 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 <id|title> — 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 <selector> — 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 <name>.
  • permissions uses the order <grant|revoke> <package> <permission>; reset takes neither a package nor a permission and removes every runtime grant you gave.
  • logcat accepts --lines <n> and --filters <filterspec>, 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