CLI reference
Every swiftpieces command. New here? Start with the Quickstart.
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"
}