env-doctor

CLI Reference

Complete reference for all env-doctor commands and options.

Default Command

Scan the current directory for environment variable issues.

env-doctor [directory] [options]

Arguments

Argument	Description	Default
directory	Directory to scan	Current directory

Options

Option	Alias	Description
--config <path>	-c	Path to config file
--env <environment>	-e	Target environment (development, production, test)
--format <format>	-f	Output format: console, json, sarif
--workspaces [patterns]	-w	Scan all workspace packages (monorepo mode)
--pipeline <name>		Validate env vars for Turborepo/Nx pipeline
--ci		CI mode - exit code 1 on errors
--verbose	-v	Verbose output with debug info
--strict		Treat warnings as errors
--version	-V	Output version number
--help	-h	Display help

Examples

# Scan current directory
env-doctor

# Scan specific directory
env-doctor ./packages/api

# Use custom config
env-doctor -c ./custom-config.js

# Target production environment
env-doctor --env production

# Output as JSON
env-doctor --format json > report.json

# CI mode with SARIF output
env-doctor --ci --format sarif > results.sarif

# Verbose mode for debugging
env-doctor --verbose

# Strict mode (warnings = errors)
env-doctor --strict

# Scan all workspace packages
env-doctor --workspaces

# Scan specific workspaces
env-doctor --workspaces "apps/*,packages/*"

# Validate for Turborepo pipeline
env-doctor --pipeline build

---

init

Initialize env-doctor in your project.

env-doctor init [options]

Options

Option	Description
--config-only	Only create config file
--example-only	Only create .env.example
--force	-f	Overwrite existing files

Examples

# Initialize both config and .env.example
env-doctor init

# Create only config file
env-doctor init --config-only

# Create only .env.example
env-doctor init --example-only

# Overwrite existing files
env-doctor init --force

---

sync

Synchronize .env.example with your code and configuration.

env-doctor sync [options]

Options

Option	Description
--config <path>	-c	Path to config file
--generate	Generate new .env.example from scratch
--update	Update existing .env.example (preserves comments)
--dry-run	Show what would change without writing
--interactive	Interactively resolve sync decisions
--strategy <strategy>	Strategy: from-code, from-env, merge
--format <format>	Template format: grouped, alphabetical, categorized
--output <path>	Output file path (default: .env.example)

Sync Strategies

Strategy	Description
from-code	Only include variables found in code
from-env	Only include variables from .env files
merge	Combine code, .env, and config (default)

Examples

# Sync with smart merge (default)
env-doctor sync

# Generate fresh .env.example
env-doctor sync --generate

# Preview changes without writing
env-doctor sync --dry-run

# Interactive mode
env-doctor sync --interactive

# Use specific strategy
env-doctor sync --strategy from-code

# Custom output file
env-doctor sync --output .env.template

Output Example

# ═══════════════════════════════════════════════════════════════════════════════
# Environment Configuration Template
# Generated by env-doctor on 2024-01-15
# 
# Copy this file to .env and fill in the values.
# Run `npx env-doctor` to validate your configuration.
# ═══════════════════════════════════════════════════════════════════════════════

# ─────────────────────────────────────────────────────────────────────────────
# Database
# ─────────────────────────────────────────────────────────────────────────────

# PostgreSQL connection URL
# Required: Yes | Type: url
DATABASE_URL=

# ─────────────────────────────────────────────────────────────────────────────
# Authentication
# ─────────────────────────────────────────────────────────────────────────────

# JWT signing secret
# Required: Yes | Type: string | Secret: Yes
JWT_SECRET=

# Session token expiry in seconds
# Required: No | Type: number | Default: 3600
SESSION_EXPIRY=3600

---

matrix

Compare environment variables across multiple environments.

env-doctor matrix [options]

Options

Option	Description	Default
--config <path>	-c	Path to config file
--envs <list>	Comma-separated environments	All defined
--format <format>	-f	Output: table, json, csv, html	table
--ci	CI mode - exit code 1 on errors
--fix	Interactive fix mode

Examples

# Compare all environments
env-doctor matrix

# Compare specific environments
env-doctor matrix --envs development,production

# Output as JSON
env-doctor matrix --format json

# Generate HTML report
env-doctor matrix --format html > report.html

# CI mode
env-doctor matrix --ci

# Interactive fix mode
env-doctor matrix --fix

Output Example

Environment Variable Matrix
═══════════════════════════════════════════════════════════════════════

