How to Test on Real Android and iOS Devices with Kane CLI

Kane CLI runs your native app tests on real Android and iOS devices in the cloud. Use a real device when you want to see how your app behaves on actual hardware. You write and run these tests the same way as an emulator or simulator test, from any machine: macOS (Intel or Apple Silicon), Linux, or Windows. You do not need Xcode, Android Studio, or kane-cli doctor --install. Kane CLI asks the device hub for a device, installs your app on it, and drives it. The device hub is the cloud service that hands out real devices to test sessions. A session is the period during which Kane CLI holds one device for you.

Requires Kane CLI 0.9.0 or later. Check your version with kane-cli --version.

Target	Drives	Builds it takes
`android`	A real Android device in the cloud	`.apk`, `.aab`, or an `APP…` id
`ios`	A real iOS device in the cloud	`.ipa`, or an `APP…` id

emulator and simulator mean virtual devices on your Mac. See Mobile Testing. android and ios always mean real devices.

Plan Requirements

To run on real devices, your account needs one of these plans. See pricing.

Plan	What you get
KaneAI Max	One real device. One real-device session runs at a time.
KaneAI credits + Real Device Plus Automation Cloud	Real devices from the automation plan, as many at once as its parallel tests allow. Credits are account-wide, so credits from any KaneAI plan qualify.

When you start more real-device sessions than your plan allows, the extra session queues for up to 15 minutes. For example, --parallel 2 on KaneAI Max starts one session too many. If a device frees up in that time, the session runs. Otherwise the run fails with failed to open the mobile hub session: <reason>. If your account has neither plan, the run fails with the same message, and the hub’s reason follows the colon.

Quick Start

kane-cli login                                                    # once
kane-cli run "Sign in and open the account tab" --target android --app ./builds/app-release.apk
kane-cli run "Add the first item to the cart" --target ios --app ./builds/MyApp.ipa

Kane CLI prints the device it got before the first step:

Connecting to a real Android device…
Running on: Real device · Galaxy S24 · Android 14 · App APP1234567

Choosing a Device

You do not have to choose. With no device named, the hub picks any free device for the platform. To pick a specific device, list the devices the cloud offers. Listing needs no login:

kane-cli devices list --target android --remote
kane-cli devices list --target ios --remote --os-version 17

Then name the device on the run, or save it as a default:

kane-cli run "<objective>" --target android --device-name "Galaxy S24" --app ./app.apk
kane-cli run "<objective>" --target ios --os-version 17 --app ./MyApp.ipa      # any iPhone on iOS 17

kane-cli config set-target android
kane-cli config set-device-name "Pixel.*"     # a name or a pattern
kane-cli config set-os-version 15

Either one alone is enough. --device-name alone means that device on any version. --os-version alone means any device on that version. Emulators and simulators need both.
A name can be a pattern. A pattern is a name that matches several devices. If your name matches an entry in the list exactly, you get that device. Anything else is read as a case-insensitive regular expression, so Pixel.* means any Pixel.
Versions match by major. 17.5 matches any iOS 17 device.
Order of precedence: the flag first, then the saved config (or the test file’s device_name: / os_version:), then the hub picks.

Kane CLI checks your choice against the device list before it asks for a session, so you find a typo before you wait for a device. If the list cannot be read, Kane CLI warns and runs anyway. The hub has the final say.

The App Under Test

Every real-device run needs an app. You can provide it in two ways:

A local build. Android takes .apk or .aab. iOS takes .ipa. Kane CLI uploads the build to your account the first time and prints its APP… id. A per-machine cache skips a build the account already has.

An uploaded app id: APP followed by digits. List your real-device uploads with:

kane-cli apps list --target android
kane-cli apps list --target ios

A simulator .zip does not run on a real iPhone. Build an .ipa instead. Every session starts with a fresh install of the app.

In the TUI

In the interactive terminal UI (TUI), you can pick a device and app from menus and watch the test on the device screen.

Run /mobile and choose Android or iOS (real device). /mobile works on any machine.
Pick a device. “Any available Android device” is the top row. Then pick the app: a local build, one of your uploads, or an app id.
A live view opens while the test runs. The live view is a picture of the device screen in its own Chrome window. It is view-only and shows a “View only — the test is driving this device” badge. Its address carries your account key, so Kane CLI never prints it.
One device session lasts for the whole TUI session. /new and exit close it. If the hub ends an idle session, your next objective opens another one.
To change the device or app mid-session, run /new first.

To turn the live view off for one run, pass --no-stream. To turn it off for every run:

