envfill

Keep your .env in sync with .env.template

Added a new env var to the template? envfill prompts your team for missing values, validates input, and generates secrets, so nobody runs the app with missing config.

npx envfill

• Syncs — only prompts for new/missing variables, keeps existing values
• Validates — URLs, emails, ports, custom regex
• Generates — secrets, passwords, tokens
• Integrates — shell commands for Vault, 1Password, AWS Secrets Manager

Quick Start

Create .env.template:

# Database password
DB_PASSWORD=<secret:32>

# Your user ID
USER_ID=`id -u`

# App environment
NODE_ENV=<dev|staging|*prod>

# Public URL
PUBLIC_URL=<required,url>

# API key (32 alphanumeric chars)
API_KEY=<regex:/^[a-zA-Z0-9]{32}$/:Enter a 32-char alphanumeric key>

Run npx envfill and get prompted for each value.

Template Syntax

Value	Behavior
PORT=3000	Default value
KEY=	Prompt (no default)
UID=`id -u`	Shell command as default
SECRET=<secret:32>	Auto-generate (alphanumeric)
TOKEN=<secret:16:alnum+special>	Auto-generate with charset
ENV=<a|b|*c>	Options (* = default)
URL=<required>	Must provide
URL=<url>	URL validation
EMAIL=<email>	Email validation
PORT=<port>	Port validation
COUNT=<integer:0:100>	Integer in range (min:max)
DEBUG=<boolean>	Yes/no toggle
KEY=<if:VAR>	Only prompt if VAR is truthy
B=${A}_suffix	Variable interpolation
KEY=<regex:/^pattern$/>	Custom regex validation
KEY=<regex:/^pattern$/i:error>	Regex with flags and custom error
NAME=<lowercase>	Transform to lowercase
NAME=<uppercase>	Transform to uppercase
SLUG=<slugify>	Slugify (lowercase + dashes)
NAME=<trim:->	Trim chars from edges
NAME=<replace:/pat/repl/g>	Regex replace

Combine with comma: <required,url> or <if:ENABLED,required>

Secret Charsets

Control which characters are used in generated secrets:

Preset	Characters
alnum	a-zA-Z0-9 (default)
alpha	a-zA-Z
lower	a-z
upper	A-Z
num	0-9
hex	0-9a-f
HEX	0-9A-F
special	!@#$%^&*()-_=+

Transform Directives

Transforms modify user input before storing. They apply left-to-right:

# Slugify: "My Cool App" → "my-cool-app"
PROJECT_SLUG=<slugify>

# Chain transforms: "  My App!  " → "my-app"
NAME=<lowercase,replace:/[^a-z0-9]+/-/g,trim:->

# Replace with regex: "hello world" → "hello_world"
SNAKE_CASE=<replace:/\s+/_/g>

# Combine with validation
PROJECT_ID=<slugify,required>

Transform	Effect	Example
<lowercase>	Convert to lowercase	"Hello" → "hello"
<uppercase>	Convert to uppercase	"Hello" → "HELLO"
<slugify>	Lowercase + replace non-alnum with dash + trim dashes	"My App" → "my-app"
<trim:chars>	Remove chars from start/end	<trim:-> on "-hello-" → "hello"
<replace:/pat/repl/flags>	Regex replace (g=global, i=case-insensitive)	See above

Fetching Secrets

Use shell commands to fetch secrets from any secret manager:

# HashiCorp Vault
DB_PASSWORD=`vault kv get -field=db_password secret/data/myapp`

# 1Password CLI
API_KEY=`op read "op://Vault/API Key/password"`

# AWS Secrets Manager
SECRET=`aws secretsmanager get-secret-value --secret-id myapp --query SecretString --output text`

CLI Options

envfill -i config.template -o .env.local
envfill --defaults    # Use all defaults
envfill --overwrite   # Re-prompt all (ignore existing)
envfill --dry-run     # Preview output

Multi-Template Support

Layer templates with multiple -i flags (later overrides earlier):

envfill -i base.template -i prod.template -i secrets.template

Variables are replaced in-place; new ones appear under file section headers.

Use in package.json

{
  "scripts": {
    "setup": "envfill",
    "setup:ci": "envfill --defaults"
  }
}

Then run npm run setup to interactively fill your .env.

License

MIT