lpm token-rotate

Use lpm token-rotate after token exposure or during planned credential maintenance.

lpm token-rotate [--otp <CODE>] [--registry <URL>] [--json]

The command rotates the active token for the LPM.dev Registry or another LPM-compatible registry.

Quickstart

Sign in, rotate the token, and make sure that the new token works:

lpm login
lpm token-rotate
lpm whoami

Use this workflow when LPM CLI manages the registry credential on your computer.

LPM CLI keeps that credential with the LPM home: ~/.lpm, or the directory that LPM_HOME names. With LPM_HOME set, the command rotates the login made with the same LPM_HOME.

The command has one mode: rotate the locally stored token for the selected registry. It has no dry run or confirmation prompt.

There is no lpm.json field for rotation. Use command flags to select the registry and supply an MFA code.

Examples

lpm token-rotate                                      # rotate the saved registry token
lpm token-rotate --otp 123456 --json                   # rotate without an interactive prompt
lpm token-rotate --registry https://registry.example.com

Rotate a locally stored token

A stored browser session or legacy access token supplies the credential. The command replaces only the active access token.

A browser session keeps its refresh credential. LPM CLI preserves the precise access-token expiry so later commands can refresh the session when needed.

Complete an MFA-protected rotation

If your account has a passkey or an authenticator app, rotating a token that can publish or write to the remote cache needs it. An organization that requires 2FA asks for it to rotate any of its tokens.

For an interactive rotation, omit --otp:

lpm token-rotate

How LPM CLI asks depends on what your account has:

Without a terminal, LPM CLI still prints the approval URL and waits for it. An authenticator-only account passes --otp instead.

LPM CLI retries the MFA challenge once with your code. It does not print the code in terminal or JSON output.

--json disables the MFA prompt and the browser approval, even in an interactive terminal. If a prompt is unavailable, pass a fresh code with --otp:

lpm token-rotate --otp 123456 --json

LPM CLI rejects a code before the request unless the code contains exactly six ASCII digits.

Use the masked prompt for manual rotations. A command-line code can appear in shell history or process information.

If you supply --otp, LPM CLI uses that code on the first request. It does not open another prompt after rejection. An account whose only second factor is a passkey can't use --otp.

If the registry rejects the code, run the command again with a fresh code.

When to use it

This command does not rotate npm, GitHub, or GitLab tokens.

What the command changes

The registry creates a new value for the current token record. The token keeps its owner, organization, access scope, and expiry.

The registry returns the unchanged expiry timestamp. A non-expiring legacy token returns an explicit null expiry.

After a successful rotation:

• The old token value becomes invalid.
• LPM CLI stores the replacement in local secure storage.
• The replacement token does not appear in terminal or JSON output.

The LPM.dev Registry can process five rotation requests per minute for one token record. Across the tokens of one account, personal or organization, it can process 20 per minute.

In rare cases, an edge cache can accept the old value for up to 60 seconds after rotation.

Rotate a token for another registry

Use the same registry URL for login, rotation, and verification:

lpm login --registry https://registry.example.com
lpm token-rotate --registry https://registry.example.com
lpm whoami --registry https://registry.example.com

The registry must support the LPM-compatible token rotation endpoint.

External tokens are rejected

lpm token-rotate accepts only a token from local secure storage.

The command rejects LPM_TOKEN, --token, and CI-issued tokens before it sends a registry request. It does not change local credentials.

LPM CLI cannot update an environment variable or an external secret store. It also does not print the replacement token.

If LPM_TOKEN overrides a stored token, remove it before you run the command:

unset LPM_TOKEN
lpm token-rotate

For CI, replace the token in the LPM.dev Registry dashboard. Then update LPM_TOKEN in the CI secret store.

Rotate other registry credentials

Use the token controls of each registry to revoke the old value and create a replacement.

Recover from a failed rotation

The server can commit a rotation before a network error or local storage error reaches you. An error does not prove that rotation failed remotely.

LPM CLI does not automatically repeat a rotation after a network error or server error. An ordinary authentication rejection can trigger one session refresh and retry.

An MFA challenge does not trigger a refresh. A refresh before another error can still change the local session.

If another command logs in or logs out while rotation is in flight, LPM CLI preserves that newer local state. The rotation command reports an error.

First, make sure that the active credential still works:

lpm whoami

If authentication fails, sign in again and inspect the new session:

lpm login
lpm whoami

If encrypted file fallback remains active, repair or unlock the OS keychain. Then create a new browser session:

lpm logout
lpm login

Rotation keeps the existing refresh credential, so rotation alone does not move that credential into the keychain.

JSON output

Use JSON output in an automation that checks the result:

lpm token-rotate --json

{
  "expires_at": "2032-01-03T04:05:06Z",
  "rotated": true,
  "storage_backend": "keychain",
  "storage_degraded": false,
  "success": true
}

A missing or malformed expiry field is an invalid registry response. LPM CLI does not report successful local storage for that response.

If secure storage or expiry metadata cannot be saved, the command returns an error. A replacement already saved locally remains available for recovery.

If an external token is active, the command returns unsupported_auth_source:

{
  "schema_version": 1,
  "success": false,
  "error_code": "unsupported_auth_source",
  "error": {
    "code": "UNSUPPORTED_AUTH_SOURCE",
    "message": "unsupported authentication source for `lpm token-rotate`: LPM_TOKEN",
    "command": "lpm token-rotate",
    "source": "LPM_TOKEN"
  }
}

If MFA is required without an interactive prompt, the command returns otp_required:

{
  "schema_version": 1,
  "success": false,
  "error_code": "otp_required",
  "error": {
    "code": "OTP_REQUIRED",
    "message": "one-time password required for `lpm token-rotate`",
    "command": "lpm token-rotate"
  }
}

An invalid or expired code returns otp_invalid. An account with a passkey gets browser_approval_required, because --json doesn't wait for an approval: run the command without --json. No MFA error rotates the token, but an earlier session refresh can change local credentials.

Flags

The command supports one command-specific flag. The relevant global flags are also listed.

See also

• lpm login / logout / whoami - manage and verify registry sessions
• lpm setup - create local project or CI authentication
• Authentication - understand credential sources and storage backends
• Environment variables - use registry credentials in automation