CLI reference

The executable is invoked as xcross <command> [subcommand] [options]. flutter, sdk and ide are parent commands that only dispatch to their subcommands, so xcross flutter on its own prints usage. Add --help to any level (xcross flutter run --help).

Global options#

Flag	Abbr	Default	Description
--verbose	-v	off	Verbose output (show every command and tool line).

-v is a top-level flag on the runner, so it works in front of any command (xcross -v tunnel). xcross flutter run additionally accepts its own -v after the subcommand, which does the same thing for that run.

Command summary#

Command	Description
xcross setup	Install or verify host requirements
xcross sdk	Manage the xcross Darwin Swift SDK.
xcross sdk install <Xcode.xip>	Extract a host-neutral Darwin Swift SDK from an Xcode.xip.
xcross auth	Save App Store Connect API key credentials or sign in with Apple ID for the native (no-Swift) signing pipeline.
xcross tunnel	Mount the Developer Disk Image and start the iOS 17+ RSD tunnel.
xcross flutter	Build and run Flutter iOS apps without Xcode.
xcross flutter run	Build, install, and run a Flutter iOS app on a device.
xcross flutter build	Build a Flutter iOS .app without Xcode.
xcross flutter dap	Internal. Debug Adapter Protocol server for IDE Run & Debug buttons.
xcross ide	Set up editor integration for Run & Debug on an iOS device.
xcross ide vscode	Set up .vscode/ so F5, Restart and Hot Reload run on an iOS device.
xcross ide idea	Set up a JetBrains DAP run config so Debug runs on an iOS device.
xcross completion	Print a shell completion script for xcross.

Commands marked Internal are hidden from xcross --help and are spawned by other tools on your behalf. They are documented here for completeness only - do not call them directly or script against them, since their input and output contracts can change without notice.

setup#

Install or verify host requirements. On Linux it runs apt-get install for the toolchain packages (clang, lld, llvm, python3, python3-pip, python3-venv, usbmuxd, usbutils, libimobiledevice-utils and the Swift build dependencies), links a versioned ld64.lld-<version> to a stable name if needed, then ensures pymobiledevice3 is installed. On Windows it only verifies that flutter, swift, clang, clang++, llvm-ar and ld64.lld are on PATH, then installs pymobiledevice3.

xcross setup

No options. Linux setup requires an apt-based distribution; without apt-get it fails with the package list for manual installation. After the install it checks that swift, clang, clang++, llvm-ar and ld64.lld are on PATH and fails if any are missing.

sdk install#

Extract a host-neutral Darwin Swift SDK from an Xcode.xip. Run once per Xcode archive.

xcross sdk install <path-to-Xcode.xip>

The path is a positional argument, not a flag; there are no options. The command deletes any previous SDK at the install directory, extracts the required iOS subset (iPhoneOS SDKs, frameworks, private frameworks, Swift and clang toolchain resources), replaces Xcode’s clang builtin headers with ones matching your host Swift, and writes the Swift artifact-bundle metadata (swift-sdk.json, toolset.json, info.json).

xcross sdk install C:\Downloads\Xcode.xip

auth#

Save App Store Connect API key credentials or sign in with Apple ID for the native (no-Swift) signing pipeline. Passing any of --issuer-id, --key-id or --private-key selects API key mode; otherwise xcross performs an Apple ID login and prompts for anything not supplied.

Flag	Value	Description
--issuer-id	id	App Store Connect API “Issuer ID” (one per team).
--key-id	id	The API key’s “Key ID”, shown next to it in App Store Connect.
--private-key	path	Path to the downloaded AuthKey_<keyId>.p8 file.
--apple-id	email	Use Apple ID/password login. If omitted, xcross prompts.
--password	password	Apple ID password (optional; prompted if omitted).
--adi-library-dir	path	Directory containing libCoreADI.so and libstoreservicescore.so for Apple ID login. Defaults to the xcross config adi-libs directory. On x86_64, missing libs are fetched from the Apple Music APK.

xcross auth --apple-id you@example.com
xcross auth --issuer-id <uuid> --key-id <id> --private-key /path/to/AuthKey.p8

The API key flags and --apple-id are mutually exclusive, and --adi-library-dir only applies to Apple ID login. Saving an API key clears any stored Apple ID session so the active mode is never ambiguous. Apple ID login prompts for a 2FA code, then asks which Developer Services team to use when more than one active team exists.

