kxbuild command reference

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

Usage: kxbuild <command> [options]. kxbuild handles projects and builds. Device operations belong to kxdevice. Every command accepts --help. The global --json option prints machine-readable JSON for scripts and the extension. Leave it off when troubleshooting, because error details appear only in the normal output.

> kxbuild version

Commands

Command	Description
doctor [project]	Checks and fixes the development environment. With a project path, also prepares that project.
build <project>	Builds and packages a project, and optionally installs it on a device.
resolve <project>	Resolves Swift package dependencies.
project …	Inspects, creates, edits and converts projects.
update	Updates kxbuild to the latest version, then runs doctor.
version	Prints version information.

doctor

kxbuild doctor [project] [-v]

Checks the development environment and fixes what it can. On Windows, it also turns on Developer Mode and long path support. With a project path, it detects the project type and prepares the project. Flutter, React Native, Expo, Kotlin Multiplatform and cocos2d-x projects need this before their first build.

Run doctor after you install or update, and whenever a build or debug session fails. It fixes most environment problems on its own. If something still fails, see Troubleshooting.

Option	Description
-v, --verbose	Shows every step and subprocess output. Use it when troubleshooting.

> kxbuild doctor

> kxbuild doctor D:\projects\my_flutter_app -v

build

kxbuild build <project.xcodeproj | project.xcworkspace | package dir> [options]

Builds and packages an Xcode project, a workspace, or a directory that contains Package.swift. Without a scheme or target, builds the default one. For projects that use CocoaPods, build the .xcworkspace. For common tasks, see Build and configure.

What to build

Option	Description
-s, --scheme NAME	Builds the scheme with this name.
-t, --target NAME	Builds the target with this name.
-c, --config NAME	Build configuration. Defaults to the scheme's run configuration, or Debug when there is no scheme.
--sdk NAME	SDK to build against: iphoneos, iphonesimulator or macosx.
--arch ARCH	Builds only this architecture, arm64 or x86_64.
--toolchain NAME	Toolchain to build with, by name or identifier.
--ignoreDependence	Builds only the named targets and skips their dependencies.

Build settings

Option	Description
-D, --setting KEY=VALUE	Overrides a build setting. Repeatable. Same precedence as xcodebuild KEY=VALUE.
--xcconfig PATH	Applies the settings in an .xcconfig file, like xcodebuild -xcconfig.

Output and packaging

Option	Description
--derivedDataDir DIR	Root directory for build output. Defaults to ~/DerivedData. Each project gets its own <name>-<hash> folder inside.
--clean	Removes the build output directory before building.
-o, --ipa PATH	Packages the built iOS app into an .ipa at PATH. Without it, the .ipa goes to <project dir>\build\<App>.ipa for Release, or <App>-<Config>.ipa for other configurations.
--no-ipa	Skips packaging the .ipa.
-i, --install	On success, installs the signed app on the connected device. Same as running kxdevice install afterwards.
--emit-commands-only	Writes only compile_commands.json for editor code completion. Doesn't compile, link or sign.

Performance and diagnostics

Option	Description
-j, --jobs N	Number of tasks to run in parallel. Defaults to the CPU count.
--explain	Prints why each task re-runs: never built, command changed, outputs modified, or input rebuilt.
--timing	Prints the time spent loading, planning and executing.
-v, --verbose	Prints every command line.
--no-cache	Ignores the cached build plan and plans from scratch.

Swift packages

build resolves dependencies automatically when needed. These four options also work with resolve.

Option	Description
--only-use-versions-from-resolved-file	Resolves packages strictly to the versions in Package.resolved. Same as xcodebuild -onlyUsePackageVersionsFromResolvedFile.
--skip-package-updates	Doesn't fetch remote package repositories when resolving. Same as -skipPackageUpdates.
--disable-package-repository-cache	Doesn't use the shared package repository cache. Same as -disablePackageRepositoryCache.
--package-cache-path DIR	Shared package cache directory. Same as -packageCachePath.

Build products

The .app and intermediate files are in ~/DerivedData/<name>-<hash>/Build/Products/<config>-iphoneos/.
An iOS app is also packaged as <project dir>\build\<App>.ipa for Release, or <App>-<Config>.ipa for other configurations. When the app embeds Swift libraries, the .ipa includes the SwiftSupport/ folder that App Store Connect requires. Next to a Release .ipa, <App>.AppStoreInfo.plist is the optional asset description for uploading with Transporter.
--emit-commands-only writes only <project root>/compile_commands.json.
With --json, the last result includes success, the product paths, the .ipa paths and the duration.

