Using LPM CLI with Swift

LPM CLI connects Swift Package Manager to LPM.dev Registry through the SE-0292 registry protocol. SwiftPM resolves and builds the dependencies.

From a directory with Package.swift:

lpm install @lpm.dev/owner.swift-pkg
swift build

Install a compatible Swift toolchain first. For Xcode projects, install Xcode and select the intended developer directory.

Private, Pool, and Marketplace packages require authentication and package access. Available Free releases need no account.

Install a dependency

# Authenticate for a protected package
lpm login

# Install an available version
lpm install @lpm.dev/owner.swift-pkg

# Install a specific version
lpm install @lpm.dev/owner.swift-pkg@1.2.0

LPM CLI configures the registry endpoint, certificate, and signing policy before SwiftPM resolves the package. Protected access also requires a SwiftPM registry login.

One eligible target is selected automatically. With several targets, the command asks which target receives the product.

For non-interactive installation:

lpm install @lpm.dev/owner.swift-pkg@1.2.0 --yes

--yes selects the first eligible target. Check the resulting Package.swift before committing it.

The dependency must expose a compatible library product. Test, binary, and system targets cannot receive package products through the target selector.

Identity mapping

lpm install writes the SwiftPM identity into Package.swift. The underscore separates the owner from the package name.

A local Package.swift takes precedence over an unrelated parent package.json. Swift dependencies belong in Package.swift, not lpm.json.

For a mixed workspace, run from the Swift member directory or select it with --filter. Use -w to select a root Swift package.

Check resolution and commit the result

swift build
swift test

Commit the manifest changes and the project's applicable Package.resolved file. Follow the repository's lockfile policy for reusable libraries.

Reinstalling an existing declaration still resolves dependencies and checks package access. Cached transitive dependencies do not bypass LPM.dev Registry access rules.

If you intend to copy source files, use lpm add. It is a different workflow from a native Swift dependency.

Xcode projects and workspaces

From the directory with your .xcodeproj or .xcworkspace:

lpm install @lpm.dev/owner.swift-pkg --yes

LPM CLI creates Packages/LPMDependencies and links its library into the app target. The wrapper exports the dependency's modules.

Its deployment targets account for the app and installed dependencies. Existing higher minimum versions remain intact.

A single project is selected automatically. With several direct projects, LPM CLI prefers the project matching the directory name.

If projects come from one workspace, its name can select the matching project.

If selection is ambiguous, run from the intended project directory. References outside the workspace and symbolic links also require the actual project directory.

LPM CLI configures the lpmdev scope for both the wrapper and Xcode's user configuration. Other registry scopes remain intact.

The command resolves the project and its containing workspaces before success. A failed resolution restores the project, wrapper, and shared lockfiles.

Before it changes project.pbxproj, LPM CLI saves the previous file as .lpm/xcode-backups/<Project>.pbxproj next to the .xcodeproj. That copy is local and stays out of Git. Earlier releases kept it as project.pbxproj.lpm-backup inside the .xcodeproj bundle. LPM CLI removes that file at its next project edit.

Commit the wrapper, project changes, and shared Package.resolved files. If Xcode was open, reopen the project after installation.

Build in CI

A fresh runner needs the registry scope, signing certificate, signing policy, and SwiftPM credentials before native resolution.

From the Xcode project directory, provide a read-scoped LPM_TOKEN for protected packages and run:

lpm swift-registry --json

This configures the project scope and Xcode's user scope. A CLI token alone does not configure SwiftPM authentication.

Use the same package-cache path for resolution and the frozen build:

xcodebuild -resolvePackageDependencies \
  -workspace MyApp.xcworkspace -scheme MyApp \
  -clonedSourcePackagesDirPath .ci/SourcePackages

xcodebuild -workspace MyApp.xcworkspace -scheme MyApp \
  -clonedSourcePackagesDirPath .ci/SourcePackages \
  -disableAutomaticPackageResolution \
  -onlyUsePackageVersionsFromResolvedFile build

Replace the workspace and scheme names. CI needs credentials for protected dependencies, even when it restores a package cache.

Publish a Swift package

Publication needs both Package.swift and a package.json that identifies the Registry release. The manifest selects the files to upload:

{
  "name": "@lpm.dev/acme.swift-widget",
  "version": "1.0.0",
  "description": "Swift widget library",
  "license": "MIT",
  "files": ["Package.swift", "Sources", "Tests"]
}

Replace the owner and package name. Include any resources or alternate manifests that the package requires.

Select LPM.dev Registry explicitly in the package's own configuration:

{
  "publish": {
    "registries": ["lpm"]
  }
}

swift build
swift test
lpm publish --lpm --check
lpm login
lpm publish --lpm --dry-run --ignore-scripts
lpm publish --lpm --yes --ignore-scripts --wait

The local check inspects Package.swift from the publication archive with the selected Swift toolchain. On macOS, it uses the developer directory from xcode-select.

Malformed manifests, unsupported tools versions, and failed inspection stop publication. Literal Sources and Tests entries select root directories, excluding matching directories under .build.

LPM CLI uploads the package archive. LPM.dev Registry inspects it, creates the Swift source ZIP, and signs the release artifacts.

The Registry signing key stays on the service. Publishers do not need that key to publish.

New packages start in Private distribution. See package distribution before requesting Free, Pool, or Marketplace distribution.

Repair registry configuration

lpm swift-registry

lpm swift-registry downloads the current certificate and checks the endpoint and signing configuration. A failed certificate download preserves the previous file.

Automatic installation performs these checks too. Malformed configuration stops setup before replacement.

The lpmdev policy accepts the Registry's signing certificate. It does not establish the publisher's identity or prove that package code is safe.

See the Swift registry trust model for the exact signing guarantees.

Troubleshooting

See also

• lpm install — dependency installation
• Swift package registry — protocol, manifests, and trust
• Publishing a package — publication checks and recovery
• lpm swift-registry — configuration repair