English · 简体中文
Build iOS apps from the command line on Windows, Linux and macOS
kxbuild is a build system for Xcode projects, in the role xcodebuild plays on a Mac.
It reads .xcodeproj / .xcworkspace / Package.swift as they are, accepts xcodebuild's own command-line syntax,
and produces signed .ipa files ready for the App Store. Runs on Windows, Linux and macOS. No Xcode required.
| 🖥️ Cross-platform | Builds natively on Windows, Linux and macOS |
| 📂 No project changes | Build settings, schemes, target dependencies and compiler flags are read by Xcode's rules |
| 🔧 xcodebuild compatible | Ships drop-in xcodebuild, xcrun and codesign, so framework build scripts run unchanged |
| 🔏 Signing built in | Drop your .p12 and .mobileprovision into a keychain folder and every build signs automatically |
| 📦 One command to .ipa | A Release build writes an App Store-ready .ipa, including SwiftSupport |
| 📱 Install on device | --install builds, signs and installs on a USB-connected iPhone in one step |
| 🤖 Script and CI friendly | --json prints one JSON event per line, and exit codes follow the usual 0 / non-zero rule |
| ✍️ Any editor | Use it from a terminal, a CI pipeline, or whichever editor you like. Nothing to configure in the project |
| OS | Version | Build | Sign | Install on iPhone |
|---|---|---|---|---|
| Windows 10 / 11 (WSL recommended) | ✅ | ✅ | ✅ | |
| Major distros / WSL | ✅ | ✅ | ✅ | |
| macOS | ✅ | ✅ | ✅ |
Each guide shows how to prepare and build that kind of project with the kxbuild command line.
| Project type | Guide |
|---|---|
| doc/en/swift.md | |
| doc/en/objective-c.md | |
| doc/en/cocoapods.md | |
| doc/en/flutter.md | |
| doc/en/react-native.md | |
| doc/en/expo.md | |
| 🟢 uni-app (HBuilderX) | doc/en/uni-app.md |
| doc/en/kotlin-multiplatform.md | |
| doc/en/unity.md | |
| doc/en/godot.md | |
| doc/en/cocos2d-x.md | |
| 🔌 Dev server over USB (Metro, livereload, any framework) | doc/en/dev-server.md |
| doc/en/cordova.md |
C and C++ sources inside any of these projects build as part of the project.
The KXBuild extension brings the same builds into VS Code: press F5 to build, sign, install on the iPhone and stop at your breakpoints. It adds code completion before the first build, visual editors for Info.plist, String Catalogs, asset catalogs and project settings, and React Native Fast Refresh. It works on Windows, Linux and macOS.
Install it in either of these ways:
- VS Code: paste
vscode:extension/kxbuild.kxbuildinto your browser's address bar to open the extension page in VS Code, or search for KXBuild in the Extensions view (Ctrl+Shift+X) and click Install. - Cursor, Windsurf, VSCodium and other editors that use Open VSX: install it from open-vsx.org/extension/kxbuild/kxbuild, or search for KXBuild in the editor's Extensions view.
Features, screenshots, command-line usage and AI prompts are in doc/en/vscode.md.
Claude Code, GitHub Copilot, Cursor, Codex and Windsurf can build the app, run it on your iPhone, read its logs, take screenshots, tap through the screens, debug with breakpoints and publish to App Store Connect: kxbuild mcp and kxdevice mcp are MCP servers, every command has --json, new projects carry an AGENTS.md, and kxstore skill --install user teaches the agent the App Store commands (upload, metadata, screenshots, review, TestFlight). Setup for each agent is in doc/en/ai-agents.md.
kxbuild is currently in private beta. Sign up to join the waitlist, and we'll email you when your access is ready. ⭐ Star or 👀 Watch this repo (top right) to get notified of updates.
Run the command for your OS and follow the prompts.
Linux / macOS / WSL
curl -fsSL https://www.kxbuild.net/install.sh | bashWindows (PowerShell)
irm https://www.kxbuild.net/install.ps1 | iex- The default install directory is
~/kxbuild(%USERPROFILE%\kxbuildon Windows). The installer asks first, so you can enter another absolute path. It setsKXBUILD_HOMEand adds itsbinfolder toPATH. - On Windows, installing inside WSL (Ubuntu) is recommended. A native Windows install also sets up the Visual Studio C++ Build Tools (10–20 GB), and Windows' 260-character path limit can break builds of deeply nested projects.
Then open a new terminal and check the environment. You're ready when every check passes.
kxbuild doctorTo update later, run kxbuild doctor again. It installs the newest kxbuild, then updates the SDKs and components.
1. Create a project (skip this for an existing project)
kxbuild project create -t app_swiftui -n MyApp -b com.example.myapp -o D:\projectskxbuild project templates lists all templates: SwiftUI, UIKit, Objective-C, CocoaPods, Flutter, React Native, Expo, frameworks and static libraries.
2. Set up signing
Put your .p12 certificate and .mobileprovision profile in a keychain folder in the project root, with a password.properties file. See Signing.
3. Build and install on your iPhone
Connect the iPhone over USB, tap Trust This Computer, and turn on Developer Mode (Settings → Privacy & Security → Developer Mode). Then:
kxbuild build D:\projects\MyApp\MyApp.xcodeproj --install4. Build an App Store .ipa
Put your Apple Distribution certificate (.p12) and the app's App Store provisioning profile in the project's keychain folder, then:
kxbuild build D:\projects\MyApp\MyApp.xcodeproj -c Release --export app-storeThe package is written to build\MyApp.ipa in the project folder. Upload it to App Store Connect with kxstore (kxstore build upload build\MyApp.ipa); TestFlight and App Review work as usual.
| Command | What it does |
|---|---|
kxbuild doctor [project] |
Updates kxbuild and its components, then checks and fixes the build environment. With a project path, also prepares that project (Flutter, React Native, Expo, Kotlin Multiplatform, Cocos Creator and cocos2d-x need this before their first build) |
kxbuild build <project> |
Compiles, links, signs and packages an .xcodeproj, .xcworkspace or Package.swift folder, optionally installing it on a device |
kxbuild run <project> |
Builds the app, installs it on the connected iPhone and launches it; optionally collects its logs, a screenshot and its view hierarchy |
kxbuild test <project> |
Builds a scheme's tests and runs them on a connected iOS 17+ device (XCTest and Swift Testing) |
kxbuild project resolve <project> |
Resolves Swift package dependencies |
kxbuild project … |
Inspects, creates, edits and converts Xcode projects: info, templates, create, settings, add-setting, add-package, add-target, add-folder, add-resource, localization, spm2app, to-spm |
kxbuild license … |
Shows the license state, starts a trial or activates this computer: status, trial, activate, refresh, deactivate |
kxbuild mcp |
MCP server for AI coding agents, see doc/en/ai-agents.md |
kxbuild version |
Prints version information |
kxstore … |
App Store Connect from the command line: login with an API key, cert / profile / device / bundle, build upload, metadata, screenshot, review submit, testflight, iap, pricing, or everything as one kxstore release; see doc/en/ai-agents.md |
Every command accepts --help for its full list of options.
kxbuild build <project.xcodeproj|project.xcworkspace|package dir> [flags]
| Option | Description |
|---|---|
-s, --scheme NAME / -t, --target NAME |
Scheme or target to build. Without either, the default scheme is built |
-c, --config NAME |
Build configuration. Defaults to the scheme's, else Debug |
--sdk NAME, --arch ARCH, --toolchain NAME |
SDK (iphoneos, iphonesimulator, macosx), architecture and toolchain |
-D, --setting KEY=VALUE |
Overrides a build setting. Repeatable; same precedence as xcodebuild KEY=VALUE |
--xcconfig PATH |
Applies an .xcconfig file, like xcodebuild -xcconfig |
-o, --ipa PATH / --no-ipa |
Where to write the .ipa, or skip packaging |
--export app-store |
Signs with an Apple Distribution certificate and an App Store profile from keychain, for an .ipa to upload to App Store Connect (also ad-hoc, enterprise, development) |
-i, --install |
Installs the signed app on the connected iPhone after a successful build |
--derivedDataDir DIR, --clean |
Build output root (default ~/DerivedData), and empty it before building |
--ignoreDependence |
Builds only the named targets, skipping their dependencies |
-j, --jobs N, --explain, --timing, -v, --verbose, --no-cache |
Parallelism and diagnostics |
--emit-commands-only |
Writes only compile_commands.json for editor code completion; nothing is compiled |
--skip-package-updates, --only-use-versions-from-resolved-file, --disable-package-repository-cache, --package-cache-path DIR |
Swift package resolution, matching the xcodebuild options of the same meaning |
| Product | Location |
|---|---|
| .app and intermediates | ~/DerivedData/<Name>-<hash>/ (change with --derivedDataDir) |
| .ipa | <project dir>/build/<App>.ipa for Release, <App>-<Config>.ipa for other configurations |
| Goal | Command |
|---|---|
| Install a Debug build on the iPhone | kxbuild build .\MyApp.xcodeproj --install |
| Release .ipa for the App Store | kxbuild build .\MyApp.xcodeproj -c Release --export app-store |
| Sign with a Distribution certificate chosen on the command line | kxbuild build .\MyApp.xcodeproj -c Release -D CODE_SIGN_IDENTITY="Apple Distribution" |
| Set version and build number for one build | kxbuild build .\MyApp.xcodeproj -D MARKETING_VERSION=1.2.0 -D CURRENT_PROJECT_VERSION=45 |
| Check that it compiles, without signing | kxbuild build .\MyApp.xcodeproj -D CODE_SIGNING_ALLOWED=NO |
| Simulator SDK compile check | kxbuild build .\MyApp.xcodeproj --sdk iphonesimulator -D CODE_SIGNING_ALLOWED=NO |
| Build one library target only | kxbuild build .\MyApp.xcodeproj -t MyKit --ignoreDependence |
| Reset Swift package caches | kxbuild project resolve .\MyApp.xcworkspace --force |
| List schemes, targets and bundle IDs | kxbuild project info .\MyApp.xcodeproj |
kxbuild run takes the same build options as kxbuild build (-s, -c, -D, --clean, -j, --explain, --no-cache and the Swift package options), plus:
| Option | Description |
|---|---|
--udid UDID, --connection-type USB|Network |
The device to run on and how to reach it. Defaults to the first connected device, over USB when both work |
--no-build / --no-install |
Installs and launches the last build / launches the app already on the device |
--kill-existing, --args "…", --launch-timeout D |
Ends a running instance first, passes launch arguments, sets how long to wait for the app to start (default 60s) |
--wait-logs D, --log-file FILE |
Collects the app's logs (os_log, Logger, NSLog) for this long after the launch, optionally into a JSON-lines file |
--screenshot FILE, --view-hierarchy FILE |
Saves a PNG screenshot and the view hierarchy as JSON after the launch |
kxbuild test runs on a connected device with iOS 17 or later and takes the same build options as kxbuild build, plus --udid and --connection-type as above and:
| Option | Description |
|---|---|
--test-plan NAME / --test-target NAME |
Uses this test plan of the scheme / runs these test targets instead of the scheme's test action |
--only-testing T[/C[/m]], --skip-testing T[/C[/m]] |
Runs only / skips these tests, repeatable, like xcodebuild |
--build-only / --xctestrun FILE |
Builds and writes the .xctestrun without running it / runs an .xctestrun without building |
All commands exit with 0 on success and non-zero on failure. A typical CI command for a release .ipa:
kxbuild build MyApp.xcworkspace -s MyApp -c Release --export app-store --clean --derivedDataDir ./out --skip-package-updates --ipa ./out/MyApp.ipa --jsonWith --json, every line on stdout is one JSON event (log, progress, diagnostic, and a final result):
{"type":"progress","phase":"CompileSwiftSources","current":12,"total":42,"target":"MyApp"}
{"type":"result","command":"build","schemaVersion":1,"data":{"success":true,"duration":"1m12s","output":"…","products":["…"],"ipa":["out/MyApp.ipa"],"schemaVersion":1}}Leave --json off when troubleshooting, because error details appear only in the normal output. Set KXBUILD_NO_UPDATE_CHECK to turn off update prompts in CI.
The bin folder of the install directory contains xcodebuild, xcrun and codesign, named the same as on macOS. When React Native, Expo, Flutter or Cordova scripts — or your own scripts — call them, they run kxbuild's versions, so they work unchanged. On macOS the system's own commands stay first on PATH, so use kxbuild build there.
xcodebuild -workspace ios/MyApp.xcworkspace -scheme MyApp -configuration Debug -sdk iphoneos
xcodebuild -list -json
xcodebuild -showBuildSettings -project MyApp.xcodeproj
xcrun --sdk iphoneos --show-sdk-path| Supported | |
|---|---|
| Actions | build (default), clean, install, installhdrs, installapi, installsrc, archive (minimal, unsigned .xcarchive), build-for-testing, test, test-without-building (tests run on a connected iOS 17+ device) |
| Selection | -project, -workspace, -scheme, -target, -alltargets, -configuration, -sdk, -arch, -toolchain, -destination |
| Settings | -xcconfig PATH, KEY=VALUE |
| Output | -derivedDataPath, -archivePath, -clonedSourcePackagesDirPath, -resolvePackageDependencies |
| Queries | -list, -showBuildSettings, -showsdks, -showdestinations, -version, with -json |
| Control | -jobs, -quiet, -verbose, -hideShellScriptEnvironment |
-exportArchive signs the archive for the method in ExportOptions.plist (app-store-connect, release-testing, enterprise, debugging, or the older names) with the certificate and profile in keychain, and writes the .ipa to -exportPath.
Not supported: analyze, docbuild, -create-xcframework, localization import/export and platform downloads. Other xcodebuild options are accepted and ignored. Exit codes follow xcodebuild: 64 usage error, 65 build failure or unsupported action, 66 input file not found. You can also get the App Store .ipa in one step with kxbuild build -c Release --export app-store.
xcrun finds and runs SDK and toolchain tools (--show-sdk-path, --show-sdk-version, -f TOOL, xcrun clang …). codesign signs and verifies with the same options, output and exit codes as on macOS.
You need a .p12 certificate (with its private key) and a .mobileprovision profile from your Apple Developer account: Apple Development + a development profile containing your iPhone's UDID for testing, Apple Distribution + an App Store profile for release.
Put them in a keychain folder. The one in the project root applies to that project; the one under KXBUILD_HOME is shared by all projects. Both are merged, and on macOS the system keychain is used too.
keychain/
├─ development.p12
├─ distribution.p12
├─ MyApp_Dev.mobileprovision
├─ MyApp_AppStore.mobileprovision
└─ password.properties
password.properties has one file=password line per certificate (file name exactly as on disk, no quotes):
development.p12=123456
distribution.p12=123456As in Xcode, the project's signing settings decide which certificate and profile are used: CODE_SIGN_IDENTITY, DEVELOPMENT_TEAM, and either automatic matching by bundle ID and team or PROVISIONING_PROFILE_SPECIFIER. Override them for one build with -D. Without a certificate the project still builds, but the product is unsigned and won't install on an iPhone.
kxbuild installs kxdevice alongside it for talking to iPhones over USB.
kxdevice doctor # check and repair device support (usbmuxd)
kxdevice device list # first column is the UDID
kxbuild build .\MyApp.xcodeproj --install
kxdevice install .\build\MyApp.ipa| OS | kxdevice doctor |
|---|---|
| Windows | Starts the Apple Mobile Device Service (one admin approval); if it is missing, install and open Apple Devices from the Microsoft Store first |
| WSL | Uses the Windows-side service through a relay. Plug the iPhone into Windows; don't pass it through with usbipd |
| Linux | Installs and starts usbmuxd and its udev rules (needs sudo) |
| macOS | Nothing to install |
With several devices connected, --install uses the first one; pass --udid to kxdevice to choose.
kxbuild: command not found after installing
Open a new terminal so the updated PATH takes effect. If it still fails, check that the bin folder of the install directory is on PATH.
The build can't find headers or modules from Pods
You built the .xcodeproj. Run pod install, then build the generated .xcworkspace.
Debug build fails to link with undefined symbol: …vpfi
A known issue in the open-source Swift compiler when compiling file by file. Set KXBUILD_SWIFT_WHOLE_MODULE=all (or pass -D KXBUILD_SWIFT_WHOLE_MODULE=all for one build) to build every Swift target as a whole module.
No signing certificate matching '…' found
The keychain folder has no certificate of the type or team the project asks for. Add the matching .p12, or use -D CODE_SIGN_IDENTITY=… -D DEVELOPMENT_TEAM=….
Something else fails
Run kxbuild doctor -v (with the project path, if it's project-specific). It fixes most environment problems; its output is the most useful thing to include in a bug report.
These sample apps build and run on iPhone with kxbuild from Windows, Linux or macOS. The templates behind kxbuild project create live in their own repository, open to suggestions:
| Repository | What's inside |
|---|---|
| SwiftUI Gallery | 15 SwiftUI demos: controls, lists, animation, gestures, Swift Charts, MapKit, SwiftData |
| UIKit Gallery (Objective-C) | 14 UIKit demos in Objective-C, every view built in code |
| Flutter Gallery | Material and Cupertino widgets plus four complete sample apps |
| React Native Gallery | 16 demos of React Native's built-in components and APIs |
| Expo Gallery | 22 Expo SDK modules: camera, sensors, location, SQLite and more |
| Godot Gallery | 10 Godot 4 demos exported to iOS |
| Unity Gallery | 10 Unity 6 demos exported to iOS |
| KXBuild App Templates | Project and target templates for kxbuild project create and add-target |
🐛 Found a problem or have a suggestion? Open an Issue
Please include the output of kxbuild version and kxbuild doctor -v, plus the full log of the failing command.
⭐ Find it useful? Star this repo, or Watch it to hear about new releases.
