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.

Rotate a locally stored token

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.

Complete an MFA-protected rotation

The registry requires MFA for some write-capable tokens.

For an interactive rotation, omit --otp:

lpm token-rotate

If the registry requires MFA, LPM CLI opens a masked prompt. Enter the six-digit authenticator code.

LPM CLI retries the rotation once. It does not print the code in terminal or JSON output.

If the command cannot use an interactive terminal, 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 the registry rejects the code, the command stops after that retry. 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.

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.

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, rotate 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

First, make sure that the active credential still works:

lpm whoami

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

lpm login
lpm whoami

JSON output

Use JSON output in an automation that checks the result:

lpm token-rotate --json

{
  "expires_at": null,
  "rotated": true,
  "storage_backend": "keychain",
  "storage_degraded": false,
  "success": true
}

The LPM.dev Registry currently returns no expiry during rotation. It keeps the existing expiry, so expires_at is null.

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. Both errors leave the stored token unchanged.

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