Per-Environment Scoping

A project vault can hold independent value sets for default, staging, production, or another valid environment name.

lpm env set --env=staging DATABASE_URL=postgres://staging.db/app
lpm env set --env=production DATABASE_URL=postgres://production.db/app

lpm env list --env=staging
lpm env list --env=production

Without --env, local vault commands use the default environment.

Select an Environment for Execution

Use --env when running a script or development server:

lpm run --env=staging dev
lpm run --env=production build
lpm dev --env=staging

An explicit flag has the highest priority. Without it, LPM CLI can select an environment from the lpm.json > env mapping for the script name:

{
  "env": {
    "dev": ".env.development",
    "staging": ".env.staging",
    "prod": ".env.production"
  }
}

For example, lpm run dev selects the canonical development environment. LPM CLI does not use an LPM_ENV environment variable as an implicit selector.

Environment Inheritance

For shared dotenv values, define named environments under lpm.json > environments:

{
  "environments": {
    "base": ".env",
    "staging": {
      "extends": "base",
      "file": ".env.staging"
    },
    "production": {
      "extends": "base",
      "file": ".env.production"
    }
  }
}

Parent files load first and child files override them. Circular inheritance and missing parents are rejected.

The LPM CLI lpm.json reference covers aliases, inheritance, and valid environment names.

How Values Are Resolved

For an executed environment, LPM CLI resolves values in this order:

Dotenv files, including a configured inheritance chain.
Vault secrets, which override dotenv values.
Defaults and validation from envSchema.

When a selected named environment contains vault secrets, its vault map is used without per-key fallback to the default vault map. If the selected environment has no vault secrets at all, LPM CLI falls back to the default vault values.

This means that adding the first staging-only secret changes staging from complete default-vault fallback to its own independent vault map. Copy the shared values explicitly when staging should begin from the default set.

Copy Values

lpm env copy default staging
lpm env copy staging production
lpm env copy staging production --overwrite

Copy writes every source key that is missing from the destination. Existing destination keys are skipped unless --overwrite is supplied. The command does not rename or prefix keys.

Compare Environments

lpm env diff
lpm env diff staging
lpm env diff staging production

Command	Comparison
`lpm env diff`	Local default environment against cloud default
`lpm env diff staging`	Local staging against cloud staging
`lpm env diff staging production`	Two local environments

Diff output reports key names as added, removed, changed, or unchanged. It never prints the compared values.

Cloud comparisons require access to a synced personal Pro vault. Comparing two local environments does not.

Validate All Environments

lpm env check

lpm env check discovers environments from lpm.json and the local vault, resolves each one, and validates all of them against envSchema. It does not accept --env; use the complete result to keep the project contract consistent.

Cloud Sync Uses the Complete Vault

lpm env push
lpm env pull

Cloud sync does not upload or download one named environment at a time. A push encrypts every non-empty environment into one project payload. A personal pull replaces the local vault with the complete remote environment map.

OIDC CI pulls are different: an authorized policy selects one environment to return to the verified workflow. See OIDC for CI.