Environments and which one you get

penv takes the first environment name it finds, and the server decides whether you may read that one.

Three things can name the environment a command reads, and penv takes the first one it finds.

The order

--env production on the command line.

PENV_ENV in the environment penv itself was started with.

development, when neither of the first two says anything.

There is no fourth source. A value cannot cascade in from a second file, because there is only one file.

penv run --env staging -- pnpm start   # staging
PENV_ENV=staging penv run -- pnpm start   # staging
penv run -- pnpm start                 # development

penv run also sets PENV_ENV in the child process to the environment it read, so your program can see which one it got.

Local mode has one environment

Before you push, the values live in .env on your machine and development is the only name that resolves. Any other name is refused:

penv: staging is not a local environment.
      Local mode runs development from .env; every other environment lives in the cloud.

That refusal is exit code 6.

In the cloud, the server decides

Environment names are free-form. You make staging or any other name in the console, and the schema does not list them.

Reading one is a permission question. A person holds a role scoped to the whole workspace, or narrowed to one project or one environment, granted on the project's Access page in the console. Asking for an environment you hold no role on answers exit code 6:

penv: this identity may not read acme/api-gateway/production.
      Ask the console for a role on that environment, or pick another with --env.

Being able to read development says nothing about production. Someone has to grant you a role on the production environment in the console before penv run --env production works.

A machine reads one environment and no other

A machine credential is bound to a single project and environment when it is created. A request naming any other environment is refused by the server, so a CI job wired to staging cannot read production even if someone changes the flag in the pipeline. How a machine logs in covers how that binding is made.

Why development behaves differently

development is the one environment penv will answer from a stale local cache when the network is down. Every other environment is revalidated against the server on every run, and a run that cannot reach the server fails rather than serving you yesterday's production values. Local mode and cloud mode has the timings.

Next: the schema and your types.