## 🔎 Intro
**env-sentinel** is a lightweight, zero-dependency tool for analyzing `.env` files — offering both schema-based **validation** and powerful **linting** to ensure your environment variables are correct, consistent, and production-safe.
In addition to verifying variable types and required keys, **env-sentinel** can detect subtle and hard-to-spot issues such as malformed keys, unsafe characters, unescaped shell tokens, duplicate references, invalid syntax, and YAML pitfalls — problems that typical schema validation can't catch.
With fast execution and a human-readable schema format, **env-sentinel** eliminates the guesswork of `.env.example` files and bloated config validators — giving you clear, actionable feedback without writing custom validation logic.
---
## 📚 Documentation
**[📖 Read the full documentation at envsentinel.dev/docs →](https://envsentinel.dev/docs)**
Find detailed guides, examples, and API references on our official documentation site:
- **Quickstart Guide** - Get started in minutes
- **Linting** - Catch unused and inconsistent variables
- **Validation** - Validate against schema to prevent misconfigurations
- **Documenting** - Generate clear documentation for your team
- **API Reference** - Integration guides for programmatic use
---
### ✨ Key Features
- ✅ Lint .env files to catch formatting issues, unsafe syntax, and common misconfigurations
- ✅ Validate environment variables against a defined schema
- ✅ Generate markdown documentation from annotated schemas
- ✅ Simple schema format (e.g. VAR_NAME=required|number)
- ✅ Smart type detection when generating from .env
- ✅ Auto-generate schema with type inference from existing .env files
- ✅ Zero dependencies and extremely fast
- ✅ Ideal for local development, CI/CD, and team workflows
- ✅ Fast fail with clear, colorized output
- ✅ Available as both CLI tool and integrable library
## 📦 Installation
The easiest way to run `env-sentinel` is with `npx` (no installation required):
```shell
npx env-sentinel lint --file .env
```
Alternatively, you can install it globally or as a local project dependency:
### Using npm
```shell
# Global
npm install -g env-sentinel
# Local (in your project)
npm install --save-dev env-sentinel
```
### Using yarn
```shell
# Global
yarn global add env-sentinel
# Local
yarn add --dev env-sentinel
```
### Using pnpm
```shell
# Global
pnpm add -g env-sentinel
# Local
pnpm add -D env-sentinel
```
## 🚀 Quick Start
### 1. Lint your .env file
```bash
# Lint default .env file
npx env-sentinel lint
# Lint specific file
npx env-sentinel lint --file .env.production
```
### 2. Create a schema from your .env
```bash
# Generate schema from .env
npx env-sentinel init
# Overwrite existing schema
npx env-sentinel init --force
# Generate from different file
npx env-sentinel init --file .env.local
```
### 3. Validate against schema
```bash
# Validate default files (.env against .env-sentinel)
npx env-sentinel validate
# Validate custom files
npx env-sentinel validate --file .env.production --schema config/prod.schema
```
### 4. Generate documentation
```bash
# Generate documentation from schema
npx env-sentinel docs
# Specify custom files
npx env-sentinel docs --schema .env-sentinel-example --output CONFIG.md
```
## 📋 CLI Commands
### `lint` - Check for formatting issues
```bash
npx env-sentinel lint [--file ]
```
**Options:**
- `--file ` - Path to .env file (default: `.env`)
**What it checks:**
- Invalid key characters
- Missing or malformed values
- Duplicate keys
- Unsafe shell characters
- YAML boolean literals
- And 20+ other formatting rules
### `validate` - Validate against schema
```bash
npx env-sentinel validate [--file ] [--schema ]
```
**Options:**
- `--file ` - Path to .env file (default: `.env`)
- `--schema ` - Path to schema file (default: `.env-sentinel`)
**What it validates:**
- Required variables
- Type checking (number, boolean, string)
- Value constraints (min, max, enum)
- Security checks
### `init` - Generate schema from .env
```bash
npx env-sentinel init [--file ] [--force]
```
**Options:**
- `--file ` - Source .env file (default: `.env`)
- `--force` - Overwrite existing schema file
**Features:**
- Auto-detects types (number, boolean, string)
- Infers required/optional based on usage
- Skips invalid entries and reports them
### `docs` - Generate documentation from schema
```bash
npx env-sentinel docs [--schema ] [--output ]
```
**Options:**
- `--schema ` - Schema file to document (default: `.env-sentinel`)
- `--output ` - Output markdown file (default: `CONFIGURATION.md`)
**Features:**
- Generates markdown documentation from annotated schema
- Supports sections, descriptions, examples, and constraints
- Creates a table of contents for easy navigation
- Highlights sensitive variables (marked with `secure` validator)
- See [example schema](.env-sentinel-example) and [generated output](EXAMPLE_GENERATED_DOCS.md)
## 📝 Schema Format (.env-sentinel)
The `.env-sentinel` file defines validation rules for your environment variables. Think of it as a contract that your `.env` file must follow.
**Quick example:**
```dotenv
# Your .env file
DB_HOST=localhost
DB_PORT=5432
API_KEY=my-secret-key-12345
```
```dotenv
# Your .env-sentinel schema file
DB_HOST=required
DB_PORT=required|number|min:1|max:65535
API_KEY=required|min:16
```
When you run `npx env-sentinel validate`, it checks that:
- ✅ `DB_HOST` exists (it does: "localhost")
- ✅ `DB_PORT` exists AND is a number between 1-65535 (it is: 5432)
- ✅ `API_KEY` exists AND is at least 16 characters long (it is)
---
### Basic Schema
Each line in `.env-sentinel` represents a variable and its validation rules. You can combine multiple rules using the pipe (`|`) character:
```dotenv
# Simple validation - just check if exists
DB_HOST=required
# Type validation - must be a number
DB_PORT=required|number
# With constraints - number between 1 and 65535
DB_PORT=required|number|min:1|max:65535
# Optional variables
DEBUG=boolean
NODE_ENV=enum:development,production,test
# String validation - minimum length
API_KEY=required|min:32
# Complex example - all together
DB_PASSWORD=required|secure|min:12|default:"changeme"
```
### Documented Schema
Add documentation annotations using comment tags for markdown generation:
```dotenv
# @section Database
# @description Database connection settings
# @var Database server hostname
# @example localhost
DB_HOST=required
# @var Database server port
# @example 5432
DB_PORT=required|number|min:1|max:65535
# @var Database password (keep secure!)
DB_PASS=required|secure|min:8
```
**Available tags:**
- `# @section ` - Group variables into sections
- `# @description ` - Add description for section (supports multi-line)
- `# @var ` - Document a variable (supports multi-line)
- `# @example ` - Provide example value
**Documentation features:**
- Multi-line descriptions are supported
- Variables with `secure` validator are automatically highlighted with 🔒
- Default values from `default:"value"` are shown in documentation
- Type and constraints (min/max/enum) are automatically extracted
- Table of contents is generated for sections
See [.env-sentinel-example](.env-sentinel-example) for a full example.
### Supported Validation Rules
Use these rules in your `.env-sentinel` schema file to validate environment variables. Multiple rules can be combined using the pipe (`|`) separator.
| Rule | What it does | Usage Example | Common use cases |
|------|--------------|---------------|------------------|
| `required` | Variable must exist and have a value | `DB_HOST=required` | Critical variables like database connections, API endpoints |
| `number` | Value must be a valid number (integer or decimal) | `PORT=required\|number` | Ports, IDs, timeouts, counts, rate limits |
| `boolean` | Value must be exactly `true` or `false` | `DEBUG=boolean` | Feature flags, toggle switches, enable/disable settings |
| `string` | Explicitly marks variable as text (optional, default type) | `APP_NAME=string` | Documentation purposes, explicit type declaration |
| `min:value` | For numbers: minimum value
For strings: minimum length | `PORT=number\|min:1`
`API_KEY=min:32` | Valid port ranges, minimum key/password length |
| `max:value` | For numbers: maximum value
For strings: maximum length | `PORT=number\|max:65535`
`USERNAME=max:50` | Port limits, username/input length restrictions |
| `enum:val1,val2` | Value must be one of the listed options | `NODE_ENV=enum:dev,staging,prod` | Environment modes, log levels, deployment targets |
| `secure` | Enforces strong passwords (uppercase + lowercase + special chars) | `DB_PASS=required\|secure\|min:8` | Passwords, API keys, sensitive credentials |
| `default:"value"` | Specifies default value (shown in docs, not used in validation) | `PORT=number\|default:"3000"` | Documenting fallback values, optional configuration |
**How rules work together:**
```dotenv
# Single rule - just check if it exists
DB_HOST=required
# Multiple rules - must be required AND a number
DB_PORT=required|number
# Complex validation - required, must be a number, and between 1-65535
DB_PORT=required|number|min:1|max:65535
# With metadata - required, secure password, min 8 chars, with default shown in docs
DB_PASS=required|secure|min:8|default:"ChangeMe123!"
# Enum - must be one of these exact values
NODE_ENV=required|enum:development,staging,production
```
**Important notes:**
- `required` means the variable **must exist** in your `.env` file
- If you don't specify `required`, the variable is **optional**
- `min` and `max` are smart: they check **numeric value** for numbers, **character length** for strings
- `secure` validator checks for: uppercase letter + lowercase letter + number + special character
- `default` is for documentation only - it doesn't set actual values in your app
## 📊 Sample Output
### Linting Output
```bash
.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
```
### Validation Output
```bash
.env:3 [error] required → Missing required variable: DB_HOST
.env:5 [error] number → PORT must be a number (got: "abc")
.env:8 [warning] unknown-rule → Unknown rule 'invalid' for DEBUG
```
## 🔧 Library Integration
**env-sentinel** is also available as an integrable library for programmatic use:
### Installation
```bash
npm install env-sentinel
```
### Basic Usage
```typescript
import { lint, validate, parseEnvContent, parseSchemaContent } from 'env-sentinel';
// Lint .env content
const lintResult = lint(envContent);
if (!lintResult.isValid) {
console.log(`Found ${lintResult.summary.errors} errors`);
}
// Validate against schema
const envVars = parseEnvContent(envContent);
const schemaVars = parseSchemaContent(schemaContent);
const validateResult = validate(envVars, schemaVars, envContent);
// Handle results
validateResult.issues.forEach(issue => {
console.log(`${issue.severity}: ${issue.message}`);
});
```
### Available Functions
#### Core Functions
| Function | Description | Returns |
|----------|-------------|---------|
| `lint(envContent: string)` | Lint .env content | `Result` |
| `validate(envVars, schema, fileContent?)` | Validate against schema | `Result` |
| `parseEnvContent(content: string)` | Parse .env content | `Record` |
| `parseSchemaContent(content: string)` | Parse schema content | `Record` |
#### Individual Validators
| Function | Description | Returns |
|----------|-------------|---------|
| `numberValidator(key, value, args)` | Validate number type | `ValidationResult` |
| `booleanValueValidator(key, value, args)` | Validate boolean type | `ValidationResult` |
| `minValueValidator(key, value, args)` | Validate minimum value | `ValidationResult` |
| `maxValueValidator(key, value, args)` | Validate maximum value | `ValidationResult` |
| `enumValueValidator(key, value, args)` | Validate enum values | `ValidationResult` |
| `secureValueValidator(key, value, args)` | Validate secure values | `ValidationResult` |
#### Individual Lint Checks
| Function | Description | Returns |
|----------|-------------|---------|
| `noLeadingSpacesCheck(lineNumber, lineContent)` | Check for leading spaces | `LintResult \| undefined` |
| `noEmptyValueCheck(lineNumber, lineContent)` | Check for empty values | `LintResult \| undefined` |
| `noMissingKeyCheck(lineNumber, lineContent)` | Check for missing keys | `LintResult \| undefined` |
| `noDuplicateKeyCheck(lineNumber, lineContent)` | Check for duplicate keys | `LintResult \| undefined` |
| `noInvalidKeyDelimiterCheck(lineNumber, lineContent)` | Check for invalid key delimiters | `LintResult \| undefined` |
| `noInvalidKeyLeadingCharCheck(lineNumber, lineContent)` | Check for invalid leading chars | `LintResult \| undefined` |
| `noInvalidKeyCharactersCheck(lineNumber, lineContent)` | Check for invalid key characters | `LintResult \| undefined` |
| `noWhitespaceInKeyCheck(lineNumber, lineContent)` | Check for whitespace in keys | `LintResult \| undefined` |
| `noLowercaseInKeyCheck(lineNumber, lineContent)` | Check for lowercase in keys | `LintResult \| undefined` |
| `noUnsafeKeyCheck(lineNumber, lineContent)` | Check for unsafe keys | `LintResult \| undefined` |
| `noQuotedKeyCheck(lineNumber, lineContent)` | Check for quoted keys | `LintResult \| undefined` |
| `noSpaceBeforeEqualCheck(lineNumber, lineContent)` | Check for space before equals | `LintResult \| undefined` |
| `noSpaceAfterEqualCheck(lineNumber, lineContent)` | Check for space after equals | `LintResult \| undefined` |
| `noInvalidReferenceSyntaxCheck(lineNumber, lineContent)` | Check for invalid references | `LintResult \| undefined` |
| `noUnquotedMultilineValueCheck(lineNumber, lineContent)` | Check for unquoted multiline values | `LintResult \| undefined` |
| `noUnescapedShellCharsCheck(lineNumber, lineContent)` | Check for unescaped shell chars | `LintResult \| undefined` |
| `noEmptyQuotesCheck(lineNumber, lineContent)` | Check for empty quotes | `LintResult \| undefined` |
| `noUnquotedYAMLBooleanLiteralCheck(lineNumber, lineContent)` | Check for unquoted YAML booleans | `LintResult \| undefined` |
| `noDuplicateReferenceCheck(lineNumber, lineContent)` | Check for duplicate references | `LintResult \| undefined` |
| `noCommaSeparatedValueInScalarCheck(lineNumber, lineContent)` | Check for comma-separated values | `LintResult \| undefined` |
### Custom Validators & Checks
#### Validator Function Signature
```typescript
type ValidatorFn = (key: string, value: string, args: string[]) => ValidationResult;
type ValidationResult = string | true; // Return true for success, string for error message
// Example custom validator
const customValidator: ValidatorFn = (key, value, args) => {
if (value.length < 8) {
return `${key} must be at least 8 characters long`;
}
return true;
};
```
#### Lint Check Function Signature
```typescript
type LintCheckFn = (lineNumber: number, lineContent: string) => LintResult | undefined;
type LintResult = {
line: number;
issue: string;
severity?: 'warning' | 'error' | 'notice'
};
// Example custom lint check
const customCheck: LintCheckFn = (lineNumber, lineContent) => {
if (lineContent.includes('TODO')) {
return {
line: lineNumber,
issue: 'Found TODO comment in .env file',
severity: 'warning'
};
}
return undefined; // No issue found
};
```
#### Registering Custom Functions
```typescript
import { validatorRegistry, lintRegistry } from 'env-sentinel';
// Register custom validator
validatorRegistry.register('custom-min-length', customValidator);
// Register custom lint check
lintRegistry.register('no-todo-comments', {
name: 'no-todo-comments',
run: customCheck
});
```
### Result Types
```typescript
type Result = {
isValid: boolean;
issues: Issue[];
summary: Summary;
};
type Issue = {
line?: number;
key?: string;
message: string;
severity: 'error' | 'warning' | 'notice';
rule?: string;
value?: string;
};
type Summary = {
total: number;
errors: number;
warnings: number;
notices: number;
};
```
## 🤝 Why use env-sentinel?
- **Zero dependencies** — stays lightweight and fast
- **Human-readable schema** — more transparent than Joi/Zod configs
- **Quick setup** — works out of the box with npx
- **CI/CD friendly** — perfect for automated validation
- **Extensible** — custom validators and lint checks
- **Type-safe** — full TypeScript support
- **Dual purpose** — CLI tool and integrable library
## 💖 Sponsors
## License
[MIT license](https://opensource.org/licenses/MIT) — Free to use, modify, and contribute!
