lpm swift-registry command reference

Configure Swift Package Manager to use LPM.dev Registry as a SE-0292 package registry.

lpm swift-registry              # repair or explicitly rerun setup
lpm swift-registry --force      # repair stale/corrupt state or refresh the certificate

Most users do not need to run this command before installing a package. lpm install automatically configures Swift Package Manager (SPM) when it adds a Swift package from LPM.dev Registry.

Use lpm swift-registry when setup needs to be repaired or rerun explicitly. Use --force after a documented certificate rotation or when Registry configuration or the local certificate may be stale or corrupt. Sign in with lpm login before resolving a Swift package; LPM.dev Registry requires authentication for every Swift package request.

Normal install flow

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

On the first install, LPM CLI sets the lpmdev Registry scope and installs the signing certificate. It also configures signing trust, updates Package.swift, and resolves the dependency.

During each HTTPS setup pass, LPM CLI signs in to SPM with the current Registry session. It does this even when the Registry scope already matches.

LPM CLI accepts the global --token <TOKEN> flag for explicit setup and automatic setup during install. It can also refresh an expired browser session before it calls SPM.

What it does

Four setup steps. Scope, SPM login, certificate, and signing-trust failures abort an explicit run. A failed session refresh also aborts the command:

Set the registry for the lpmdev scope. Runs swift package-registry set --scope lpmdev <registry-url>/api/swift-registry. Adds --allow-insecure-http only for http:// registry URLs (local dev); the hosted LPM.dev Registry endpoint is HTTPS-only.
Log in. Resolves the LPM.dev Registry bearer token through the standard LPM CLI session. It writes the token to a temporary file and calls swift package-registry login --token-file <path> --no-confirm. On Unix, the file mode is 0600. LPM CLI removes the file after SPM exits, so the bearer does not appear in process arguments. This step runs only for HTTPS because SPM refuses to send authentication over HTTP. If no token is found, this step warns and is skipped. Setup can finish, but every Swift package request returns 401 until you run lpm login.
Install and verify the signing certificate. Downloads the CMS signing cert from <registry-url>/api/swift-registry/certificate with a bounded response reader, parses exactly one complete DER X.509 object, and compares its bytes with ~/.swiftpm/security/trusted-root-certs/lpm.der. Missing, malformed, trailing-data, stale, or mismatched local bytes are atomically repaired; malformed or oversized Registry responses abort.
Configure the SPM signing trust policy. Writes ~/.swiftpm/configuration/registries.json with a default signing.onUnsigned = "warn" + signing.onUntrustedCertificate = "warn" policy and a scope-specific override pinning lpmdev to signing.onUntrustedCertificate = "silentAllow". See Trust model for the rationale.

The configuration operation is idempotent. LPM CLI retains matching scope, certificate, and trust configuration without a rewrite. It repairs stale or partial configuration with atomic file writes.

Automatic setup skips SPM login when no credential exists. If a credential exists, a refresh or login failure stops the install. A rejected refresh-backed bearer causes one session refresh and one login retry.

The existing ~/.swiftpm/configuration/registries.json file has a 16 MiB limit enforced before JSON parsing. Missing retains the setup command's normal create behavior; an oversized file fails with its path and byte limit instead of being treated as absent or overwritten. See local configuration size limits.

`--force`

lpm swift-registry --force

Re-runs setup and re-downloads the signing certificate even when a valid one is on disk. Use it to repair stale or corrupt Registry configuration, or after a documented certificate rotation. A failed --force re-download is fatal even if a stale cert is still on disk — silently keeping the stale cert would defeat the explicit rotation the user asked for.

JSON output

lpm swift-registry --json

Emits a structured envelope describing what was configured:

Field	Meaning
`registry_url`	The `<base>/api/swift-registry` URL the `lpmdev` scope now points at
`scope`	Always `"lpmdev"` today
`https`	`true` when the registry URL is HTTPS; `false` for local-dev `http://`
`signing_certificate_installed` / `signing_certificate_outcome`	`"installed"` (new write) or `"already_installed"` (idempotent no-op)
`signing_trust_configured` / `signing_trust_outcome`	`"configured"` or `"already_configured"`
`trust_anchor`	Always `"https"` — the trust anchor is the HTTPS connection to LPM.dev Registry, not a cert chain
`signer_trust_policy`	Always `"silentAllow"` — see Trust model

Flags

Flag	Effect
`--force`	Re-download the signing certificate even when a valid one is on disk

Plus the global flags — --json is documented above; --registry <URL> redirects the configured base URL.

Prerequisites

swift on PATH (steps 1 and 2 spawn it). Without Swift installed, lpm swift-registry errors with Is Swift installed? and exits.
An LPM CLI session (lpm login). LPM.dev Registry requires a valid token for all Swift package resolution, including packages that would otherwise be public.

lpm swift-registry