Examples

> kxbuild build .\MyApp.xcodeproj --install

> kxbuild build .\MyApp.xcworkspace -s MyApp -c Release --clean -D CODE_SIGN_IDENTITY="Apple Distribution"

> kxbuild build .\MyApp.xcodeproj --sdk iphonesimulator --arch arm64 -D CODE_SIGNING_ALLOWED=NO

> kxbuild build .\MyApp.xcodeproj --emit-commands-only

In order: a Debug build installed on the iPhone, a Release .ipa signed with a Distribution certificate chosen on the command line, a simulator build that compiles without signing, and a completion database for the editor only.

Scripts and CI

All of these commands work in a CI pipeline. They exit with 0 on success and non-zero on failure. A typical CI command for a release .ipa looks like this.

> kxbuild build MyApp.xcworkspace -s MyApp -c Release --clean --derivedDataDir .\out --skip-package-updates --ipa .\out\MyApp.ipa --json

Option	Why
--json	Prints one JSON event per line. Scripts read the result from the success and product path fields. Leave it off when troubleshooting.
--derivedDataDir DIR	Keeps build output inside the workspace, starting from a clean folder each time, so products are easy to collect.
--skip-package-updates	Keeps Swift packages at the versions in Package.resolved without fetching remotes, so builds are reproducible.
--clean	Keeps intermediate files from the previous build out.

When React Native, Expo or Flutter build scripts call xcodebuild and xcrun, they run the KXBuild commands of the same name, so the scripts work unchanged. See xcodebuild and xcrun compatibility.

resolve

kxbuild resolve <project.xcodeproj | project.xcworkspace | package dir> [options]

Resolves the project's Swift package dependencies and checks them out to <DerivedData>/<name>-<hash>/SourcePackages/. build does this automatically. Run it on its own to warm the cache or reset broken dependencies.

Option	Description
--force	Resets the package checkouts and caches before resolving. Same as Reset Package Caches in Xcode.
--derivedDataDir DIR	Same as for build.
--only-use-versions-from-resolved-file and the other three	Same as the Swift package options of build.

> kxbuild resolve .\MyApp.xcodeproj --force

project

Inspects, creates, edits and converts Xcode projects, and adds Swift package dependencies and app extensions. For what each built-in template generates and how to add your own, see Project templates.

Subcommand	Description
info	Prints targets, schemes, bundle IDs and executable paths as JSON.
templates	Lists the available project templates.
create	Creates a project from a template.
settings dump / apply	Reads build settings, or changes them in bulk.
add-setting	Adds or changes one build setting.
add-folder	Adds a folder group to the project.
add-resource	Adds a resource file to a target, such as .xcstrings or .xcassets
add-package	Adds a Swift package dependency to a target.
add-target	Adds an app extension, App Clip, framework, static library or resource bundle to a project.
spm2app	Turns a Swift package whose executable target is an app into an app project that builds an .ipa.

project info

kxbuild project info <project.xcodeproj | project.xcworkspace> [options]

Prints the project's targets, schemes, bundle IDs and executable paths as JSON.

Option	Description
-c, --config NAME	Reads settings from this configuration. Defaults to the one build would use.
--src	Includes each target's source files and header search paths.
--derivedDataDir DIR	Makes executablePath match the output directory of build.

> kxbuild project info .\MyApp.xcodeproj --src

project templates

kxbuild project templates

Lists the available project templates with their id, name, description and required tools. Pass the id to create -t. For what each template contains, see Project templates.

project create

kxbuild project create -t <template id> -n <name> [-b <bundle ID>] [-o <parent dir>] [--force] [--no-script]

Creates a project at <parent dir>/<name>. The CocoaPods, Flutter, React Native and Expo templates then run their setup steps, such as pod install or flutter create.

Option	Description
-t, --type ID	Template id, from templates or Project templates. Required.
-n, --name NAME	Project name. Starts with a letter and contains only letters, digits and underscores. Also used as the directory name. Required.
-b, --bundle-id ID	Bundle ID. Defaults to com.example.<name>.
-o, --output DIR	Parent directory. Defaults to the current directory.
--force	Creates the project in a non-empty directory.
--no-script	Copies the template without running its generator script.

> kxbuild project create -t app_swiftui -n MyApp -b com.example.myapp -o D:\projects

On Windows, the React Native and Expo templates create deeply nested dependency folders. Use a short parent directory such as D:\p to stay under the 260-character path limit.

project settings dump / apply

kxbuild project settings dump <project> [--project NAME] [--all] [--ops FILE] [--derivedDataDir DIR]

