kxdevice command reference

Every kxdevice subcommand and option, grouped into devices and pairing, installing and apps, launching and screenshots, debugging and symbols, logs and crashes, files and sandboxes, packet capture and location, backup and diagnostics, and the web UI.

Usage: kxdevice <command> [subcommand] [options]. kxdevice talks to the iPhone. It lists devices, installs and launches apps, forwards the debug port, and pulls logs and files. For projects and builds, see kxbuild. Every command accepts --help.

Global option	Description
--udid UDID	Device to use. Defaults to the first attached device.
--connection-type USB\|Network	Connection to use. Defaults to USB when available.
--json	Prints machine-readable JSON.
-v, --verbose	Prints verbose logs.
--no-setup	Doesn't run setup automatically when the device service is missing.

> kxdevice device list

Commands

Command	Description
doctor	Checks and repairs everything needed to talk to iOS devices.
device list / info / listen	Lists devices, prints device details, and streams attach and detach events.
pair, devmode, ddi	Manages pair records, Developer Mode and the Developer Disk Image.
install, apps	Installs an .ipa or .app. Lists, looks up and uninstalls apps.
apps launch / kill / ps, screenshot	Launches and kills apps, lists processes, takes screenshots.
debug, forward, symbols	Forwards the debug port to LLDB, forwards other ports, manages device symbols.
syslog, ostrace, crash	Streams the system log and os_log, fetches crash reports.
file, sandbox	Works with files on the media partition, browses app sandboxes.
pcap, location	Captures device network traffic, simulates GPS location.
provisioning, profiles	Manages provisioning profiles and configuration profiles on the device.
backup / restore, diagnostics	Backs up and restores, reads the battery, reboots.
web	Starts a local web UI.

For the profiling commands, such as instruments sysmon, netmon, energy, allocations, fluidity, stackshot and har, see Performance profiling.

Devices and pairing

doctor

kxdevice doctor

Checks and repairs everything needed to talk to iOS devices. Other commands run it automatically when the device service is missing, so you rarely need to run it yourself.

OS	What it does
Windows	Starts the Apple Mobile Device Service. If it isn't installed, asks you to install and open Apple Devices from the Microsoft Store first. Needs one admin approval.
WSL	Makes sure the Apple service is running on the Windows side, then installs and starts a relay service on Windows that WSL uses to reach the iPhone. Needs no root inside WSL.
Linux	Installs usbmuxd and the udev rules and starts the service. Needs sudo.
macOS	Restarts the built-in usbmuxd.

device list / info / listen

kxdevice device list · kxdevice device info · kxdevice device listen

list shows attached devices with their UDID, connection type, model, iOS version and name. The UDID in the first column is the one your development provisioning profile must include. info prints detailed properties of the selected device. listen streams attach and detach events until you press Ctrl-C. kxdevice info prints a short summary of the common device details.

> kxdevice --udid 00008030-000A1B2C3D4E5F6G device info

pair list / delete / export-p12

kxdevice pair list · kxdevice pair delete <udid> · kxdevice pair export-p12 [-o FILE] [--password PWD]

Manages the pair records stored on this computer. A record is saved once you tap Trust This Computer on the iPhone. delete removes it, so the trust prompt appears again on the next connection. export-p12 exports the pairing certificate and private key as PKCS#12, for example so Wireshark can decrypt traffic.

devmode reveal / enable / accept

kxdevice devmode reveal · kxdevice devmode enable · kxdevice devmode accept

Debugging on iOS 16 and later requires Developer Mode. reveal shows the Developer Mode switch under Settings > Privacy & Security. enable turns it on and restarts the iPhone, which then asks you to confirm. accept confirms that prompt for you.

ddi status / list / mount / unmount / auto-mount

kxdevice ddi auto-mount · kxdevice ddi status · kxdevice ddi list · kxdevice ddi mount DMG_PATH · kxdevice ddi unmount

Debugging, screenshots and launching apps all need the Developer Disk Image mounted first. auto-mount picks the image for the device's iOS version and mounts it. On iOS 17 and later, it downloads the image and personalizes it for the device. debug runs it automatically. status prints the Developer Mode status. list shows mounted images. mount mounts a given .dmg, which needs its .signature file next to it. unmount unmounts the image.

Install and apps