kane-cli config set-device-stream off

The live view needs Google Chrome (or KANE_CLI_CHROME_PATH). Without it, Kane CLI prints note: no live view of the device — <reason> and the test runs anyway. Agent and non-interactive runs never open a live view.

Permissions and Alerts

By default, Kane CLI accepts app permission prompts and system alerts so they do not block your test. You can turn this off per platform:

Setting	Applies to	Default
`kane-cli config set-auto-grant-permissions on\|off`	Android (`android`, and `emulator`)	on
`kane-cli config set-auto-accept-alerts on\|off`	iOS (`ios`, and `simulator`)	on

Real devices and virtual devices keep separate values. Each command changes the value for your saved target. To change the real-device value, run kane-cli config set-target android (or ios) first. Kane CLI also saves the setting on the mobile test it creates in Test Manager, so a cloud re-run behaves the same way.

Saved Tests (`_test.md`)

Save a real-device test as a file so you can run it again or add it to a suite. Set the target and app in the frontmatter:

---
target: android            # android | ios
app: ./builds/app-release.apk
device_name: Pixel.*       # optional: a name or a pattern
os_version: "15"           # optional
---

app: is required, or pass --app.
no_reset: is refused, because a real-device session always starts with a fresh install.
kane-cli testmd run <path> runs the file on the target its target: names. --device-name, --os-version, --app, and --no-stream work as on run.

For the full file format, see Test.md.

Suites (`testrun`)

You can run a suite of real-device tests from your machine or on the cloud grid. A member is one test file in the suite. Locally, real-device members run from any machine. Each member opens its own device session, so --parallel works up to what your plan allows. Extra sessions queue, as described in Plan Requirements.

kane-cli testrun run --match '^tests/devices/' --parallel 2 < /dev/null

On the cloud grid with --remote, a real-device suite runs as a HyperExecute job on Linux runners. Kane CLI resolves each member’s device on your machine (the flag, then the file, then the hub picks) and prints it before dispatch:

Devices:
  tests/devices/login_test.md  Real device · any Android device · Android 15  (test file)

Android and iOS real-device members can share one job.
A job cannot mix real-device members with web, emulator, or simulator members.
testrun takes the app from each file’s app:. There is no --app on testrun.
--device-slug is refused for real devices.

See Remote Runs on the Cloud Grid and Batch Runs.

Limitations

No adaptive heal. A replay step that fails is not repaired, and the test fails. Kane CLI prints note: adaptive heal is off on real devices… on a replay.
No no_reset. Every session installs the app fresh.
Idle sessions end. The hub ends a session left idle too long. In the TUI, your next objective opens another one.
The live view needs Chrome and never opens for agent runs.

Troubleshooting

Find the message Kane CLI printed in the left column, then apply the fix.

You see	Fix
`failed to open the mobile hub session: <reason>`	Check that your account has KaneAI Max or KaneAI credits + Real Device Plus Automation Cloud, and that you are not over your plan’s devices. The reason comes from the hub.
`a real-device run needs your TestMu AI username and access key, and none were found.`	Run `kane-cli login`, or pass `--username` and `--access-key`.
`"X" is not available as a real Android device.`	Pick a name from `kane-cli devices list --target android --remote`.
`no real Android device runs Android 9.`	Pick a version the list shows, or drop `--os-version`.
`no real Android devices are listed right now — try again later.`	The hub has no free devices for that platform. Try again later.
`… cannot run on a real iOS device — use an .ipa file, or an iOS app ID …`	Use the build type the platform takes. See the table at the top of this page.
`no app for this real-device test — add app: <path-to-build \| AppId> to the file, or pass --app.`	Add `app:` to the file, or pass `--app`.
`… has to be uploaded before it can run on a real device, but your account's org id was not found.`	Run `kane-cli login` again, or use an `APP…` id from `kane-cli apps list`.
`error: real devices are not listed from this machine — add --remote`	Add `--remote` to `devices list`.

Next Steps

Mobile Testing to compare all mobile targets
Remote Runs on the Cloud Grid to run suites on HyperExecute
Evidence for what a real-device run records

​Plan Requirements

​Quick Start

​Choosing a Device

​The App Under Test

​In the TUI

​Permissions and Alerts

​Saved Tests (_test.md)

​Suites (testrun)

​Limitations

​Troubleshooting

​Next Steps

Plan Requirements

Quick Start

Choosing a Device

The App Under Test

In the TUI

Permissions and Alerts

Saved Tests (`_test.md`)

Suites (`testrun`)

Limitations

Troubleshooting

Next Steps