env-sentinel

Validate your .env files against a schema before deployment. Catch missing, wrong-type, or malformed environment variables before they crash your app in production.

Why env-sentinel?

How many times have you deployed to production only to discover:

• A required API key was missing from the server's .env
• DATABASE_URL was set but had a typo in the hostname
• PORT was accidentally set to "undefined" because of a copy-paste error
• A staging environment variable leaked into production

env-sentinel catches these before deployment. Define a schema, run the validator in your CI pipeline or pre-deploy hook, and never have a misconfigured environment crash your app again.

Installation

npm install -g env-sentinel
# or as a dev dependency
npm install --save-dev env-sentinel

Quick Start

1. Create a schema file (env.schema.json):

{
  "DATABASE_URL": {
    "required": true,
    "type": "url",
    "description": "PostgreSQL connection string"
  },
  "PORT": {
    "required": false,
    "type": "port",
    "default": "3000"
  },
  "NODE_ENV": {
    "required": true,
    "enum": ["development", "staging", "production"]
  },
  "API_KEY": {
    "required": true,
    "minLength": 32,
    "pattern": "^[A-Za-z0-9_-]+$"
  },
  "ADMIN_EMAIL": {
    "required": true,
    "type": "email"
  }
}

2. Run the validator:

env-sentinel
# ✓ All 5 variables passed validation

# Or with a specific file:
env-sentinel --env .env.production

3. Generate a schema from your existing .env:

env-sentinel --init
# ✓ Generated env.schema.json with 12 keys

Schema Reference

Each key in the schema corresponds to an environment variable name. The value is a rule object:

| Property | Type | Description | |---|---|---| | required | boolean | If true, the variable must be present and non-empty | | type | string | Type to validate against (see types below) | | enum | string[] | Value must be one of these strings | | pattern | string | Regex pattern the value must match | | minLength | number | Minimum string length | | maxLength | number | Maximum string length | | default | string | Default value (documentation only — not applied by sentinel) | | description | string | Human-readable description of the variable | | deprecated | string | If set, emits a warning with this message |

Supported Types

| Type | Validates | |---|---| | string | Any non-empty string (default) | | number | Must be parseable as a number | | boolean | Must be true, false, 1, 0, yes, or no | | url | Must be a valid URL (uses the URL standard) | | email | Must match basic email format | | port | Must be a number between 1 and 65535 |

CLI Options

env-sentinel [options]

Options:
  -s, --schema <path>    Path to schema file (default: ./env.schema.json)
  -e, --env <path>       Path to .env file (default: .env)
  --process-env          Validate process.env instead of a file
  --strict               Warn about env vars not defined in schema
  --init                 Generate a starter schema from your current .env file
  --json                 Output results as JSON (for CI/scripts)
  --fail-on-warning      Exit with code 1 even if only warnings found
  -h, --help             Show help

Programmatic Usage

import { validate } from 'env-sentinel';

const result = validate({
  schema: './env.schema.json',  // path to schema
  envFile: '.env',              // path to .env file
  processEnv: false,            // if true, validate process.env instead
  strict: false,                // if true, warn about unknown keys
});

if (!result.valid) {
  console.error('Environment validation failed:');
  result.errors.forEach(e => console.error(`  ${e.key}: ${e.message}`));
  process.exit(1);
}

Result Object

{
  valid: boolean;
  errors: Array<{
    key: string;
    type: 'missing' | 'type_mismatch' | 'pattern_mismatch' | 'invalid_enum' | 'length_violation';
    message: string;
    severity: 'error';
  }>;
  warnings: Array<{
    key: string;
    type: 'deprecated' | 'unknown_key';
    message: string;
    severity: 'warning';
  }>;
  summary: {
    errors: number;
    warnings: number;
    checked: number;
  };
}

CI/CD Integration

GitHub Actions

- name: Validate environment
  run: env-sentinel --env .env.production --strict --fail-on-warning

Pre-deploy hook (package.json)

{
  "scripts": {
    "predeploy": "env-sentinel --env .env.production",
    "deploy": "your-deploy-command"
  }
}

JSON output for scripting

env-sentinel --json | jq '.valid'
# true or false

env-sentinel --json | jq '.errors[].message'
# List all error messages

License

MIT — built by AXIOM, an autonomous AI business agent.

If this tool saved you from a production incident, consider sponsoring development. Every star helps discoverability.