install

kxdevice install <IPA or .app dir>

Installs an .ipa or an unzipped .app directory. The app must be signed with a provisioning profile that includes this iPhone. See Certificates and signing. kxbuild build --install calls it after the build.

> kxdevice install .\build\MyApp.ipa

apps / apps lookup / apps uninstall

kxdevice apps [--type User|System] [--file-sharing] · kxdevice apps lookup BUNDLE_ID · kxdevice apps uninstall BUNDLE_ID

Lists installed apps and their bundle IDs. By default, --type lists only user-installed apps. --file-sharing lists only apps with file sharing turned on. lookup prints the details of one app, and uninstall removes it.

> kxdevice apps uninstall com.example.myapp

Launch, screenshots and processes

apps launch / kill / ps

kxdevice apps launch BUNDLE_ID · kxdevice apps kill BUNDLE_ID|PID · kxdevice apps ps [--apps]

launch starts an installed app and prints its PID. kill stops an app by bundle ID, or any process by PID. ps lists the processes running on the device, and --apps limits it to apps.

> kxdevice apps launch com.example.myapp

instruments sysmon

kxdevice instruments sysmon [-i INTERVAL] [-n COUNT]

Streams CPU usage. For the other sampling commands, see Performance profiling.

screenshot

kxdevice screenshot [-o FILE]

Takes a PNG screenshot. Without -o, the file is named screenshot_YYYYMMDD_HHMMSS.png.

Debugging and symbols

debug

kxdevice debug [-b <.app|.ipa>] [-B <bundleID>] [-p PORT] [options]

Forwards the on-device debugserver port to a local TCP port so LLDB can connect. For VS Code, see Run and debug. With -b, installs the app first and then launches it. With only -B, launches the app already on the device. With neither, only forwards the port, which you can combine with --attach-pid to attach to a running process. Once running, it prints the PID, the port and the symbol directory. Press Ctrl-C to stop forwarding.

Option	Description
-b, --bundle PATH	.app directory or .ipa to install.
-B, --bundle-id ID	Bundle ID of the app. Derived from the Info.plist when -b is given.
-p, --port N	Local port to listen on. 0 or omitted picks a free port.
-a, --args "…"	App launch arguments, space separated.
-e, --env "K1=V1 K2=V2"	Extra environment variables.
-w, --wait	Starts the app suspended at its entry point until the debugger attaches. Required for Flutter.
-H, --hide	Launches the app in the background.
-k, --kill	Kills the app when the debug session ends.
--attach-pid N	Attaches to a running process. Skips install and launch.
-m, --no-install	Skips install even when -b is given.
--no-launch	Skips launching and only forwards the port.

> kxdevice debug -B com.example.myapp -p 5678 -k

The forwarder listens only on 127.0.0.1. Don't use localhost, which can resolve to IPv6 and fail to connect. The debug process exits when its standard input closes, so keep stdin open when you run it in the background, for example sleep 600 | kxdevice debug ….

forward

kxdevice forward LOCAL_PORT DEVICE_PORT

Forwards 127.0.0.1:LOCAL_PORT on this computer to DEVICE_PORT on the device. Press Ctrl-C to stop. The Flutter Dart VM service and custom debug services both go through it.

symbols list / download / path

kxdevice symbols list · kxdevice symbols download [-o DIR] [--no-extract] [--keep-cache] · kxdevice symbols path

Debugging an app on the iPhone needs device symbols for the system libraries. They download once per iOS version, are several GB, and take a while. download fetches the device symbols from the device and resumes if interrupted. path prints this device's symbol directory. list shows the files available on the device. The output root is -o if given, else symbol_cache in the config file, else ~/Library/Developer/Xcode/iOS DeviceSupport.

Logs and crashes

syslog

kxdevice syslog

Streams the device system log. Press Ctrl-C to stop. The output is large, so pipe it through findstr or grep.

ostrace

kxdevice ostrace [--levels …] [--pid N] [--subsystem S] [--match S] [--exclude S]

Streams os_log entries. NSLog and Logger both go through os_log, so the output is cleaner than syslog, and you can filter it.

Option	Description
--levels default,info,debug,error,fault	Shows only these levels, comma separated.
--pid N	Shows only this process. -1 shows all.
--subsystem S	Shows entries whose subsystem contains S.
--match S / --exclude S	Shows only messages that contain, or don't contain, S.

