ctroenv check

CI-friendly validation command. Designed for continuous integration pipelines.

Usage

ctroenv check [options]

Options

Option	Type	Default	Description
--source	string	.env	Path to the env file to check
--strict	boolean	false	Validate values against schema (not just keys)
--json	boolean	false	Output as JSON
--warn-unknown	boolean	false	Warn about keys in source not in schema (with "did you mean?" suggestions)

CI Integration

# .github/workflows/env-check.yml
name: Environment Check
on: [pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npx ctroenv check

Exit Codes

Code	Meaning
0	All variables valid
1	Validation errors found
2	Configuration error

Combine with .env.example in CI:

# Validate against the example file (all required vars present)
ctroenv check --source .env.example

# Strict mode: validate values against schema validators
ctroenv check --source .env --strict

Strict Mode

Without --strict, check only compares key sets — it reports missing and unused keys but does not validate values.

With --strict, each value is validated against its schema validator (same as ctroenv validate). This catches type mismatches, invalid URLs, out-of-range numbers, and other value-level errors.

# Key comparison only (fast)
ctroenv check --source .env

# Key comparison + value validation
ctroenv check --source .env --strict

Unknown Key Warnings

With --warn-unknown, the command reports keys found in the source file that are not defined in the schema. When a close match is detected via Levenshtein distance, a "did you mean?" suggestion is shown:

ctroenv check --source .env --warn-unknown
# ⚠ Unknown key: "DATABSE_URL"
#   → Did you mean "DATABASE_URL"?

JSON output

ctroenv check --source .env --strict --warn-unknown --json

{
  "source": ".env",
  "total": 5,
  "clean": false,
  "summary": {
    "missing": 2,
    "unused": 1,
    "matched": 2
  },
  "missing": ["DATABASE_URL", "JWT_SECRET"],
  "unused": ["OLD_KEY"],
  "matched": ["PORT", "NODE_ENV"],
  "validationErrors": [
    {
      "key": "DATABASE_URL",
      "message": "Invalid URL",
      "code": "invalid_value"
    }
  ],
  "unknownSuggestions": [
    { "key": "DATABSE_URL", "suggestion": "DATABASE_URL" }
  ]
}