karagoz key

• Android emulator Done
• Android device Done
• iOS simulator Done
• iOS device Done

Usage

~/app

karagoz key <key> [--device <id>]

Copy

Before you start

• On Android, for the key to reach apps: the screen unlocked. On a lock screen key types into the PIN field, and a wrong PIN counts as a failed unlock attempt. With the screen off, keys still arrive; both cases exit 0.
• On an iOS simulator: Xcode 27 or newer, opened once.
• On an iPhone: paired with the Mac, Developer Mode on, connected by USB cable, Settings > Developer > Enable UI Automation on, and Karagöz’s runner installed with install-runner.

Options

<key> is an Android KeyEvent name or code:

• A name, case-insensitive, with or without KEYCODE_: HOME, back, KEYCODE_ENTER, VOLUME_UP.
• A number from 1 to 340 is a key code: key 3 is HOME. To press the digit 7, use KEYCODE_7, because key 7 is code 7, which is KEYCODE_0.

Examples

Press Home

~/app

$ karagoz key HOME
{"device":"emulator-5554","key":"KEYCODE_HOME","code":3}exit 0

Copy

Output

{
  "device": "emulator-5554",
  "key": "KEYCODE_HOME",
  "code": 3
}

Copy

device string

Serial, or the simulator's or iPhone's UDID.

key string

The resolved name.

code number

The number of the resolved key.

Errors

INVALID_ARGS: unknown key 'FOO'; use a KeyEvent name such as HOME, BACK or ENTER, or a code from 1 to 340. Checked before any device call.

A key can also get INPUT_BLOCKED, the device selection errors and the adb errors.

Notes

• A device knows the key codes of its Android version only (12: up to 288, 13: 304, 14: 316, 15: 318, 16: 337); a higher code is sent as KEYCODE_UNKNOWN, still with exit 0.
• Some keys act on the whole device: code 312 opens Recents, 318 saves a screenshot.
• Exit 0 means Android accepted the key, not that the app reacted to it.

On an iOS simulator

The same names and codes, and the same output. Only these have an iOS key:

Name	On the simulator
HOME	The Home button
POWER	The side button: locks the screen
VOLUME_UP, VOLUME_DOWN	The volume buttons
A-Z, 0-9, ENTER, DEL (backspace), FORWARD_DEL, TAB, SPACE, ESCAPE, DPAD_UP, DPAD_DOWN, DPAD_LEFT, DPAD_RIGHT, MOVE_HOME, MOVE_END, PAGE_UP, PAGE_DOWN, F1-F24, COMMA, PERIOD, MINUS, EQUALS, LEFT_BRACKET, RIGHT_BRACKET, BACKSLASH, SEMICOLON, APOSTROPHE, SLASH, GRAVE, SHIFT_*, CTRL_*, ALT_*, META_*, CAPS_LOCK	The hardware keyboard key

Any other name fails before anything is sent:

{
  "error": {
    "code": "INVALID_ARGS",
    "message": "'BACK' has no iOS simulator key; iOS takes HOME, POWER, VOLUME_UP, VOLUME_DOWN and keyboard keys (letters, digits, ENTER, DEL, TAB, ESCAPE, DPAD_*, F1-F24); tap the app's back button or swipe from the left edge"
  }
}

Copy

• Each key is pressed alone, with no modifier held.
• Keyboard keys act only where iOS uses them: in a focused field, or with Full Keyboard Access.
• A letter goes through iOS’s typing, so auto-capitalization applies: key A in an empty field typed A.
• The first of ui-tree, tap, swipe, text or key on a simulator compiles a small helper, which takes a few seconds.
• Errors: NOT_SUPPORTED, DEVICE_NOT_READY and HELPER_FAILED, as for tap.

On an iPhone

The same names, codes and output, through Karagöz’s runner. Fewer keys have an iPhone counterpart:

Name	On an iPhone
HOME	Brings the Home screen to the front; when it is already in front nothing changes (the page, an open folder).
POWER	The side button: locks the screen. Unlocking is yours, and the next runner start asks for the passcode on the phone.
VOLUME_UP, VOLUME_DOWN	The volume buttons
A-Z (typed lowercase), 0-9, SPACE, ENTER (Return), TAB, DEL (backspace), ESCAPE, MINUS, EQUALS, LEFT_BRACKET, RIGHT_BRACKET, BACKSLASH, SEMICOLON, APOSTROPHE, GRAVE, COMMA, PERIOD, SLASH	The character, typed as text types it

A key that types no character (DPAD_*, F1-F24, PAGE_UP, MOVE_HOME, FORWARD_DEL, modifiers) fails before anything is sent:

{
  "error": {
    "code": "INVALID_ARGS",
    "message": "'DPAD_UP' has no iPhone key; an iPhone takes HOME, POWER, VOLUME_UP, VOLUME_DOWN and keys that type a character (letters, digits, SPACE, ENTER, TAB, DEL, ESCAPE, punctuation)"
  }
}

Copy

A volume key takes about 0.4 s, POWER about 0.9 s. Errors: those of tap on an iPhone.

MCP equivalent

MCP equivalentkey {"key":"HOME"}MCP tools

Arguments: key (required), device. The names are the CLI's option and positional names.

Related commands

karagoz tap

On a simulator and on an iPhone, key fails with the errors tap gets.

karagoz text

On an iPhone, a key that types a character types it as text does.