The .env.schema format

# @penv=acme/api-gateway
# @currentEnv=$APP_ENV

# @type=enum(development,staging,production)
APP_ENV=development

# @type=url
DATABASE_URL=

# @type=string(startsWith=sk_) @rotate=90d @hosts(api.stripe.com)
STRIPE_SECRET_KEY=

# @type=url @sensitive=false
NEXT_PUBLIC_APP_URL=http://localhost:3000

The grammar is @env-spec; upstream meanings: root decorators, item decorators. This page lists what penv 1.0.0-rc.1 adds, restricts or infers. Concept: schema and types.

penv reads the nearest .env.schema upward from your working directory, so a monorepo holds one per app. A # --- line ends a block.

Decorators

penv ignores anything else with a warning, so a varlock schema still parses: varlock_only for @plugin and for other values of @required, @optional or @sensitive; unknown_decorator for the rest. penv has no @scope: read access is a role in the console.

The header is the first comment block; a block on a key is still the header when it carries a header decorator, and that key gets no decorators.

@penv

@penv takes an optional provider, then org/project with no second /; anything else is invalid_header. No @penv means local mode.

@hosts

Under an agent, or with penv run --sealed, penv run hands the command a placeholder and puts the value into requests to the @hosts hosts only. A type with no room for a placeholder is cannot_seal (errors).

@hosts may be computed:

# @hosts=url($DATABASE_URL, host)
DATABASE_URL=

[hosts]
DATABASE_URL = ["db.internal.test"]

penv check and a sealed run refuse a key whose hosts differ from its pin; penv check --pin-hosts writes the pins. penv push sends a computed @hosts to penv.cloud as hostsExpr, the expression as written. We store and show it and enforce nothing; sealed runs and [hosts] pins enforce it on your machine. Config.

@assert

# @assert(not(eq($PORT, $ADMIN_PORT)), "PORT and ADMIN_PORT collide")

A false expression fails penv check and penv run with the message. Expressions use the functions below.

Grammar version

[schema]
version = 1

penv init writes the version here rather than as @schema in your file, because varlock rejects @schema (root decorators). penv 1.0.0-rc.1 reads up to version 1.

A higher version is unsupported_schema (config) or schema_too_new (@schema); penv upgrade fixes both. The config wins over @schema.

Types

penv accepts seven of the upstream data types. A key with no @type is a string.

There is no integer; write number(isInt=true). Another type is an unknown_type warning and penv checks a string; an unknown constraint is an unknown_constraint warning and is ignored.

Durations

@rotate takes y, m (calendar months), w, d, h, min and s, largest first, each at most once: 90d, 1y6m, 30min. 90 days does not parse. penv check prints @rotate as a reminder counted from the value's last write, without changing its exit code.

Computed values

DATABASE_URL=postgres://app:${DB_PASSWORD | urlencode}@db:5432/app
LOG_LEVEL=${LEVEL:-info}
SESSION_SECRET=random(length=32)
SHARED_KEY=penv(production/SHARED_KEY)
LITERAL='${NOT_EXPANDED}'

A value or schema default that holds ${KEY} or is one function call is computed. Upstream semantics: functions.

A single-quoted or backticked value is never computed. A value computed from a sensitive key is sensitive; a bundler-public one fails penv check and penv run. Failures exit 3 (errors).

Inference

penv decides required and sensitive per key when no decorator says otherwise.

A required key with no value fails penv check. penv ls prints no values, and penv run scrubs sensitive values from its output. What penv init infers: from a .env file.

Diagnostics

penv check reports every problem with line and column and exits 3; other commands refuse the file as invalid_schema, exit 3. Warnings never change the exit code.

Undeclared keys in .env are drift: penv check names them, penv run masks them, and the exit code holds.

Generated .env

penv pull and penv set write the same plain lines:

The reader accepts more and warns with line and column, never the character.

Next: penv check.