lpm setup

Use lpm setup to configure registry access or create a starting workflow for CI secrets.

lpm setup ci npmrc [-r <URL>] [--oidc]
lpm setup ci github-actions [--env <NAME>]
lpm setup ci gitlab [--env <NAME>]
lpm setup local [-d <DAYS>]

Choose a command for the client or workflow that needs authentication:

lpm setup ci npmrc                     # create .npmrc for npm, pnpm, or Yarn in CI
lpm setup local                        # create a local read-only project token
lpm setup ci github-actions            # print a GitHub Actions OIDC workflow fragment
lpm setup ci gitlab                    # print a GitLab CI OIDC workflow fragment

Choose a setup mode

If CI uses only LPM CLI, set LPM_TOKEN on the package command. LPM CLI does not need a generated .npmrc file.

- name: Install private packages
  run: lpm ci
  env:
    LPM_TOKEN: ${{ secrets.LPM_TOKEN }}

Project configuration in lpm.json

The GitHub Actions and GitLab targets prepare OIDC workflows for lpm env pull.

These workflows use the vault field in lpm.json. The generated deploy step also runs the deploy script from this file.

{
  "vault": "7f3a1e2c-5b9d-4a8f-b6c1-9b1d2e3f4a5b",
  "scripts": {
    "deploy": "./deploy.sh"
  }
}

Create the local secret project before you generate the workflow:

lpm env set API_URL=https://api.example.com
lpm env push
lpm setup ci github-actions --env production

The lpm env commands create the vault field. Commit lpm.json after this field exists.

The GitHub Actions target copies the vault ID into the printed LPM_VAULT_ID value. If the field is missing, it prints <your-vault-id>.

The GitLab job can read the vault ID from the checked-out lpm.json file. The setup command does not change lpm.json.

lpm setup ci npmrc and lpm setup local do not use lpm.json.

Create .npmrc for CI

If an npm-compatible client needs LPM.dev Registry authentication, run this command:

- name: Configure LPM.dev Registry access
  run: lpm setup ci npmrc
  env:
    LPM_TOKEN: ${{ secrets.LPM_TOKEN }}
- run: npm ci

The command writes this scoped block to .npmrc in the current directory:

# LPM Registry (generated by lpm setup ci npmrc)
//lpm.dev/:_authToken=<resolved-token>
@lpm.dev:registry=https://lpm.dev/api/registry/
# End LPM Registry

