xcodebuild for humans. Build, run, debug, and test iOS, macOS, tvOS, watchOS, and visionOS apps from your terminal, without opening Xcode. No Xcode window, no editor required. Works with Xcode projects and workspaces, Tuist, XcodeGen, and Swift Packages.
Full documentation lives at sweetpad.hyzyla.dev. If it saves you time, star the repo ⭐️ or become a sponsor 💰
Try it
brew install sweetpad-dev/tap/sweetpad
A Mac with Xcode is the whole dependency list. Then:
sweetpad project new MyApp # or just cd into a project you already have cd MyApp sweetpad run
run builds, installs, launches, and streams the logs. Press r to rebuild and relaunch without
leaving, q to quit.
The first run asks which scheme to build and where to run it, then remembers, so you never answer again. To skip the question outright, say where you want it:
sweetpad run --on "iPhone 16 Pro" # closest matching simulator or device sweetpad build --on mac # your Mac sweetpad test --on booted # whichever simulator is already open
Full walkthrough: Get started with the CLI.
Why you'd stay
- Hot reload:
sweetpad run --hotpatches each Swift file you save into the live process, so the app keeps its screen and its state. - Autocomplete anywhere:
sweetpad bsp initpoints SourceKit-LSP at SweetPad's build server, so Neovim, Zed, Helix, and Emacs get completions and diagnostics on a real Xcode project. - Debug without the IDE: run under lldb,
script a session with
--batch --cmd, or letapp diagnosecatch the first crash and print a structured report. - Scripts and CI: every command speaks
JSON, exit codes are specific enough to branch on, and
--gh-annotationsputs errors inline on a pull request. - Agent skills: vendor-neutral files that
teach Claude Code, Cursor, Codex, Copilot, or Gemini to drive the CLI properly:
npx skills add sweetpad-dev/sweetpad
The rest of the surface
| Command | What it does |
|---|---|
sweetpad test |
Run tests, with --only-testing, --failed, --retry-flaky, --coverage, --junit. |
sweetpad format |
Format Swift sources, or lint them with --tool swiftlint. |
sweetpad devices |
Everything runnable (Mac, simulators, connected devices), each with a copy-paste specifier. |
sweetpad simulator |
Boot, clone, erase, screenshot, record mp4, set location and permissions, deliver a push. |
sweetpad project |
Inspect the project, resolve a build setting, add or update Swift Package dependencies. |
sweetpad archive |
Archive and export an .ipa. |
sweetpad merge |
Git merge drivers that resolve project.pbxproj conflicts semantically, not line by line. |
sweetpad doctor |
Diagnose the local Xcode and Swift toolchain when something is off. |
Configuration is optional and layered: answer the prompts once, or commit a sweetpad.toml for the
team and keep your own preferences in ~/.config/sweetpad/config.toml. sweetpad status prints which
layer won. And SweetPad never tries to wrap all of xcodebuild. Anything after -- is handed over
untouched, so one unusual flag doesn't send you back to the raw tool:
sweetpad build -- SWIFT_ACTIVE_COMPILATION_CONDITIONS="DEBUG STAGING"The tool documents itself offline too: sweetpad --help, sweetpad <command> --help, and
sweetpad help <topic> for config, environment, exit-codes, destinations, and hot-reload.
Prefer to work in VS Code?
The same builds, runs, and tests in the VS Code sidebar, plus breakpoints via CodeLLDB, a native Testing panel, format-on-save, and autocomplete. It works in Cursor too, and has over 61,000 installs on the Marketplace.
You do not need both. The CLI needs no editor, and the extension builds, runs, debugs, and tests on its own. They meet in exactly one place: the extension's default autocomplete runs the build server that ships inside the CLI binary, so that one feature asks for the CLI as well. Which one do I need?