Authentication

Authentication in LPM CLI is registry-specific. LPM CLI first selects the registry that receives a request. Then it selects a credential for that registry.

Credentials for the LPM.dev Registry, npm, GitHub Packages, GitLab Packages, and custom registries remain separate. LPM CLI does not send a token to an unrelated registry.

How authentication works

Each authenticated request uses the same model:

1. A package name, publish target, or registry option selects the destination registry.
2. LPM CLI selects the first available credential for that registry.
3. LPM CLI sends the credential only to the selected registry.

This order matters because an environment variable can override a stored credential. A project file can also select a different registry.

Credential priority

LPM CLI uses the first available source in each row.

The gh and glab commands provide their tokens at request time. LPM CLI does not copy these tokens into its credential storage.

GitHub and GitLab login commands also recognize environment and stored credentials. They do not save an environment token unless you pass --save-env-token.

An install route from .npmrc uses the credential for the matching registry origin. This rule also applies to custom registries and package tarballs.

Choose a credential method

Use lpm login to check an available source or create a stored session or token. You do not need authentication to install public packages.

Sessions and tokens

A browser login to the LPM.dev Registry can store an access token and a refresh token. LPM CLI can refresh this session without another browser login.

lpm setup ci npmrc, lpm swift-registry, and automatic Swift setup use this refresh path before they copy a token to another client. A refresh failure stops the command.

Tokens from --token, LPM_TOKEN, CI, or older login flows do not refresh automatically. Third-party registry tokens also remain static until you replace them.

If the registry rejects LPM_TOKEN, replace it or unset it to use your saved login. LPM CLI preserves saved credentials and reports env_token_rejected in JSON output. See environment-token recovery for local and CI steps.

Use lpm token-rotate to rotate a stored LPM.dev Registry session. This command does not rotate npm, GitHub, GitLab, or custom registry tokens.

Project configuration and registry routing

Project configuration can select a registry, but it does not change the credential priority. Do not put registry tokens in lpm.json.

For example, this lpm.json selects a custom npm-compatible publish registry:

{
  "publish": {
    "registries": ["npm"],
    "npm": {
      "registry": "https://npm.example.com"
    }
  }
}

Store a token for that registry, then publish:

lpm login --login-registry https://npm.example.com --token <TOKEN>
lpm publish

The registry URL selects the stored credential. A token for registry.npmjs.org does not become a token for npm.example.com.

Use .npmrc for install routes and credentials for npm-compatible registries:

@acme:registry=https://npm.example.com/
//npm.example.com/:_authToken=${NPM_TOKEN}

Set the variable for the install process:

NPM_TOKEN=<TOKEN> lpm install

Keep environment-backed credentials in user or CI-owned configuration. Project .npmrc files must not expand environment secrets. Registry URLs cannot contain usernames or passwords. See private registry authentication for scoped Basic authentication and lockfile recovery.

On Unix, each .npmrc layer can supply credentials only if no group or other permission bits are set. Mode 0600 is recommended. Mode 0700 is also accepted because only the owner has access.

If a layer has group or other permissions, LPM CLI refuses _authToken, _auth, username, and _password from that layer. It still uses non-secret registry routes and TLS configuration from the same file. LPM CLI prints a security warning in terminal and JSON modes. A refused higher-priority credential does not replace a protected credential from a lower-priority layer.

Use this command to protect the file:

chmod 600 .npmrc

Secure credential storage

LPM CLI stores local credentials in the secure storage service for your operating system.

The service name is lpm-cli. LPM CLI separates stored credentials by registry.

If secure storage is unavailable, LPM CLI uses an encrypted file at ~/.lpm/.credentials. LPM CLI does not store tokens as plain text in this file.

A headless Linux upgrade preserves an existing encrypted-file login when its saved key can decrypt the credential store. For an older login, keep ~/.lpm/.credentials, ~/.lpm/.key, and ~/.lpm/.salt. A keyring outage does not authorize a stale file token or restore a revoked login.

The first recovery of an older file key uses its original derivation, which needs about 1 GiB of memory. On Unix, subsequent reads use an authenticated private cache at ~/.lpm/.key-derived. The original files remain compatible with the older CLI. Native keyring keys are not copied into this cache.

The encrypted fallback is valid, but it has less protection than the operating-system service. lpm doctor reports this fallback as degraded.

macOS shared credentials