tunnel#

Mount the Developer Disk Image and start the iOS 17+ RSD tunnel (mounter auto-mount + lockdown start-tunnel + tunneld). Requires sudo on POSIX or an Administrator terminal on Windows.

xcross tunnel

No options. The long-lived tunnel processes stay running after the command exits; run it once per device reconnect.

flutter run#

Build, install, and run a Flutter iOS app on a device. Always a debug (JIT) build, always launched with hot reload when the required frontend_server artifacts are available.

Flag	Abbr	Default	Description
--target	-t	lib/main.dart	The main entry-point file of the application.
--flavor			Build a custom app flavor (sets FLUTTER_APP_FLAVOR).
--dart-define	-D		Pass a KEY=VALUE define to the Dart compiler. Repeatable.
--dart-define-from-file			Load dart-defines from a .json or .env file. Repeatable.
--[no-]pub		on	Run “flutter pub get” before building.
--device-id	-d		Target device id or name (flutter-style).
--udid	-u		Target device UDID.
--usb		off	Search USB devices only.
--wifi		off	Search Wi-Fi devices only.
--device-connection		both	Discovery: attached (USB), wireless (Wi-Fi), or both. Allowed: attached, wireless, both.
--route			Initial route the app navigates to on launch.
--dart-entrypoint-args	-a		Pass arguments to the app main() (repeatable).
--verbose	-v	off	Verbose output.

--udid wins over --device-id when both are set, and --usb / --wifi take precedence over --device-connection. The run aborts before installing if the device reports an OS older than iOS 17.

xcross flutter run
xcross flutter run -u 00008030-000123456789ABCD -D API_URL=https://staging.example.com

flutter build#

Build a Flutter iOS .app without Xcode. The output is unsigned; signing happens when xcross flutter run installs the bundle.

Flag	Abbr	Default	Description
--target	-t	lib/main.dart	The main entry-point file of the application.
--flavor			Build a custom app flavor (sets FLUTTER_APP_FLAVOR).
--dart-define	-D		Pass a KEY=VALUE define to the Dart compiler. Repeatable.
--dart-define-from-file			Load dart-defines from a .json or .env file. Repeatable.
--[no-]pub		on	Run “flutter pub get” before building.
--build-name			Version name (CFBundleShortVersionString).
--build-number			Version code (CFBundleVersion).
--ipa	-i	off	Output a .ipa file instead of a .app.

xcross flutter build --build-name 1.4.0 --build-number 42
xcross flutter build -i -t lib/main_staging.dart --flavor staging

flutter dap (internal)#

Debug Adapter Protocol server for IDE Run & Debug buttons. It takes no options and speaks DAP over stdio, so nothing else may write to stdout - xcross suppresses its own banner for this command. Running it in a normal terminal just leaves you with a process waiting for DAP frames.

VS Code reaches it through the generated .vscode/xcross_dap.dart shim; JetBrains IDEs reach it through the LSP4IJ run configuration. Launch configurations must set "xcross": true to be handled here.

ide vscode#

Set up .vscode/ so F5, Restart and Hot Reload run on an iOS device.

xcross ide vscode

No options. It creates .vscode/, rewrites the xcross_dap.dart shim with the path of the currently installed xcross, and upserts launch.json and settings.json in place - existing keys are preserved, and a second run that changes nothing reports the files as unchanged. Malformed JSON/JSONC is reported instead of overwritten.

ide idea#

Set up a JetBrains DAP run config so Debug runs on an iOS device.

xcross ide idea

No options. It writes .run/xcross_ios_device.run.xml, a shared LSP4IJ DAPConfiguration that starts xcross flutter dap over stdio with a launch configuration marked "xcross": true. An existing file is never overwritten; the command prints the XML for you to merge yourself.

completion#

Print a shell completion script for xcross. Append the output to your shell config file (e.g. ~/.bashrc or ~/.zshrc) to enable tab-completion.

xcross completion >> ~/.bashrc
xcross completion >> ~/.zshrc

No options. The generated script covers bash and zsh (both compdef and compctl). Restart your shell or source the file afterwards. Like flutter dap, this command owns stdout, so the banner is suppressed - but unlike flutter dap it is a normal, visible command meant to be run by you.

See also#

• Quick start
• IDE integration
• Troubleshooting