CLI Reference
Install SwiftPieces Pro screens into an Xcode project with npx swiftpieces and the license key from your account.
The CLI runs through npx, so there is nothing to install. It fetches pieces with your license key; it contains no source itself. For the first-time setup, follow the Quickstart.
Commands
| Command | What it does |
|---|---|
npx swiftpieces login sp_live_... | Saves your license key to ~/.swiftpieces/auth.json |
npx swiftpieces whoami | Confirms the saved key has Pro access |
npx swiftpieces init | Creates the SwiftPieces folder and swiftpieces.json |
npx swiftpieces add wallet-stack | Adds a piece and everything it depends on |
npx swiftpieces add wallet-stack --overwrite | Replaces files you already have |
npx swiftpieces list --pro | Lists every Pro piece with its id |
npx swiftpieces add style-studio brief-finance | Installs Build Kit items as skills for your coding agent |
npx swiftpieces add tool-review --agent codex | Picks the agent: claude, codex, cursor or xcode (comma-separate for several) |
npx swiftpieces add swift-pieces --global | Installs a skill for every project instead of this one |
npx swiftpieces list --kit | Lists every Build Kit item with its id |
In CI, set SWIFTPIECES_LICENSE_KEY instead of running login.
How add behaves
- Dependencies come along. Adding a template or themed screen also adds the design system and the pieces it composes.
- Your edits are safe. Existing files are skipped unless you pass
--overwrite. - Shaders come along. Metal files a piece needs are written next to it and compile into your app.
- Kit ids go to your agent. Ids starting with
style-,brief-,recipe-ortool-(andswift-pieces) are written as skills to your agent's skills folder, not toSwiftPieces/. They don't needswiftpieces.json. - Project settings are listed, not changed. Required capabilities and Info.plist keys print after install for you to apply.
swiftpieces.json
{
"directory": "MyApp/SwiftPieces",
"minIOSVersion": "17.0"
}