envcraft

╔════════════════════════════════════════════════════════════════════════════╗
║                                                                            ║
║   ███████╗███╗   ██╗██╗   ██╗ ██████╗██████╗  █████╗ ███████╗████████╗     ║
║   ██╔════╝████╗  ██║██║   ██║██╔════╝██╔══██╗██╔══██╗██╔════╝╚══██╔══╝     ║
║   █████╗  ██╔██╗ ██║██║   ██║██║     ██████╔╝███████║█████╗     ██║        ║
║   ██╔══╝  ██║╚██╗██║╚██╗ ██╔╝██║     ██╔══██╗██╔══██║██╔══╝     ██║        ║
║   ███████╗██║ ╚████║ ╚████╔╝ ╚██████╗██║  ██║██║  ██║██║        ██║        ║
║   ╚══════╝╚═╝  ╚═══╝  ╚═══╝   ╚═════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝        ╚═╝        ║
║                                                                            ║
║                      Precise tools for .env files                          ║
║                                                                            ║
║                      🐸 LazyFrog | kindware.dev                            ║
║                                                                            ║
╚════════════════════════════════════════════════════════════════════════════╝

---

🎯 What is envcraft?

envcraft is a safe, deterministic CLI tool for working with .env files. It performs three operations with absolute precision:

Command	Purpose
check	Validate a .env file against a YAML schema
diff	Show semantic differences between two .env files
format	Normalize and format a .env file

✨ Features

• 🔒 Safe — Never modifies secret values (only trims whitespace)
• 🎯 Deterministic — Same input always produces same output
• 🚫 No AI — No heuristics, no guessing, no surprises
• 🌐 Offline — No network access, no telemetry
• 🖥️ Cross-platform — Works on Windows, Linux, and macOS
• 📦 Zero unsafe code — Pure safe Rust

---

📦 Installation

From crates.io

cargo install envcraft

From source

git clone https://github.com/Brutus1066/envcraft.git
cd envcraft
cargo build --release

The binary will be at target/release/envcraft.

---

� CLI Reference

$ envcraft --help
Precise tools for .env files

Usage: envcraft <COMMAND>

Commands:
  check   Validate a .env file against a YAML schema
  diff    Show semantic differences between two .env files
  format  Normalize and format a .env file
  help    Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

envcraft check

$ envcraft check --help
Validate a .env file against a YAML schema

Usage: envcraft check <SCHEMA> <ENVFILE>

Arguments:
  <SCHEMA>   Path to the YAML schema file
  <ENVFILE>  Path to the .env file to validate

Options:
  -h, --help     Print help
  -V, --version  Print version

envcraft diff

$ envcraft diff --help
Show semantic differences between two .env files

Usage: envcraft diff [OPTIONS] <FILE1> <FILE2>

Arguments:
  <FILE1>  Path to the first .env file
  <FILE2>  Path to the second .env file

Options:
      --redact   Hide values in output (show only key names)
  -h, --help     Print help
  -V, --version  Print version

envcraft format

$ envcraft format --help
Normalize and format a .env file

Usage: envcraft format [OPTIONS] <FILE>

Arguments:
  <FILE>  Path to the .env file to format

Options:
      --in-place  Modify the file in place instead of printing to stdout
  -h, --help      Print help
  -V, --version   Print version

---

�🚀 Usage

Check: Validate against a schema

envcraft check schema.yml .env

Schema format (YAML):

PORT: int
DEBUG: bool
DATABASE_URL: string
API_KEY: string

Supported types:

Type	Description	Valid examples
string	Any value	hello, user@example.com
int	Integer (i64)	42, -10, 8080
bool	Boolean	true, false, TRUE, FALSE

Output:

error: missing required key: API_KEY
error: key 'PORT' has invalid value 'abc' (expected an integer)
warning: extra key not in schema: LEGACY_MODE
✗ validation failed with 2 error(s)

Diff: Compare two files

envcraft diff .env.production .env.staging

Output:

+ NEW_FEATURE=enabled
- DEPRECATED_KEY=old_value
~ DATABASE_URL: prod-db → staging-db
~ PORT: 80 → 8080

4 difference(s) found

Redact sensitive values:

envcraft diff .env.production .env.staging --redact

Output:

+ NEW_FEATURE
- DEPRECATED_KEY
~ DATABASE_URL
~ PORT

4 difference(s) found

Format: Normalize a file

envcraft format .env

What it does:

• ✅ Trims whitespace from keys and values
• ✅ Converts keys to UPPERCASE
• ✅ Normalizes format to KEY=VALUE
• ✅ Sorts keys alphabetically
• ✅ Preserves comments
• ❌ Never modifies actual values (except whitespace trimming)

Modify in place:

envcraft format .env --in-place

---

📋 Demo

Try the included demo files to see envcraft in action:

Validate a valid .env file

$ envcraft check demo/schema.yml demo/valid.env
✓ validation passed

Validate an invalid .env file

