Capabilities and entitlements

A capability is something like Push Notifications, App Groups or HealthKit: a feature Apple has to enable for your App ID, usually backed by one or more entitlements in your app. sochi adds them the way Xcode’s Signing & Capabilities tab does.

See what a target has

sochi capabilities

This prints the app target’s entitlements file and each capability it has, with its values. Entitlements that don’t belong to a known capability are listed by their Xcode name or raw key. Use --target to look at a different target.

Find a capability

sochi capabilities --all

This lists every iOS capability in Apple’s catalog, read from the selected Xcode. Entries that need an identifier from you are marked (needs ID), and those Apple has to approve for your account are marked (needs Apple approval). A few capabilities exist only inside Xcode, not in Apple’s catalog. Those are marked (Xcode-only).

sochi doesn’t keep its own list. It reads the catalog Xcode downloads for your team, and falls back to the copy shipped inside Xcode, so new capabilities show up when you update Xcode.

Add a capability

sochi add capability push-notifications
sochi add capability sign-in-with-apple
sochi add capability healthkit

You can name a capability by its name in the list (push-notifications), Apple’s ID (PUSH_NOTIFICATIONS), or any part of its name that only it has (push). If a name matches several, sochi lists them.

sochi then:

1. Works out the entitlement keys and values from Xcode’s own schema and Apple’s entitlement documentation.
2. Shows the changes as a diff.
3. Writes them and checks that xcodebuild resolves the target’s entitlements file as expected.
4. Puts every file back if that check fails.

Your App ID and provisioning profile are updated by automatic signing the next time you sochi run.

Capabilities that take values

Some capabilities need values, such as domains, group identifiers or container IDs. Pass them after the name:

sochi add capability associated-domains applinks:example.com webcredentials:example.com
sochi add capability app-groups group.com.example.shared
sochi add capability network-extensions packet-tunnel-provider

If a value is required and missing, sochi tells you which key needs it, what form it takes, and links to Apple’s documentation for it. If a capability offers a fixed set of choices, sochi lists them. Adding values to a capability that already has some keeps the existing ones.

Background Modes

background-modes is written to the target’s Info.plist (UIBackgroundModes), not to entitlements, and it needs at least one mode:

sochi add capability background-modes remote-notification
sochi add capability background-modes audio fetch

If the target only has a generated Info.plist, sochi creates an Info.plist file in the target’s folder and points the target at it.

Keychain Sharing

keychain-sharing adds $(AppIdentifierPrefix) to the front of each group for you, and uses the app’s own bundle ID if you don’t pass one.

Remove a capability

sochi remove capability push-notifications
sochi remove capability app-groups group.com.example.old

Pass values to remove only those values and keep the rest. Names work the same way as for add.

Edit entitlements directly

When there’s no capability for what you need, edit the entitlements file directly. This works for every entitlement key.

sochi entitlements                       # show the app target's 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

set works out the type from what you pass:

You pass	It’s stored as
A single true or false	A boolean. Add --string to store it as text instead.
Several values	An array.
One value with --array	An array with one item.
Anything else	A string.

add appends values to an array entitlement, skipping any that are already there, and creates it if needed. remove deletes a key, or only the values you pass. A key left empty is removed.

Which target and which file

Every editing command uses the app target unless you pass --target. If the project has several app targets, sochi chooses the one that matches your saved scheme or the project name. If it still can’t tell, it asks you to pick one.

sochi finds the entitlements file through the target’s resolved build settings, so a CODE_SIGN_ENTITLEMENTS set in an .xcconfig file is respected. If the target has no entitlements file, sochi creates <Target>.entitlements in the target’s folder and sets it for every configuration. If only some configurations have one, sochi stops and asks you to set the others first rather than guess.

Options for every edit

Option	Effect
-t, --target <name>	The target to edit. Defaults to the app target.
--project <path>	A folder, .xcodeproj or .xcworkspace. Defaults to the current folder.
--dry-run	Show the diff without writing anything.
--force	Edit a project that looks generated by XcodeGen or Tuist.

sochi refuses to edit a project if it finds project.yml, project.yaml, Project.swift, Tuist.swift, Tuist or Workspace.swift next to it, because the next generation would overwrite the edit. Change the generator’s manifest instead, or pass --force if you mean to edit the .xcodeproj anyway.