Prints the raw and resolved settings of every target and configuration, plus setting metadata, as JSON. --all also lists settings that aren't set explicitly. --project picks a project when the workspace has several. --ops FILE applies the changes in memory before computing, as a preview, and writes nothing.

kxbuild project settings apply <project> --ops FILE [--project NAME]

Applies a batch of changes to project.pbxproj. FILE is a JSON array with one operation per item. op is set, remove or rename. owner is project or a target name. config is a configuration name, or * for all configurations. value is a string or an array of strings, and rename uses newKey. The Project Settings Editor calls this when it saves.

[
  {"op": "set",    "owner": "MyApp",   "config": "*",       "key": "MARKETING_VERSION", "value": "1.2.0"},
  {"op": "set",    "owner": "project", "config": "Debug",   "key": "OTHER_LDFLAGS",     "value": ["$(inherited)", "-ObjC"]},
  {"op": "remove", "owner": "MyApp",   "config": "Release", "key": "ENABLE_BITCODE"}
]

> kxbuild project settings apply .\MyApp.xcodeproj --ops ops.json

project add-setting

kxbuild project add-setting -k KEY -v VALUE -P <project.xcodeproj> [-t TARGET] [-c CONFIG] [-a]

Adds or changes one build setting. Quicker than an ops file for a single change.

Option	Description
-k, --key KEY	Setting name, such as HEADER_SEARCH_PATHS.
-v, --value VALUE	Value. For an array, separate items with commas and add -a.
-a, --array	Writes the comma-separated value as an array.
-t, --target NAME	Target to change. Without it, changes the project level.
-c, --config NAME	Changes only this configuration. Without it, changes all configurations.
-P, --project PATH	Path to the .xcodeproj. Required.

> kxbuild project add-setting -k IPHONEOS_DEPLOYMENT_TARGET -v 15.0 -t MyApp -P .\MyApp.xcodeproj

project add-resource

kxbuild project add-resource -f <file> -P <project.xcodeproj> [-t TARGET]

Adds a resource file to a target's resources, such as a new Localizable.xcstrings, Assets.xcassets or .storyboard. Create the file first. A file already in the project is reused, and files inside an Xcode 16 folder (synchronized folder) don't need adding.

Option	Description
-f, --file PATH	The resource file, absolute or relative to the project's folder
-t, --target NAME	The target to add it to. Defaults to the first one
-P, --project PATH	Path to the .xcodeproj. Required

> kxbuild project add-resource -f MyApp\Localizable.xcstrings -t MyApp -P .\MyApp.xcodeproj

project add-folder

kxbuild project add-folder -f <folder name> -P <project.xcodeproj> [-p <parent group>]

Adds a folder group to the project's group tree. Without -p, adds it at the root.

project add-package

kxbuild project add-package -P <project.xcodeproj> (--url URL [version rule] | --path DIR) [--product P,…] [-t TARGET]

Adds a Swift package dependency to a target, like Add Package Dependencies in Xcode. It resolves the package right away and updates Package.resolved. If a product name is wrong or resolution fails, the project is left unchanged. Without a version rule, a remote package uses the latest version, up to the next major version. If the repository has no version tags, it tracks the default branch. Needs network access.

Option	Description
-P, --project PATH	Path to the .xcodeproj. Required.
--url URL	Git URL of a remote package.
--path DIR	Directory of a local package. Use either this or --url.
--product P,…	Library products to link, comma separated. Optional when the package has only one library product. With several, omitting it lists the choices.
-t, --target NAME	Target that links the products. Defaults to the first target.
--from VERSION	Up to the next major version, starting from this version.
--up-to-next-minor VERSION	Up to the next minor version, starting from this version.
--exact VERSION	Exactly this version.
--range A..<B	Version range, such as 5.0.0..<6.0.0.
--branch NAME	Tracks this branch.
--revision SHA	Pins to this commit.
--no-resolve	Only edits the project, without resolving over the network. The next build resolves it. Requires --product, and a version rule for a remote package.

> kxbuild project add-package -P .\MyApp.xcodeproj --url https://github.com/Alamofire/Alamofire.git --from 5.9.0 --product Alamofire

> kxbuild project add-package -P .\MyApp.xcodeproj -t MyApp --path ..\MyKit

project add-target

kxbuild project add-target -P <project.xcodeproj> --type <type> --name <name> [--language swift|objc] [--host TARGET | --no-host] [--bundle-id ID] [--app-group ID]

