CLI

The swiftpieces CLI copies SwiftUI components into your Xcode project. Run npx swiftpieces add GlassSurface from the folder that contains your .xcodeproj. It writes files you own. It is distributed through npm so no extra toolchain is required, and it contains no premium source. Free components come from swiftpieces.com. A license key also reaches the Pro registry on pro.swiftpieces.com.

Commands

npx swiftpieces init                 # optional: add does this on first run
npx swiftpieces add GlassSurface     # free piece
npx swiftpieces add SignInBlock      # Pro pattern, with Pro's design system; needs a license
npx swiftpieces add subscription-app # Pro template, needs a license
npx swiftpieces add Silk --overwrite
npx swiftpieces list                 # free registry
npx swiftpieces list --pro           # Pro registry (metadata is public)
npx swiftpieces login sp_live_...    # store your key in ~/.swiftpieces/auth.json
npx swiftpieces whoami               # check whether your key has Pro access

Resolution order

add tries the free registry first. On a 404 it tries the Pro registry with your license key from SWIFTPIECES_LICENSE_KEY or ~/.swiftpieces/auth.json. A Pro piece without a valid key produces a short message pointing at pro.swiftpieces.com, never a stack trace.

swiftpieces.json

{
  "$schema": "https://swiftpieces.com/schema/config.json",
  "directory": "MyApp/SwiftPieces",
  "minIOSVersion": "17.0",
  "registries": {
    "free": "https://swiftpieces.com/r",
    "pro": "https://pro.swiftpieces.com/r"
  }
}

Behavior

• Warn, don't overwrite. Existing files are skipped unless you pass --overwrite.
• Dependencies resolve recursively through registryDependencies, across both registries.
• Shaders and assets listed by a piece are written alongside it.
• Project requirements (Info.plist keys, capabilities, SPM packages) are printed after install for you to apply.
• Writes stay in the destination. A path with .., an absolute path, or a symlink that leaves the SwiftPieces folder (or the agent's skills folder, for the Build Kit) is refused.
• The license key goes to pro.swiftpieces.com. It is not sent to any other registry unless you pass --trust-registry.
• Registries are https. http:// is refused, except --allow-http-localhost for a registry on localhost. An item that doesn't match the registry schema is not written.