Official signed releases of LPM CLI and LPM Vault use one restricted Keychain access group. Public source code does not grant access to that group. Unsigned builds and third-party builds cannot read its credentials.

An upgrade migrates each older credential when LPM CLI or LPM Vault first needs it. The migration checks the recorded credential identity before it copies the value. After the shared copy passes verification, the migration removes the old copy. Interrupted cleanup resumes on the next read.

After migration, older LPM CLI versions cannot read the shared login. Keep LPM CLI and LPM Vault current. If a credential fails verification, update both products and sign in again with lpm login.

LPM Vault cannot use the CLI encrypted-file fallback. A source build can use its own login or an environment token, but cannot share the official Keychain group.

macOS Keychain permission

LPM CLI first tries to read an authorized Keychain item without a prompt. During migration, macOS can request permission for the older item. LPM CLI prints guidance before the permission sheet.

Select Always Allow to keep later authorized reads silent. If you deny access, LPM CLI cannot use the stored credential for that request.

Common recipes

Use the LPM.dev Registry on your computer

Sign in through the browser, then inspect the active account:

lpm login
lpm whoami

Use npm in CI

Pass NPM_TOKEN to the package command. This method does not store the token:

NPM_TOKEN=<TOKEN> lpm install
NPM_TOKEN=<TOKEN> lpm publish --npm

Use an existing GitHub CLI session

Authenticate gh, then publish to GitHub Packages:

gh auth login --hostname github.com
lpm publish --github

LPM CLI reads the gh token for the request. The token remains under the control of GitHub CLI.

Use GitLab CI

GitLab CI provides CI_JOB_TOKEN to eligible jobs. LPM CLI selects it after GITLAB_TOKEN:

CI_JOB_TOKEN=<TOKEN> lpm publish --gitlab

The GitLab publish target also requires publish.gitlab.projectId in lpm.json. See the lpm publish targets.

Use a custom publish registry

Store the token for the exact publish registry:

lpm login --login-registry https://npm.example.com --token <TOKEN>
lpm publish --publish-registry https://npm.example.com

Interactive login can ask for the token with masked input. JSON mode and non-interactive shells require --token.

Logout and revocation

lpm logout clears only the stored LPM.dev Registry session:

lpm logout

Use --all to clear all credentials that LPM CLI stores:

lpm logout --all

These commands do not clear environment variables, .npmrc credentials, or gh and glab sessions. LPM CLI does not own those credential sources.

Add --revoke to revoke the LPM.dev Registry session and browser pairings. See the lpm logout reference for valid flag combinations.

Troubleshooting

You logged out but remain authenticated

A higher-priority credential can remain active after local logout. Inspect LPM_TOKEN, the registry-specific environment variables, .npmrc, and host CLI sessions.

For example, clear LPM_TOKEN from the current shell:

unset LPM_TOKEN
lpm logout

LPM CLI selects an unexpected token

Read the credential-priority table and remove the earlier source. For example, GITHUB_TOKEN overrides both gh and the stored GitHub fallback token.

LPM CLI selects gh or glab unexpectedly

Disable host CLI authentication for one command:

LPM_DISABLE_HOST_CLI_AUTH=1 lpm publish --github

If a stored fallback token is available, LPM CLI uses it. An environment token still has higher priority.

LPM CLI refuses an .npmrc credential on Unix

LPM CLI refuses .npmrc credential fields when group or other permission bits are set. Registry routes and TLS configuration from the same file remain active.

Restrict the file permissions:

chmod 600 .npmrc

Mode 0700 is also accepted, but 0600 is the recommended mode for a credential file.

The secure storage service is unavailable

Run lpm doctor to inspect the active storage service. If that service is unavailable, LPM CLI uses encrypted file storage.

Inspect authentication

These commands report the active account, available credential sources, or storage health:

lpm whoami
lpm whoami --json
lpm doctor
lpm setup ci npmrc --json

lpm whoami reports available third-party credentials. It does not send a request to each third-party registry to test every token.

lpm setup ci npmrc --json reports a redacted file shape. The live bearer appears only in the protected .npmrc file on disk.

See also

• lpm login, lpm logout, and lpm whoami - manage stored registry credentials
• lpm setup - write .npmrc authentication for local use or CI
• lpm token-rotate - rotate the LPM.dev Registry session token
• Registries - route packages to npm-compatible registries
• Environment variables - use temporary credentials and registry overrides