Environments and precedence
penv reads the environment named by --env, then PENV_ENV, then the @currentEnv key, then development. We decide whether your identity may read it.
Environment precedence
| Order | Source | Example |
|---|---|---|
| 1 | --env flag | penv run --env production -- pnpm start |
| 2 | PENV_ENV in the environment penv was started with | PENV_ENV=staging penv run -- pnpm start |
| 3 | The key @currentEnv names: the process, then .env and .env.local, then its default | # @currentEnv=$APP_ENV |
| 4 | Default | development |
The first source that names an environment wins.
penv run --env staging -- pnpm start # staging
PENV_ENV=staging penv run -- pnpm start # staging
penv run -- pnpm start # @currentEnv, else developmentpenv run sets PENV_ENV in the child process to the environment it read.
Local mode
In local mode, penv runs any environment your value files describe, and warns naming the files it used when .env.<env> is missing.
Cloud mode
You create environments in the console or with penv env new, not in the schema. Reading one requires a role scoped to your workspace, the project, or that environment, granted on the project's Access page. We refuse an environment your identity holds no role on with environment_refused, exit 6:
{ "error": "environment_refused",
"message": "your account has no access to acme/api-gateway/production.",
"fix": "Ask an admin to give you a role on that environment in the console, or pick another with --env <name>." }A role on development grants nothing on production.
Machine credentials
A machine credential is bound to one project and environment at creation. We refuse a request naming any other environment, so your CI job bound to staging cannot read production even if the pipeline's --env changes. See machine identity.
Development cache
| Environment | Network down |
|---|---|
development | Served from the local cache |
| Every other name | Fails; penv revalidates with us on every run |
Timings: local and cloud modes.
Next: schema and types.