Run and build

sochi run builds, installs and launches the app. sochi build only builds it. Both take the same options:

sochi run [path] [--scheme <scheme>] [--device <device>] [--sim] [--configuration <name>] [--team <team>] [--fresh]

path is a folder, an .xcodeproj or an .xcworkspace. It defaults to the current folder.

The scheme

Without --scheme, sochi uses the scheme it saved for this project last time. If there isn’t one, it asks xcodebuild for the project’s schemes, skips any that start with Pods or end in Tests, and prefers the one named after the project.

sochi run --scheme WeatherDev

Scheme names are matched without regard to case. If a saved scheme has since been deleted, sochi notices, picks again, and says so.

Devices

By default sochi runs on a connected iPhone or iPad, using the first one it can reach. List what’s paired with:

sochi devices

iPad Air               iPad Air 11-inch (M3) · iOS 26.1 · 00008112-000A3C1E2B90401E  ● connected
Ana’s iPhone           iPhone 16 Pro · iOS 26.1 · 00008140-001A2D3E0C12801E  ● available
Old iPhone             iPhone SE · iOS 18.6 · 00008030-0019642E3A40802E  ○ unavailable  developer mode off

available means the Mac can reach the device but hasn’t opened a connection yet. sochi connects when it needs to.

Picking a device

--device takes any part of a device’s name or model that only one device has, or the start of its UDID:

sochi run --device ipad
sochi run --device "ana's"
sochi run --device 00008140

sochi tries these in order and stops at the first that matches anything:

1. The exact name or the full UDID.
2. The start of a UDID.
3. Any part of the name or model.

Case doesn’t matter, and a straight apostrophe matches the curly one in default names like “Ana’s iPhone”. If more than one device matches, sochi lists them and asks you to type more instead of guessing.

A device you name with --device is used even when it doesn’t look reachable, so you can try a device that’s waking up.

Note

sochi currently runs on iPhone and iPad only. sochi devices lists every paired device, but --device only matches iOS ones.

Simulators

sochi run --sim
sochi sims

With --sim, sochi uses a booted iOS simulator if there is one. Otherwise it picks an iPhone Pro on the newest runtime, or failing that any iPhone. It boots the simulator and opens Simulator.app in the background.

To choose a simulator, pass its exact name or UDID:

sochi run --sim --device "iPhone 16e"

If --device doesn’t match any physical device, sochi also checks for a simulator with exactly that name, so sochi run --device "iPhone 16e" works without --sim.

Signing team

Device builds use Xcode’s automatic signing. sochi passes -allowProvisioningUpdates and -allowProvisioningDeviceRegistration, so Xcode registers your device, App ID and capabilities with Apple as part of the build.

The team comes from the project. To override it, pass a team ID or name, or set SOCHI_TEAM:

sochi run --team A1B2C3D4E5
sochi run --team "Example Ltd"
SOCHI_TEAM=A1B2C3D4E5 sochi run

Team names are matched against the accounts signed into Xcode › Settings › Accounts. sochi remembers the team after a successful build. To forget it and go back to the project’s own team:

sochi run --team auto

If the project has no team and you only have one, sochi retries the build with it and tells you:

↻ project has no development team, signing with A1B2C3D4E5

With several teams it stops and lists them, so you can choose one with --team.

Configuration

Builds use the Debug configuration unless you pass another:

sochi build --configuration Release

What sochi remembers

sochi saves the scheme and team you used once a build succeeds, and records what it installed on each device. It never saves build settings. Those are read fresh from xcodebuild on every run, so changes you make in Xcode or an .xcconfig file always apply.

Remembered values are marked (saved) on the first line of output. They’re stored per project, outside your repository. See Files and environment.

Install skipping

On a device, sochi skips the install when the device already has this exact build: the same bundle ID, the same signed executable, and the same app container on the device. You’ll see:

✓ com.example.Weather already up to date on device (checked in 0.4s)

Pass --fresh to always reinstall. Remembered choices still apply. Simulators are always reinstalled.

Before installing anywhere, sochi checks that the bundle ID matches and that the app was built for that destination, so a simulator build never goes onto a device.

Build output

While building, a single line shows the current task. Errors and warnings print with their file, line and column, the source line and a caret under the problem. A successful build ends with:

✓ built in 14.2s (212 tasks), 2 warnings

If sochi can’t make sense of a failure, it prints the last 40 lines of raw xcodebuild output.

Colours and the live status line only appear in an interactive terminal. Set NO_COLOR=1 to turn them off.

Stopping the app

Press ctrl-c. sochi stops the app and prints stopped.

Swift packages

If there’s a sochi.toml next to the project, run and build sync it with the project before building. See Swift packages.