Usage

Session options (run / build)

Option	Default / notes
path	. — project directory, .xcodeproj, or .xcworkspace
-s, --scheme	App scheme if omitted
-d, --device	Connected physical device if omitted
--sim	Use a simulator
-c, --configuration	Debug
--team / SOCHI_TEAM	Override development team; auto forgets saved override
--fresh	Always reinstall (ignore install fingerprint skip)

Scheme and team may be remembered. The status line marks those with (saved).

State locations:

• DerivedData: ~/Library/Caches/dev.sochi/projects/<name>-<hash>/DerivedData
• Remembered scheme / team / install records: ~/Library/Application Support/dev.sochi/projects/<id>/state.json

Build settings are always queried fresh from xcodebuild; only choices (scheme, team) are sticky.

sochi new

Creates a project from an Xcode project template (default app = iOS App).

sochi new Weather --org com.example
sochi new Weather --option storageType=SwiftData
sochi new Arcade --template game --option gameType=SpriteKit

Flag	Notes
--org	Bundle ID prefix; remembered after first use
--template	Default app; see sochi templates
--option key=value	Template options (repeatable)
--team	DEVELOPMENT_TEAM
--directory	Parent directory (default .)

Then: cd <Name> && sochi run.

sochi run / sochi build

sochi run
sochi run --sim
sochi run --scheme App --device "iPhone"
sochi build --configuration Release

run pipeline: resolve session → xcodebuild (streamed log; one retry on recoverable scheme/team failures) → prepare destination → verify app product → install if needed → launch with console (devicectl --console or simctl launch --console-pty). CLI chrome is on stderr; app output is on stdout.

Install skip: on a physical device, install is skipped when the on-device URL and app fingerprint match the saved InstallRecord, unless --fresh. Simulators always install.

Devices / sims / doctor

sochi devices
sochi sims
sochi doctor

Capabilities and targets

sochi capabilities --all
sochi add capability push-notifications
sochi add capability associated-domains applinks:example.com
sochi remove capability app-groups group.com.example.old

sochi templates
sochi add target widget-extension Forecast
sochi add target widget-extension Forecast --option includeLiveActivity=false
sochi add target Kit --type framework --no-embed

Capability names come from Apple’s catalog in the selected Xcode (slug, ID, or unambiguous substring). List values are extra args. Background Modes is a local capability written to Info.plist. Some capabilities still require portal registration on the next automatic-signing build.

add target requires a host app target in a folder-based project (objectVersion ≥ 77). Convert classic group projects with sochi migrate first.

Edit flags: --project, --dry-run, --force (allow XcodeGen/Tuist-marked projects).

Entitlements

Use when there is no capability slug:

sochi entitlements
sochi entitlements set com.apple.developer.healthkit true
sochi entitlements add com.apple.security.application-groups group.com.example.shared
sochi entitlements remove com.apple.developer.healthkit

sochi migrate

Converts PBX groups that mirror on-disk folders into file-system-synchronized folders. Membership exceptions and per-file compiler flags are preserved when possible. Groups that cannot convert faithfully are left as groups with a reason.

sochi migrate
sochi migrate --dry-run
sochi migrate --move-files     # materialize virtual groups, then convert
sochi migrate --no-verify      # skip before/after build compare (static checks remain)

By default, sochi builds before and after (device SDK, no signing) and refuses if compiled sources or bundled product files differ. After a successful migrate, the project requires Xcode 16+.

Failure modes

Symptom	Action
Destination / “waiting for device”	Unlock device, keep awake, or use USB; retry
Ambiguous project, target, or team	Pass path, --scheme, --target, or --team
Generated project refused	--force if you intend to edit XcodeGen/Tuist output
SPM package only	Not supported; need .xcodeproj / .xcworkspace
Cannot add target on classic groups	sochi migrate first