Get started with the CLI

The sweetpad command-line tool builds, runs, and tests your Xcode apps from the terminal, with no editor needed. This page gets you from install to a running app in a few minutes. You need a Mac with Xcode installed.

1. Install

Install with Homebrew:

brew install sweetpad-dev/tap/sweetpad

Check that it worked:

sweetpad --version

2. Get a project

You can start a brand-new app or point SweetPad at one you already have.

Create a new project

sweetpad project new scaffolds a minimal SwiftUI app. Run it with no options and it walks you through a short set of questions (project name, iOS or macOS, bundle identifier, and so on) and then creates the project for you:

sweetpad project new

Prefer to skip the questions? Pass a name (and any options you want) and it uses sensible defaults:

sweetpad project new MyApp --platform ios

When it's done, hop into the new folder:

cd MyApp

Starting a project has every option and what the scaffold contains.

Or use an existing project

Already have a project? Just cd into it, anywhere inside a folder that has an .xcworkspace, .xcodeproj, or Package.swift. SweetPad finds the project by looking in the current folder and its parents, just like git does.

cd ~/Developer/MyApp

3. See where you are

Run sweetpad status to see what SweetPad thinks it's working with:

sweetpad status

The first time, it may not have picked a scheme or a place to run yet. That's fine; the next step sorts it out.

4. Build and run

Run your app with a single command:

sweetpad run

The first time in a project, SweetPad asks which scheme to build and which simulator or device to run on, then remembers your choice so it won't ask again. It builds the app, launches it, and streams the app's logs right in your terminal.

Want to skip the questions and just say where to run? Use --on with a simulator name, mac, or booted (whatever simulator is already open):

sweetpad run --on "iPhone 16 Pro"

5. Try a few more commands

Here are the everyday ones:

# See everywhere you can run — simulators, devices, and macOS
sweetpad devices

# Just build, don't run
sweetpad build

# Run your tests
sweetpad test

# Format your Swift files
sweetpad format

Most commands ask you to pick a scheme or destination the first time, then remember it. Run sweetpad status any time to see the current choices, or change them with sweetpad context.

Getting help

Every command explains itself with --help:

sweetpad --help              # all commands
sweetpad run --help          # options for one command

And there are a few longer guides built right into the tool:

sweetpad help                # list the guides
sweetpad help destinations   # how to pick where to run
sweetpad help config         # settings you can save

Where to go next

The Overview is the fuller tour if you'd rather read one page than pick a topic. Otherwise:

The daily loop. Build and run goes deeper on what you just did, including reading a failed build. Testing covers narrowing a run, watch mode, and getting at what the tests recorded. Formatting is short. Hot reload skips the rebuild entirely and injects each save into the running app.

Where it runs. Destinations and devices is everything about choosing where a build goes. Simulators drives one: screenshots, push payloads, permissions. App lifecycle and debugging covers logs, lldb, and crash reports.

Your project. Starting a project scaffolds a new one. Project and dependencies reads and edits what's in the project. Tuist and XcodeGen covers generated ones. Archive and distribute ships it. Git merge drivers stop .pbxproj conflicts from ruining your afternoon.

Setup and automation. Configuration is how you stop answering the same prompts, for you or your team. Editor autocomplete wires up completions in Neovim, Zed, Helix, or Emacs. Scripts and CI covers JSON output, exit codes, and a working GitHub workflow.

When something's wrong. Troubleshooting starts from sweetpad doctor and works outward. The CLI reference lists every command, flag, config key, and exit code on one page.

Working in an editor? The VS Code extension is a separate product that does all of this from the VS Code sidebar. You don't need it for anything above.