Envfile Spec

Start with the Envfile quickstart, or use this page as the language reference.

Syntax and options

Declare an environment variable by name:

# Envfile (safe to commit)
# ------------------------

strict true

env "KEY"

Add options after a comma to change how the variable is handled:

# Envfile (safe to commit)
# ------------------------

strict true

env "KEY", encrypted: false

Declarations

Save the file as Envfile in your project directory. It contains names and rules. Values stay in .env or your other environment sources.

Variable names are case-sensitive and must match [A-Za-z_][A-Za-z0-9_]*. Use single or double quotes. Comments begin with #. Blank lines are ignored.

# Envfile
strict true

env "DATABASE_URL", type: "url"
env 'SENTRY_DSN', optional: true

Every declaration is required, encrypted, and redacted by default. Proxying is off. There is no default type, enum, or range.

Options can continue on the next line after a comma:

env "PORT",
  type: "port",
  encrypted: false,
  redacted: false

Required and optional

required: true requires a value that is present and not blank. optional: true allows missing or blank values. When an optional value is supplied, its other rules still apply.

Use either required or optional in a declaration, never both. optional: false is equivalent to required: true.

Types, choices, and bounds

All environment values remain strings. Types validate them; they do not convert them.

• integer: a signed or unsigned whole number, such as 42 or -1.
• boolean: exactly true, false, 1, or 0.
• port: an integer from 0 through 65535.
• url: a URL with a scheme, including database URLs such as postgres://localhost/app.
• email: an email address with a valid local part and DNS-style domain.
• ip: an IPv4 or IPv6 address.

enum is a nonempty array of quoted strings or integers. Values must match one of the choices. With an integer or port type, choices compare numerically; other choices compare exactly. When combined with a type, every choice must satisfy that type.

Enum strings support escaped quotes, backslashes, and \n, \r, and \t. Arrays and proxy objects may have a trailing comma. A declaration cannot end with a trailing comma.

env "NODE_ENV", enum: ["development", "test", "production"]
env "WORKERS", type: "integer", min: 1, max: 32
env "PORT", type: "port", min: 1024, encrypted: false

min and max are inclusive integer bounds. They require type: "integer" or type: "port". The minimum cannot exceed the maximum. Port bounds are clamped to 0–65535.

Encryption and redaction

encrypted: true requires an encrypted source for a nonblank value. Use encrypted: false for values that may remain plaintext. The alias is encrypt.

redacted: true marks a value for output redaction. Use redacted: false for values that may be visible. The alias is redact.

env "DATABASE_URL", encrypted: true, redacted: true
env "PORT", type: "port", encrypted: false, redacted: false

These are independent rules. Allowing plaintext does not automatically allow output visibility. Declaring a rule does not rewrite your .env; run dotenvx encrypt to encrypt its values.

Undeclared loaded variables are not an allowlist violation. They still use the default encryption policy. Dotenvx public-key metadata is exempt from the encryption requirement.

Proxy

A proxy rule associates a secret with its destination domain:

env "STRIPE_SECRET_KEY", proxy: { domain: "api.stripe.com" }

The domain must be a DNS hostname. Schemes, ports, paths, wildcards, and IP addresses are not allowed. Domain names are normalized to lowercase.

proxy: false disables proxying for that variable, including an inherited rule. proxy: true is not supported. A proxy declaration does not start a proxy by itself; it is used by Dotenvx's credential-proxy integration.

File overrides

Group file-specific overrides inside file ".env.production" do … end. They inherit root rules and apply when that file is selected.

env "NODE_ENV", enum: ["development", "test", "production"]
env "SENTRY_DSN", optional: true

file ".env.production" do
  env "NODE_ENV", enum: ["production"]
  env "SENTRY_DSN", optional: false
  strict true
end

Paths are relative to the Envfile and must name exact files; globs are not supported. An override changes only the options it specifies. It can also introduce a variable that applies only to that file.

When multiple selected files have rules, each active policy must hold. Conflicting proxy domains for the same variable are an error. A redaction requirement from any active policy takes precedence over an allowance to display the value.

Strictness

dotenvx spec generates strict true at the top of each Envfile. This stops startup when validation fails. Set strict false to warn instead. Existing files that omit strict continue to warn. Set strictness once at the root or per file block. strict is the only root-level setting; it is not an env option. Encryption and redaction are per-variable options only; there is no root or file-level encrypted false or redacted false setting.

strict true

env "DATABASE_URL", type: "url"

For dotenvx run, strict rules stop the command on validation failure. Without strictness, validation failures warn. CLI --strict also stops on loading errors. dotenvx check reports validation failures with a nonzero exit status regardless of the Envfile strictness setting.

Invalid syntax

Duplicate declarations in one scope, duplicate options (including both spellings of an alias), and duplicate normalized file paths are errors. Unknown options are errors too. The current language has no value assignments, default values, imports, interpolation, loops, executable Ruby, or TOML syntax. Put actual values in your environment sources.

An invalid Envfile reports MALFORMED_ENVFILE. A failed validation reports INVALID_ENV. dotenvx check requires an Envfile; .env.example is not a substitute.

Commands

dotenvx spec
dotenvx check
dotenvx encrypt
dotenvx run -- node index.js

dotenvx spec creates an Envfile with strict true and variable declarations, without copying secret values. In a terminal, it lets you select env files and scan code for references. Use -f .env.production to select one file, --stdout to preview the result, or --overwrite to replace an existing Envfile and its custom rules.

Use dotenvx check -f .env.production to validate a specific file and its overrides. See the quickstart for a complete example.