Conceptsince 1.0.0-alpha.3
Glossary
Every word penv and its docs use, with the plain phrase first and the precise term beside it.
Read the left column out loud to a colleague. Read the middle column to a security questionnaire. The rows are ordered by the term in the middle.
The words
| Say this | The term | What it means |
|---|---|---|
| What gets mixed into the seal so a value only opens where it belongs | AAD | The extra data bound into an encrypted value. penv uses the value's full address |
| Encrypted, each value under its own key | AES-256-GCM | The cipher every stored value is sealed with |
| Where a value lives | address | {org}/{project}/{environment}, plus the key's own name |
| A run your coding agent is driving | agent session | A session penv detected as an agent, which turns on masking and JSON output |
| A person's yes before a value prints | approval | The request penv reveal creates under an agent, answered in the console within 10 minutes |
| The record of who did what | audit log | The append-only list of every action in your workspace |
| How long we keep the record of who did what | audit log retention | 7 days on Free, 90 on Pro, contractual on Enterprise |
| A key the server can check a signature against | bound keypair | How a plain server proves who it is when it can prove nothing else |
| A key name your build tool copies into the browser | bundler prefix | NEXT_PUBLIC_, VITE_, PUBLIC_, EXPO_PUBLIC_, NUXT_PUBLIC_ or REACT_APP_. penv treats such a key as public |
| Your own encryption key | BYOK | An Enterprise workspace pointing penv at a key it owns in AWS, Google, Azure or Vault |
| The encrypted copy on your laptop | cache | What makes a warm penv run start in milliseconds. Fresh for 60 seconds in development |
| What penv promises, in its own words | claim | The sentence penv guard --check prints. It differs between local mode and cloud mode |
| The cloud holds the values | cloud mode | Your schema names a project and you hold a credential |
| What proves who you are | credential | pcu_ for a person, pck_ for a machine |
| A line above a key that says something about it | decorator | @type=url, @rotate=90d and the rest of the vocabulary |
| Signing in by approving a code in your browser | device-code login | What penv login does. No password reaches the command line |
| Signed data agreement | DPA | The data processing agreement your legal team asks for |
A key in your .env that your schema never heard of | drift | What penv check reports so the two files stay in step |
| Short-lived values | dynamic parameter | A key with no stored value, minted on request and given a lease |
| The marker that says the cloud mints this one | @dynamicFrom | The schema decorator naming the engine behind a short-lived value |
| The shared vocabulary the schema is written in | @env-spec | varlock's decorator specification, which penv follows word for word |
| Encrypted, each value under its own key | envelope encryption | A fresh key per value, itself encrypted by your workspace's key |
| Which copy of a value you get | environment | development, staging, production, or any name you make in the console |
| The keys and settings your app needs | environment variables | The names your code already reads, such as DATABASE_URL |
| The tag that says whether anything changed | ETag | What penv run sends so an unchanged environment costs one small request |
| The number a command leaves behind | exit code | 0 ok, 1 error, 2 auth, 3 validation, 4 confirmation required, 5 no credential, 6 environment refused |
| A counter that catches a copied key | generation counter | Advanced on every bound-keypair login, so a clone locks out both machines |
The rules that keep your agent out of .env | guard | What penv guard writes into each harness's own config |
| The tool your coding agent runs inside | harness | Claude Code, Codex, Cursor, Amp, Copilot CLI, Gemini, Cline or Windsurf |
| The thing a harness calls before it does something | hook | penv hook claude-code and its siblings. The hook is the penv binary itself |
| Where your workspace's master key is held | KMS | The key management service that wraps every per-value key |
| The typed file penv writes for your language | language target | A folder holding a template and a target.toml. ts and py ship built in |
| How long a minted credential lasts | lease | The expiry attached to a short-lived value, recorded without the credential itself |
| Values in a file on your disk | local mode | No @penv= header, or no credential yet. development is the only environment |
| Your CI or server logs in like a person does | machine identity | An identity bound to one project and environment, holding a role, taking no seat |
| The list of every command penv has | manifest | What penv help --json prints. The docs, the completions and the agent skill all read it |
| Values scrubbed out of your program's output | masking | On by default under an agent. Covers base64, hex, percent-encoded and JSON-escaped forms |
| No stored key to steal | OIDC token exchange | Your pipeline's own signed token traded for a 15 minute penv credential |
| The one-time secret that binds a server | pce_ | What penv machine enroll takes. It can never be used as a credential |
| A machine's credential | pck_ | Issued in the console, or minted by an exchange with 15 minutes on it |
| A person's credential | pcu_ | Left in your keychain by penv login, good for 30 days from last use |
| The environment to read | PENV_ENV | Read when --env says nothing |
| The machine credential a pipeline hands penv | PENV_TOKEN | Takes precedence over the keychain |
| Person, or the machine | principal | Whoever a request is acting as. The audit entry calls it the actor |
| One app or service | project | The middle part of an address, named by the @penv= header |
| Which environment reads a value, and who may write it | role | Granted in the console at workspace, project or environment level |
| Replacing a value on a schedule | rotation | @rotate=90d in the schema, and the set-new-version form in the console |
| Sign in with your company login | SAML | The protocol behind that sign-in |
| The one file you commit | schema | .env.schema. Key names, types, and what a good value looks like |
| Your identity provider adds and removes people for you | SCIM | The directory sync that provisions and deprovisions members |
| Only what that job needs | scope | The project and environment a credential or a role is limited to |
| One safe place for the keys and settings your apps need | secret store | What penv.cloud is |
| A value penv hides in output | sensitive | Inferred true unless the key is bundler-prefixed or marked @sensitive=false |
| Which run of your agent asked | session id | Stamped on every cloud request and onto the audit entry |
| Uptime promise | SLA | The availability commitment in an Enterprise contract |
| Sign in with your company login | SSO | Single sign-on through your own identity provider |
| Confirm it is you | step-up | The second check the console asks for before a sensitive action |
| Workspace | tenant | Your company or team. The billing and membership boundary |
| The rule that says a token is a given machine | trust | An issuer, an audience and one exact subject. It holds no secret |
| Your CI or server logs in like a person does | workload identity | The same idea as a machine identity, in other vendors' words |
Words you may meet that penv no longer uses
The command line was rewritten in Rust for 1.0 and these went with the old one. They appear in older posts and in other tools.
| The old word | What replaced it |
|---|---|
penv.config.ts, defineConfig | Nothing. There is no config file, only .env.schema |
| provider, filesystem provider | Nothing. penv reads .env in local mode and the cloud in cloud mode |
the four-scope cascade, .local files | One environment per run, chosen by --env, PENV_ENV or the default |
.enc files, the local envelope, PENV_KEY_* | Values live in the cloud, and the local copy is sealed with a key in your keychain |
$PENV_HOME, .penv/state | .penv/targets for remembered answers, and the platform cache directory |
penv doctor | penv check |
penv rotate | penv set, plus @rotate in the schema |
PENV_DELIVERY, PENV_CLOUD_TOKEN | PENV_TOKEN |
| materialize a parameter | write a .env with penv pull |
Next: back to how penv works.