Only @lpm.dev/* packages use this route. Existing default registries and unrelated .npmrc lines stay unchanged.

The command replaces its previous generated block. On Unix, LPM CLI sets the file permissions to 0600.

CAUTION: Do not commit this .npmrc file. The file contains a literal bearer token.

This command does not add .npmrc to .gitignore. CI runners usually remove the workspace after the job.

Choose the CI credential

Without --oidc, the command uses one of these credentials:

1. The global --token <TOKEN> flag
2. LPM_TOKEN
3. A valid token from lpm login

If neither credential is available, the command stops before it changes .npmrc.

LPM CLI refreshes an expired browser session before it writes .npmrc. If the refresh fails, the command stops and keeps .npmrc unchanged.

Use --oidc to require a CI identity exchange:

lpm setup ci npmrc --oidc

GitHub Actions needs permissions: id-token: write. GitLab.com CI needs LPM_OIDC_TOKEN with the https://lpm.dev audience.

An OIDC error stops the command. It does not use LPM_TOKEN or a saved login as a fallback.

Use --registry with another LPM-compatible registry:

lpm setup ci npmrc --registry https://registry.example.com

A stored session applies only to that exact registry URL. The command appends /api/registry/ to the base URL in the generated scope route.

JSON output

If automation needs the file path and credential source, use JSON output:

lpm setup ci npmrc --json

The command still writes .npmrc. The JSON response replaces the token with <redacted>.

Create a local project token

If a local npm-compatible client needs a read-only project token, run these commands:

lpm login
lpm setup local
npm install

The LPM.dev Registry requires a valid browser-backed CLI session. The default token lifetime is 30 days.

Set a lifetime from 1 through 90 days:

lpm setup local --days 7
lpm setup local --days 90

The command changes two project files:

• .npmrc receives a scoped, read-only token for @lpm.dev/* packages.
• .gitignore receives one .npmrc entry.

Existing .npmrc lines stay unchanged. A custom default registry also stays unchanged.

CAUTION: The .npmrc file contains a token. Keep the file outside version control.

Run lpm setup local again before the token expires. The command replaces the previous project token instead of creating active duplicates.

JSON output reports the paths, scope, and expiry. It does not include the token.

lpm setup local --json

Print a GitHub Actions workflow

Print the workflow fragment for the production secret environment:

lpm setup ci github-actions

Select another environment with --env:

lpm setup ci github-actions --env staging

The command prints three items:

1. A complete GitHub Actions job fragment for lpm env pull --oidc
2. An lpm env oidc allow command for the repository
3. An instruction to configure the returned policy ID as LPM_OIDC_POLICY_ID

The command prints output only. It does not create or change a workflow file.

Run the printed authorization command from a logged-in development machine. Then add the workflow fragment to .github/workflows/deploy.yml.

The authorization command also uploads protected material for the personal env project. Continue only when LPM CLI reports that CI escrow is enabled.

If the escrow upload fails, correct the error and run the same authorization command again. The command updates the matching policy.

When you run the authorization command, LPM CLI gets the immutable repository ID from GitHub. Private repositories need GITHUB_TOKEN, GH_TOKEN, or --repository-id.

The job fragment uses ubuntu-latest and includes all required job keys.

If your deployment needs another runner, change runs-on after you add the fragment.

The job needs id-token: write permission. It uses the vault ID from lpm.json as LPM_VAULT_ID.

The fragment reads LPM_OIDC_POLICY_ID from the GitHub vars context. Create it as a repository variable before the first pull. To use an environment variable instead, add environment: <name> to the job.

The aliases github and gha select the same target.

Print a GitLab CI workflow

Print the GitLab.com CI fragment:

lpm setup ci gitlab
lpm setup ci gitlab --env staging

The command prints three items:

1. A GitLab CI job fragment with an LPM_OIDC_TOKEN identity token
2. An lpm env oidc allow command for the numeric project ID
3. An instruction to configure the returned policy ID as LPM_OIDC_POLICY_ID

The identity token uses the https://lpm.dev audience. The checked-out lpm.json file supplies the vault ID.

The command prints output only. It does not create or change .gitlab-ci.yml.

Run the printed authorization command from a logged-in development machine. Then add the job fragment to .gitlab-ci.yml.

The authorization command also uploads protected material for the personal env project. Continue only when LPM CLI reports that CI escrow is enabled.

Create LPM_OIDC_POLICY_ID as a GitLab CI/CD variable before the first pull. Mark it protected only when every branch or tag allowed by the OIDC policy is protected.

The alias gitlab-ci selects the same target. Self-managed GitLab issuers are not supported for this workflow.

Recover an interrupted setup

If lpm setup local reports an interrupted token replacement, run the same command again. Use the same registry URL.

lpm setup local --registry https://registry.example.com

If you want to switch to CI setup, finish the pending local replacement first. Then run lpm setup ci npmrc.

If a generated local block belongs to another registry, use that registry URL for recovery. LPM CLI does not move the token between registries.

Flags

Use only the flags listed for the selected target. The npmrc target rejects --env. The GitHub Actions and GitLab targets reject --registry and --oidc. The aliases use the same rules.

An invalid flag stops the command before it writes a file or prints a workflow fragment.

--json returns structured output for npmrc and local. The GitHub Actions and GitLab targets always print human-readable fragments.

See also

• Authentication - learn how LPM CLI selects credentials
• lpm login, logout, and whoami - manage registry sessions
• lpm env - manage project secrets and OIDC policies
• CI/CD setup - configure complete CI jobs
• Environment variables - use LPM_TOKEN, LPM_OIDC_TOKEN, and LPM_VAULT_ID