Adds a target to a project, such as an app extension like a widget, an App Clip, a framework, a static library or a resource bundle. It's the equivalent of Xcode's File > New > Target. The sources go into a folder of the same name next to the .xcodeproj, and the new target is built and installed with the app, with the same build configurations. If anything fails, the project is left unchanged. Before signing an extension or App Clip, register an App ID and create a provisioning profile for its bundle ID in the Apple Developer portal. With --app-group, also enable App Groups on both App IDs. The command output lists what's needed. See Certificates and signing.

Option	Description
-P, --project PATH	Path to the .xcodeproj. Required
--type TYPE	The target type, see the table below. Required
--name NAME	The target name, also used for the source folder. Letters, digits and underscores, starting with a letter. Required
--language LANG	Language of a framework or static library, swift or objc. Defaults to swift
--host NAME	The app target to add it to. Optional when the project has only one app
--no-host	Adds a framework, static library or resource bundle without adding it to any app
--bundle-id ID	The bundle ID. For an extension it defaults to the app's bundle ID plus a dot and the lowercased name, and must start with the app's bundle ID and a dot
--app-group ID	An App Group shared by the app and the extension or App Clip, such as group.com.example.myapp. Use it when they share data
--list	Lists every type

Type	What it does
framework	Dynamic framework, linked and embedded in the app. Swift or Objective-C
static-library	Static library, linked into the app. Swift or Objective-C
bundle	Resource bundle, copied into the app
app-clip	App Clip embedded in the app, bundle ID is the app's plus .Clip
widget	Home Screen and Lock Screen widget
widget-live-activity	A widget plus a Live Activity for the Lock Screen and Dynamic Island
notification-service	Modifies push content before it's shown, downloads attachments
notification-content	Custom interface for expanded notifications
share	Receives text, links and images from the share sheet
action	Acts on content from other apps through the share sheet
imessage	iMessage extension in the Messages app
keyboard	Custom keyboard
photo-editing	Edits photos inside the Photos app
quicklook-preview	Previews custom files in Files and other apps
thumbnail	Generates thumbnails for custom files
safari-web-extension	Safari web extension
content-blocker	Safari content blocker
broadcast-upload	Broadcast upload extension for screen broadcasting
broadcast-setup-ui	Setup screen shown before a screen broadcast starts
file-provider	Provides your cloud files in the Files app. Needs an App Group
credential-provider	Supplies passwords for AutoFill
call-directory	Caller ID and call blocking
message-filter	Filters text messages from unknown senders
network-extension	VPN tunnel (Packet Tunnel)
device-activity-monitor	Screen Time device activity monitor
shield-configuration	Screen Time shield appearance
shield-action	Handles the buttons on a Screen Time shield
background-download	Asset packs the system downloads at install and update. iOS 26 and later

> kxbuild project add-target -P .\MyApp.xcodeproj --type widget --name MyAppWidget --app-group group.com.example.myapp

project spm2app

kxbuild project spm2app <package dir> [-n NAME] [-b ID] [--executable E] [-o DIR] [--force] [--no-resolve]

For a package whose executable target is a SwiftUI or UIKit app, creates an iOS app project from that code and references the package as a local package. Build that project with build to get an .ipa. By default the project goes in <package dir>\<App name>\, so you commit it together with the package. Library-only packages are not converted. Add them to an app project with add-package instead. If a target in the same package that the app uses has no library product, spm2app adds a .library line to Package.swift and lists that change in its output. For the full workflow, see Swift packages.

Option	Description
-n, --name NAME	App name. Defaults to the name of the app executable.
-b, --bundle-id ID	Bundle ID. Defaults to com.example.<App name>.
--executable E	Picks the app executable to convert when the package has several.
-o, --output DIR	Parent directory. The project is created at <DIR>\<App name>. Defaults to the package directory.
--force	Creates the project in a non-empty directory.
--no-resolve	Doesn't resolve packages after generating the project.

> kxbuild project spm2app . -n MyApp -b com.example.myapp

update

kxbuild update [--check] [--no-doctor]

Updates kxbuild to the latest version by downloading it and replacing the local binary, ready to run. Afterwards, runs doctor once with the new version.

Option	Description
--check	Only reports whether a newer version exists. Installs nothing.
--no-doctor	Doesn't run doctor after updating.

> kxbuild update --check

version

kxbuild version [--json]

Prints version information. With --json, prints a single JSON object that scripts can use to check the version. Include this output when you ask for help.

Next steps

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.

Folders and environment variables

What's in the KXBUILD_HOME install folder, the keychain and shared folders, what appears in your project folder, and the environment variables you might need.