# karagoz text

Types into whatever has focus.

- Android emulator Done
- Android device Done
- iOS simulator Done
- iOS device Done

## Usage

```console title="~/app"
karagoz text <text> [--device <id>]
karagoz text [--device <id>] -- <text starting with ->
```

## Before you start

- On Android, for input to reach apps: the screen unlocked. On a lock screen `text` types into the PIN field, and a wrong PIN counts as a failed unlock attempt.

- On an iOS simulator:

  - Xcode, opened once.
  - With Xcode 27 or newer: a simulator on iOS 27 or newer.
  - No UI test running on the same simulator.

- 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`](https://karagozmcp.com/docs/commands/install-runner/).

## Examples

### Type into the focused field

```console title="~/app"
$ karagoz text hello
{"device":"emulator-5554","text":"hello"}
```

## Characters

Printable ASCII, newline (sent as Enter), tab (sent as Tab), `ç`, `Ç` and `ß`. Anything else fails before anything is typed:

```json
{
  "error": {
    "code": "TEXT_UNSUPPORTED",
    "message": "cannot type 'ü' (U+00FC): Android's input text types only printable ASCII, newline, tab, ç, Ç and ß; nothing was typed"
  }
}
```

Quotes, spaces and `%s` are typed as they are; Karagöz handles the escaping.

## Errors

| Code                                                                            | When                                                            |
| ------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| [`INVALID_ARGS`](https://karagozmcp.com/docs/error-codes/#invalid-args)         | Empty text.                                                     |
| [`TEXT_UNSUPPORTED`](https://karagozmcp.com/docs/error-codes/#text-unsupported) | A character outside the set under Characters. Nothing is typed. |

Long text is sent in pieces of up to 100 characters. If a piece fails, the error keeps its code and the message ends with `; <n> of <total> characters were typed before this`.

Plus [`INPUT_BLOCKED`](https://karagozmcp.com/docs/error-codes/#input-blocked), the [device selection errors](https://karagozmcp.com/docs/device-selection/#errors) and the adb errors.

## Notes

- Characters typed right after a field appears can be lost. Waiting about 2 s after the field shows up fixed it in testing.
- 100 characters take about 0.9 s.

## On an iOS simulator

Any Unicode text is typed exactly, at the cursor; iOS’s auto-capitalization and smart quotes and dashes are not applied.

```json
{
  "device": "27024DC1-EDB0-4BF2-8010-08FE3936BAB6",
  "text": "çğş it's -- ok"
}
```

- Control characters other than newline and tab fail before anything is typed: `cannot type 'U+0001' on an iOS simulator: control characters other than newline and tab; nothing was typed` ([`TEXT_UNSUPPORTED`](https://karagozmcp.com/docs/error-codes/#text-unsupported)).

- With no focused field nothing is typed, and the call still exits `0`.

- It types 120 characters a second after about 1 s of setup: 300 characters took 3.5 s.

- The first of `ui-tree`, `tap`, `swipe`, `text` or `key` on a simulator compiles a small [helper](https://karagozmcp.com/docs/requirements/#cache-folder), which takes a few seconds.

- A cancelled or timed-out call can still type the whole text: the simulator gets it in one piece.

- The call loads Xcode’s XCUIAutomation frameworks and puts the simulator in automation mode for its length, as a UI test does.

- When the call ends, the simulator turns its app accessibility setting off. `text` writes it back if it was on, so later `ui-tree` reads still see apps. An app opened while the call ends can read as an empty tree until it is opened again.

- Errors:

  - [`NOT_SUPPORTED`](https://karagozmcp.com/docs/error-codes/#not-supported) at once with Xcode 27 or newer on a simulator older than iOS 27: `'text' on an iOS 26.2 simulator needs an iOS 27 or later simulator with Xcode 27 or later; tap, swipe, key and ui-tree work on it`.
  - [`AUTOMATION_BUSY`](https://karagozmcp.com/docs/error-codes/#automation-busy) when a UI test holds the simulator.
  - [`HELPER_FAILED`](https://karagozmcp.com/docs/error-codes/#helper-failed) when the session is not granted or the typing fails.

## On an iPhone

Any Unicode text is typed exactly through Karagöz’s runner, as on the simulator.

- Control characters other than newline and tab fail before anything is sent: `cannot type 'U+0001' on an iPhone: ...` (`TEXT_UNSUPPORTED`).
- A newline acts as Return: in a single-line field it ends editing, and what follows it is not typed. A tab is typed as a tab.
- With no focused field nothing is typed, and the call still exits `0`.
- 120 characters a second: 20 characters took 0.6 s, 300 took 2.9 s.
- Errors: those of [`tap` on an iPhone](https://karagozmcp.com/docs/commands/tap/#on-an-iphone).

## MCP equivalent

MCP equivalent `text {"text":"hello"}` [MCP tools](https://karagozmcp.com/docs/mcp/#tools)

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

## Related commands

- [karagoz tap](https://karagozmcp.com/docs/commands/tap/): Its iPhone section lists the errors text gets on an iPhone.