Where a value lives
A value's address is workspace, project, environment and key name. The schema header names the first two.
acme / api-gateway / production / DATABASE_URLWe address your value as {org}/{project}/{environment}, with the key name under it.
Address parts
| Part | What it is | Set by | Purpose |
|---|---|---|---|
Workspace (org) | A company or team | The @penv= header | Billing and membership boundary |
| Project | One app or service | The @penv= header | Groups the environments one app ships to |
| Environment | development, staging, production, or any name you make in the console or with penv env new | --env, PENV_ENV, the @currentEnv key, or development (precedence) | Selects which copy of a value is read; a machine credential is bound to one |
| Key | The name the code reads | The .env.schema line |
The @penv= header
# @penv=acme/api-gateway
# @penv=penv:acme/api-gateway # the same, provider namedThe header sits in the first comment block and names <org>/<project>, optionally behind a provider prefix; penv (Penv Cloud) is the default. With no header, your schema is in local mode.
The nearest .env.schema above the working directory wins, so your monorepo holds one schema per app.
penv push on a schema with no header prints its plan, asks us to create the project from the directory name, and writes the slug we return into the header.
Slugs
You type a display name in the console, and we derive the slug the header holds. penv never guesses a slug from a name.
We refuse an address that matches more than one thing with ambiguous rather than resolved to one. Rename the duplicate in the console, then run the command again.
Key paths
A key carries a path beside its name, usually empty. The console joins them: redis/password is password under the path redis.
penv push writes every key with an empty path, so schema names equal cloud names. You assign a path in the console.
Next: environments and precedence.
How penv works
penv validates every value against your committed schema file, then starts your program with those values in its environment.
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.