🔐 envctl

A powerful command-line tool for managing and validating environment variables using schema definitions.

✨ Features

• ✅ Validate - Validate environment variables against a schema
• 🩺 Doctor - Actionable diagnostics and suggestions
• 📝 Generate - Generate .env.example files and documentation from schemas
• 🔍 Diff - Compare two environment files with secret protection

📦 Installation

Using Cargo

cargo install --git https://github.com/eladbash/envctl

Build from Source

git clone https://github.com/eladbash/envctl
cd envctl
cargo build --release

🚀 Quick Start

1. Create an env.schema.yaml file

fields:
  - key: "DATABASE_URL"
    required: true
    doc: "Database connection string"
    example: "postgresql://user:pass@localhost/db"
    secret: false
  
  - key: "API_KEY"
    required: true
    doc: "API key for external service"
    secret: true
  
  - key: "PORT"
    required: false
    default: "8080"
    doc: "Server port"
    example: "8080"
    secret: false

2. Validate your environment

envctl validate --schema env.schema.yaml

3. Run diagnostics

envctl doctor --schema env.schema.yaml

4. Generate .env.example

envctl generate env-example --schema env.schema.yaml

5. Generate documentation

envctl generate docs --schema env.schema.yaml

📚 Commands

✅ validate

Validate environment variables against the schema.

envctl validate --schema env.schema.yaml [--env .env] [--mode strict|lenient] [--format human|json]

Examples:

# Validate process environment
envctl validate --schema env.schema.yaml

# Validate a dotenv file
envctl validate --schema env.schema.yaml --env .env

# JSON output
envctl validate --schema env.schema.yaml --format json

🩺 doctor

Run diagnostics and provide actionable feedback.

envctl doctor --schema env.schema.yaml [--env .env] [--mode strict|lenient] [--format human|json]

Example output:

Environment Diagnostics Report

Summary:
  Missing:    1
  Invalid:   0
  Unknown:   1
  Deprecated: 0

Issues:
  [MISSING] DATABASE_URL
      Required environment variable is missing
      Example: postgresql://user:pass@localhost/db

  [UNKNOWN] UNKNOWN_VAR
      Unknown environment variable
      Suggestions: did you mean DATABASE_URL?

📝 generate env-example

Generate a .env.example file from the schema.

envctl generate env-example --schema env.schema.yaml [--out .env.example]

Example output:

# Database connection string
DATABASE_URL=postgresql://user:pass@localhost/db

# API key for external service
API_KEY=<redacted>

# Server port
PORT=8080

📖 generate docs

Generate markdown documentation from the schema.

envctl generate docs --schema env.schema.yaml [--out CONFIG.md]

🔍 diff

Compare two dotenv files.

envctl diff --schema env.schema.yaml left.env right.env [--fail-on-diff]

Example output:

Environment Differences

Missing in left:
  - NEW_VAR

Changed values:
  PORT: 8080 -> 3000
  API_KEY: <hidden> -> <hidden>

🎛️ Global Flags

Flag	Description
--schema <PATH>	Required - Path to env.schema.yaml
--env <PATH>	Optional - Dotenv file path; if omitted, uses process environment
--mode <strict|lenient>	Validation mode (default: strict)
--format <human|json>	Output format (default: human)
-q, --quiet	Reduce output
--no-color	Disable ANSI color output

📊 Exit Codes

Code	Meaning
0	✅ Success
1	❌ Error (validation failed, etc.)
2	⚠️ Differences found (only with --fail-on-diff flag on diff command)

🔧 Dependencies

• env-schema - Core schema validation (git dependency)
• clap - CLI argument parsing
• serde / serde_json - JSON serialization
• colored - ANSI color output

📄 License

Licensed under the MIT License. See LICENSE for more information.

---

Made with ❤️ using Rust