Variable              │ development    │ staging        │ production     │ Status
──────────────────────┼────────────────┼────────────────┼────────────────┼────────
DATABASE_URL          │ ✓ localhost    │ ✓ staging-db   │ ✓ prod-db      │ OK
STRIPE_SECRET_KEY     │ ✓ sk_test_...  │ ✓ sk_test_...  │ ✗ MISSING      │ ERROR
DEBUG_MODE            │ ✓ true         │ ✓ true         │ ✓ true         │ WARN

Summary:
  ✓ Consistent: 1
  ✗ Errors: 1
  ⚠ Warnings: 1

---

graph

Generate dependency graph visualization for monorepos.

env-doctor graph [options]

Options

Option	Description	Default
--config <path>	-c	Path to config file
--format <format>	-f	Output: ascii, mermaid, dot, json	ascii
--output <path>	-o	Save to file (optional)

Examples

# ASCII diagram in terminal
env-doctor graph

# Mermaid diagram (for docs)
env-doctor graph --format mermaid > graph.md

# DOT format (for Graphviz)
env-doctor graph --format dot > graph.dot
dot -Tpng graph.dot -o graph.png

# JSON data
env-doctor graph --format json

Output Example

Environment Variable Dependency Graph
═════════════════════════════════════════════════════════════

                    ┌─────────────┐
                    │  Root .env  │
                    └──────┬──────┘
                           │
          ┌────────────────┼────────────────┐
          │                │                │
          ▼                ▼                ▼
   ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
   │  apps/web   │  │  apps/api   │  │   worker    │
   └─────────────┘  └─────────────┘  └─────────────┘

Variables Flow:
  DATABASE_URL: Root → api, database, worker
  REDIS_URL: Root → api, database

---

generate:schema

Generate runtime validation schema from config.

env-doctor generate:schema [options]

Options

Option	Description	Default
--config <path>	-c	Path to config file
--output <path>	-o	Output file path	src/env.ts
--format <format>	Output: typescript, javascript	typescript
--framework <name>	Override framework detection
--include-docs	Include JSDoc comments

Examples

# Generate TypeScript schema
env-doctor generate:schema

# Custom output path
env-doctor generate:schema --output lib/env.ts

# JavaScript format
env-doctor generate:schema --format javascript

# With documentation
env-doctor generate:schema --include-docs

Output Example

// src/env.ts
// Auto-generated by env-doctor - do not edit manually

import { createEnv } from '@theaccessibleteam/env-doctor/runtime';

export const env = createEnv({
  server: {
    /**
     * PostgreSQL connection URL
     * @required
     */
    DATABASE_URL: {
      type: 'url',
      required: true,
    },
    /**
     * Server port
     * @default 3000
     */
    PORT: {
      type: 'number',
      default: 3000,
    },
  },
  client: {
    NEXT_PUBLIC_API_URL: {
      type: 'url',
      required: true,
    },
  },
  framework: 'nextjs',
});

---

fix

Interactively fix environment issues.

env-doctor fix [options]

Options

Option	Description
--config <path>	-c	Path to config file
--dry-run	Show what would be fixed without changes

Examples

# Interactive fix mode
env-doctor fix

# Dry run - preview changes
env-doctor fix --dry-run

---

scan-history

Scan git history for leaked secrets.

env-doctor scan-history [options]

Options

Option	Description	Default
--depth <number>	-d	Number of commits to scan	100
--format <format>	-f	Output format: console, json	console

Examples

# Scan last 100 commits
env-doctor scan-history

# Scan last 500 commits
env-doctor scan-history --depth 500

# Output as JSON
env-doctor scan-history --format json

---

watch

Watch for changes and re-analyze automatically.

env-doctor watch [options]

Options

Option	Description
--config <path>	-c	Path to config file

Examples

# Start watch mode
env-doctor watch

# With custom config
env-doctor watch --config ./custom-config.js

---

Exit Codes

Code	Meaning
0	No errors found
1	Errors found (or warnings in strict mode)

---

Environment Variables

Variable	Description
GITHUB_ACTIONS	Enables GitHub Actions annotation format
CI	Detected CI environment (various CI providers)
NO_COLOR	Disables colored output
ENV_DOCTOR_DEBUG	Enable debug logging

---

Output Formats

Console (default)

Human-readable output with colors and formatting.

JSON

Machine-readable JSON output for integration with other tools.

SARIF

GitHub Code Scanning format:

env-doctor --format sarif > results.sarif

Upload to GitHub:

- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

HTML

Interactive HTML report with filtering and sorting:

env-doctor matrix --format html > report.html

CSV

Spreadsheet-compatible format:

env-doctor matrix --format csv > report.csv

This site is open source. Improve this page.