Where a value lives
Four parts say where a value lives, and the header at the top of your schema names two of them.
Four things say where a value lives: the workspace it belongs to, the project inside it, the environment inside that, and the key's own name.
The four parts
acme / api-gateway / production / DATABASE_URLWritten as one string, the first three are the address: {org}/{project}/{environment}. The key name sits under it.
| Part | What it is | Where it comes from |
|---|---|---|
Workspace (org) | Your company or team | The @penv= header |
| Project | One app or service | The @penv= header |
| Environment | development, staging, production, or any name you make | --env, PENV_ENV, or development |
| Key | The name your code reads | The .env.schema line |
The header names the first two
# @penv=acme/api-gateway @schema=1That comment block is the first thing in the file. @penv=<org>/<project> names the cloud project. A schema with no @penv= header is in local mode and reads .env from disk.
The nearest .env.schema above your working directory wins, so a monorepo holds one file per app and each app names its own project.
Names become slugs on the server
You type a display name in the console. The server derives the slug from it, and that slug is what the header holds. penv never guesses a slug from a name it was handed.
When an address could mean more than one thing, the server refuses it with ambiguous instead of picking one. Rename the duplicate in the console, then run the command again.
penv push on a schema with no header prints what it is about to do, then creates the project from the directory name and writes the slug the server returned back into the header.
Keys can sit under a path
A key carries a path beside its name. Most keys have an empty path and read as a plain name. The console shows the two joined, so redis/password is the key password under the path redis.
penv push writes every key with an empty path, so the names in your schema are the names in the cloud. A path is something you give a key in the console.
What each part is for
The workspace is the billing and membership boundary. The project groups the environments one app ships to. The environment is what decides which copy of a value you get, and it is also what a machine credential is bound to.