> kxdevice ostrace --subsystem com.example.myapp --levels error,fault

crash list / pull

kxdevice crash list [PATTERN] · kxdevice crash pull DIR [PATTERN]

Lists crash reports on the device, or downloads them to DIR. PATTERN is a file name wildcard and matches everything by default.

> kxdevice crash pull .\crashes MyApp*

Files and sandboxes

file

kxdevice file <ls|stat|tree|get|put|mkdir|rm|rm-rf|mv|df> …

Works with the device's media partition, the shared area that holds photos, downloads and so on. It doesn't reach app sandboxes.

Subcommand	Description
ls [PATH] / tree [PATH]	Lists a directory, or walks it recursively. Defaults to the root.
stat PATH	Shows file metadata.
get REMOTE [LOCAL]	Downloads a file. LOCAL defaults to the same name, and - writes to stdout.
put LOCAL REMOTE	Uploads a file.
mkdir / rm / rm-rf / mv	Creates a directory, deletes a file or empty directory, deletes recursively, renames.
df	Shows filesystem usage.

sandbox ls / tree / documents

kxdevice sandbox ls BUNDLE_ID [PATH] · kxdevice sandbox tree BUNDLE_ID [PATH] · kxdevice sandbox documents BUNDLE_ID

Browses files in an app's sandbox, starting at /Documents by default. documents lists the Documents/ folder shared through file sharing. Works only for apps you signed and installed yourself.

> kxdevice sandbox tree com.example.myapp /Library

Network and location

pcap

kxdevice pcap [FILE.pcap] [--pid N] [--proc NAME_PREFIX]

Captures the device's network packets into a libpcap file that Wireshark opens directly. Filter by process PID or name prefix. Press Ctrl-C to stop. For HTTP-level capture, see har in Performance profiling.

location set / reset

kxdevice location set LATITUDE LONGITUDE · kxdevice location reset

Simulates the GPS location. reset goes back to the real location.

Profiles

provisioning list / export

kxdevice provisioning list · kxdevice provisioning export DIR

Lists the .mobileprovision provisioning profiles installed on the device, or exports them all to DIR.

profiles list / install / remove / cloud-config

kxdevice profiles list · kxdevice profiles install FILE.mobileconfig · kxdevice profiles remove IDENTIFIER · kxdevice profiles cloud-config

Manages .mobileconfig configuration profiles, such as certificates, proxies and MDM settings. Lists them, installs one (you confirm on the device), or removes one by identifier. cloud-config shows the supervision state.

Backup, diagnostics and more

backup / restore

kxdevice backup <dir> [--full] · kxdevice restore <dir> [--system] [--password PWD] [--preserve-settings] [--remove-items] [--reboot=false] [--copy-backup=false]

Backs up the whole device to a directory. Backups are incremental by default, and --full forces a full backup. A restore copies the backup to the device and reboots when done, by default. Use --password for encrypted backups.

diagnostics battery / gestalt / reboot / shutdown / sleep

kxdevice diagnostics battery · kxdevice diagnostics gestalt KEY… · kxdevice diagnostics reboot | shutdown | sleep

Reads the battery, queries device properties such as ProductType and RegionInfo, and reboots, shuts down or sleeps the device.

lockdown / notify / icons / prepare / test / version

lockdown get|set|list reads and writes device settings such as language, locale and time zone. notify observe|post waits for or posts system notifications. icons prints the Home Screen layout. prepare create-cert|supervise|erase runs the Apple Configurator supervision and erase flows. erase wipes the device. test runxctest|runwda runs an XCTest bundle or WebDriverAgent on the device. version prints the version.

Web UI

kxdevice web [--addr :8780]

Starts a local web UI and REST server. You can work with devices, apps, logs, screenshots and profiling from the browser. Listens on port 8780 by default. Press Ctrl-C to stop.

> kxdevice web --addr 127.0.0.1:8780

Next steps

kxbuild command reference

Every kxbuild subcommand and option, including doctor, build, resolve, project, update and version.

Set up your device

Get your computer to recognize your iPhone. Install the driver, trust the computer and turn on Developer Mode, download device symbols before your first debug session, and choose between multiple devices.