lpm swift-registry

lpm swift-registry configures Swift Package Manager access and package signing trust for LPM.dev Registry.

lpm swift-registry [OPTIONS]

Use this command to prepare or repair Swift registry access. lpm install runs setup automatically for Swift packages, so a separate setup command is usually unnecessary.

The registry scope applies to the current Swift project. For an Xcode project, setup also configures the user-wide lpmdev scope. The certificate and signing-trust configuration apply to your user account and can affect other Swift projects.

Quickstart

From the directory with Package.swift, run:

lpm login
lpm swift-registry

See lpm login for authentication. Swift must be available on PATH. The command uses your installed Swift toolchain.

For a normal package installation, run:

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

Automatic setup skips login for Free releases. Protected releases use the current Registry credential, including when the project already has the correct scope.

Examples

lpm swift-registry                         # configure or repair access
lpm swift-registry --force                 # replace the local certificate
lpm swift-registry --json                  # report each setup outcome
lpm swift-registry --registry https://registry.example.com

For an unattended run, provide a Registry credential through the environment:

LPM_TOKEN="$REGISTRY_TOKEN" lpm swift-registry --json

The command has no confirmation prompt or --yes flag. SwiftPM receives --no-confirm for login and can persist the credential in its own authentication storage.

A task in lpm.json

lpm.json has no dedicated Swift registry configuration. An uncached task can run setup from a Swift project:

{
  "tasks": {
    "swift-setup": {
      "command": "lpm swift-registry",
      "cache": false
    }
  }
}

lpm run swift-setup
lpm run swift-setup -- --force --json

The extra arguments apply to that run. See lpm run.

What setup changes

Setup first checks existing project and user-wide SwiftPM configuration. Malformed JSON, unsupported versions, invalid field types, and linked configuration files stop setup before changes. --force does not bypass this check.

After that check, setup performs these operations in order:

1. Set the project registry scope and, for an Xcode project, the user-wide lpmdev scope.
2. If HTTPS and a Registry credential are available, log in through SwiftPM.
3. Download and install the current package signing certificate.
4. Configure the user-wide signing-trust policy.

A failed operation stops the command. Earlier successful operations remain in place. After you resolve the error, rerun setup.

Registry scope and URL

The project scope points to <registry-url>/api/swift-registry. Explicit setup checks the Swift toolchain and updates the project scope. Automatic installation retains a matching project scope.

A trailing slash in the base URL does not change the endpoint. Scheme matching is case-insensitive. Base URLs with embedded credentials, query parameters, or fragments are rejected before setup changes.

HTTPS works for hosted and private registries that implement this API. HTTP works only for loopback development addresses. SwiftPM receives --allow-insecure-http for those addresses and skips authentication. The global --insecure flag does not permit a remote HTTP server for this command.

From an Xcode project, explicit and automatic setup configure the global lpmdev scope. A local Package.swift selects ordinary SwiftPM setup instead. See Xcode projects and workspaces.

Authentication

--token overrides LPM_TOKEN, which overrides stored credentials. A stored browser session can refresh before login and retry once after SwiftPM rejects the first login attempt. Explicit and environment tokens do not refresh automatically.

LPM CLI passes the credential through a temporary file, with Unix permissions 0600. It removes that file after SwiftPM exits. The credential does not appear in SwiftPM process arguments. SwiftPM can retain its own authentication after the temporary file is removed.

If no credential exists, setup skips login and can still succeed. This does not clear credentials that SwiftPM already stores. For protected access, run lpm login, then rerun setup or lpm install.

Signing certificate

Every setup run downloads the current certificate, including a run without --force. The certificate request has a 10-second connection limit and a 30-second overall limit, including the response body.

LPM CLI accepts one complete DER X.509 certificate between 100 bytes and 64 KiB. Malformed, oversized, and trailing-data responses stop setup. This check validates certificate structure, not its expiry or certificate chain.

The certificate is security/trusted-root-certs/lpm.der under the SwiftPM user directory.

Matching valid bytes avoid a file replacement. Missing, malformed, or different bytes cause an atomic replacement. --force also replaces a matching certificate. A download or validation failure preserves the previous certificate and returns an error, with or without --force.

Signing trust

User-wide trust configuration is configuration/registries.json under the SwiftPM user directory.

LPM CLI sets strict default signing actions to error. It sets onUntrustedCertificate to silentAllow for the selected Registry hostname. It also removes the obsolete lpmdev scope signing override and preserves unrelated valid mappings and authentication configuration.

For HTTPS, trust starts with the authenticated connection that supplies the signing certificate. Loopback HTTP has no authenticated transport. See Swift signing trust.

The configuration file has a 16 MiB limit before parsing. An oversized file stops setup without replacement. Matching valid trust configuration avoids a rewrite. Concurrent LPM CLI updates preserve each other’s registry entries. If the CLI detects an external edit during setup, it stops without replacing that edit.

SwiftPM user directory

XDG_CONFIG_HOME must be an absolute path. On macOS, it does not replace the native Library directory. SwiftPM can create directory aliases under ~/.swiftpm. LPM CLI preserves these aliases. Project scope configuration remains at .swiftpm/configuration/registries.json inside the project.

JSON output

lpm swift-registry --json

Failed setup returns success: false with error and error_code. JSON mode suppresses SwiftPM terminal output.

Recovery

Flags

LPM_TOKEN and LPM_REGISTRY_URL provide token and Registry defaults. Explicit flags override these values. See Global flags.

See also

• Swift Package Registry — identities, signatures, and trust.
• Using LPM CLI with Swift — package installation and publication.
• lpm install — automatic setup for Swift dependencies.
• lpm publish — publish signed Swift packages.