Linting

Catch unused, missing, or inconsistent environment variables automatically with powerful linting tools.

Why Linting Matters

Even small mistakes in .env files can cause production failures:

Misspelled or duplicated keys
Unsafe shell characters
Hidden YAML pitfalls (on, off, yes, no)
Unescaped quotes or multiline values

env-sentinel lint catches these issues before they cause damage.

Basic Usage

Run linting on your default .env file:


npx env-sentinel lint

Lint a specific file:


npx env-sentinel lint --file .env.production

What It Checks

Invalid or unsafe characters in keys and values
Missing or empty values
Duplicate keys or references
Unescaped shell tokens like $, !, &
YAML boolean literals (true, false, yes, no, etc.)
Whitespace and formatting problems

Built-in Linting Rules

Below is a list of all built-in linting checks:

Rule	Description	Severity
no-leading-spaces	Checks for leading spaces in key names	error
no-empty-value	Detects empty values for keys	error
no-missing-key	Ensures every line has a key	error
no-duplicate-key	Prevents duplicate keys in .env	error
no-invalid-key-delimiter	Checks for invalid key=value delimiter usage	error
no-invalid-key-leading-char	Detects invalid leading characters in keys	error
no-invalid-key-characters	Detects invalid characters in keys	error
no-whitespace-in-key	Checks for spaces in key names	warning
no-lowercase-in-key	Ensures keys are uppercase	notice
no-unsafe-key	Detects unsafe characters in keys	warning
no-quoted-key	Prevents quoted keys	warning
no-space-before-equal	Checks for space before `=` in key=value	warning
no-space-after-equal	Checks for space after `=` in key=value	warning
no-invalid-reference-syntax	Detects invalid variable reference syntax	error
no-unquoted-multiline-value	Detects multiline values that are not quoted	error
no-unescaped-shell-chars	Detects unescaped shell-special characters	error
no-yaml-boolean-literal	Detects YAML-style booleans in values	warning
no-empty-quotes	Detects empty quotes	notice
no-duplicate-reference	Detects duplicate variable references	warning
no-comma-separated-value-in-scalar	Detects comma-separated values in scalar context	warning

Example Output


.env:5 [error] no-missing-key → Variable name is missing
.env:8 [warning] no-unescaped-shell-chars → Unescaped shell characters in value
.env:12 [notice] no-empty-value → Variable "COMMENTED_OUT" has an empty value

✅ Errors must be fixed
⚠️ Warnings highlight risky practices
💡 Notices are suggestions for improvement

CI/CD Integration

Linting can be added as a pre-commit hook or CI step:


{
  "scripts": {
    "lint:env": "env-sentinel lint --file .env"
  }
}

In CI (GitHub Actions example):


- name: Lint .env files
  run: npx env-sentinel lint --file .env.production

Next Steps

Explore Validation to enforce variable types.
Learn how to Document your configuration for better team workflows.

With env-sentinel, your .env files stay consistent, safe, and production-ready.