$ envcraft check demo/schema.yml demo/invalid.env
error: missing required key: API_KEY
error: key 'DEBUG' has invalid value 'maybe' (expected true or false)
error: key 'PORT' has invalid value 'not_a_number' (expected an integer (e.g., 42, -10))
✗ validation failed with 3 error(s)

Diff between environments

$ envcraft diff demo/dev.env demo/prod.env
~ API_KEY: sk_dev_key → sk_live_secret
+ CACHE_ENABLED=true
~ DATABASE_URL: postgres://localhost:5432/dev_db → postgres://prod-server:5432/prod_db
~ DEBUG: true → false
~ HOST: localhost → 0.0.0.0
- LOG_LEVEL=debug
~ PORT: 3000 → 80

7 difference(s) found

Diff with redacted values

$ envcraft diff demo/dev.env demo/prod.env --redact
~ API_KEY
+ CACHE_ENABLED
~ DATABASE_URL
~ DEBUG
~ HOST
- LOG_LEVEL
~ PORT

7 difference(s) found

Format a messy file

Before (messy.env):

# Development environment

port = 3000
host=localhost
debug=true
database_url = postgres://localhost:5432/dev_db
api_key=sk_dev_xyz789
  extra_spaces  =   lots of whitespace   

After:

$ envcraft format demo/messy.env
# Development environment

API_KEY=sk_dev_xyz789
DATABASE_URL=postgres://localhost:5432/dev_db
DEBUG=true
EXTRA_SPACES=lots of whitespace
HOST=localhost
PORT=3000

---

📋 Examples

Example .env file

# Database configuration
DATABASE_URL=postgres://localhost:5432/myapp

# Server settings
PORT=8080
DEBUG=false

# API keys
API_KEY=sk_live_abc123xyz

Example schema

# schema.yml
DATABASE_URL: string
PORT: int
DEBUG: bool
API_KEY: string

---

🔒 Trust & Safety

envcraft is designed with security in mind:

Guarantee	Description
🚫 No network access	The tool never makes HTTP requests
🚫 No telemetry	No data is collected or transmitted
🚫 No AI/heuristics	Behavior is 100% deterministic
🚫 No secret analysis	Values are treated as opaque strings
✅ Whitespace only	The only modification to values is trimming
✅ Offline operation	Works without internet connection
✅ Open source	Full source code available for audit

---

🛠️ Building

# Debug build
cargo build

# Release build (optimized)
cargo build --release

# Run tests
cargo test

# Run with verbose test output
cargo test -- --nocapture

---

🧪 Tests

envcraft includes comprehensive test coverage:

running 32 tests
test cli::tests::verify_cli ... ok
test diff::tests::test_diff_added ... ok
test diff::tests::test_diff_changed ... ok
test diff::tests::test_diff_complex ... ok
test diff::tests::test_diff_format_normal ... ok
test diff::tests::test_diff_format_redacted ... ok
test diff::tests::test_diff_identical ... ok
test diff::tests::test_diff_removed ... ok
test format::tests::test_format_complex ... ok
test format::tests::test_format_empty_value ... ok
test format::tests::test_format_mixed_case_key ... ok
test format::tests::test_format_preserves_comments ... ok
test format::tests::test_format_preserves_values ... ok
test format::tests::test_format_sorts_alphabetically ... ok
test format::tests::test_format_trims_whitespace ... ok
test format::tests::test_format_uppercase_keys ... ok
test parser::tests::test_empty_key_rejected ... ok
test parser::tests::test_invalid_line ... ok
test parser::tests::test_parse_empty_value ... ok
test parser::tests::test_parse_preserves_line_structure ... ok
test parser::tests::test_parse_quoted_values ... ok
test parser::tests::test_parse_simple_env ... ok
test parser::tests::test_parse_whitespace_handling ... ok
test schema::tests::test_schema_invalid_type ... ok
test schema::tests::test_schema_parsing ... ok
test schema::tests::test_schema_type_aliases ... ok
test schema::tests::test_validation_bool_case_insensitive ... ok
test schema::tests::test_validation_extra_key ... ok
test schema::tests::test_validation_missing_key ... ok
test schema::tests::test_validation_success ... ok
test schema::tests::test_validation_type_error_bool ... ok
test schema::tests::test_validation_type_error_int ... ok

test result: ok. 32 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

running 12 tests
test test_check_extra_key_warning ... ok
test test_check_missing_key ... ok
test test_check_type_error ... ok
test test_check_valid_env ... ok
test test_diff_added_removed_changed ... ok
test test_diff_identical_files ... ok
test test_diff_redact ... ok
test test_format_in_place ... ok
test test_format_preserves_comments ... ok
test test_format_stdout ... ok
test test_help_flag ... ok
test test_version_flag ... ok

test result: ok. 12 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Total: 44 tests passing ✓

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

🐸 About

envcraft is developed by LazyFrog at kindware.dev.

• 📧 Support: support@kindware.dev
• 🐙 GitHub: github.com/Brutus1066/envcraft
• 🌐 Website: kindware.dev

---

🐸 LazyFrog | kindware.dev
Precise tools for .env files