A lightweight C-based CLI tool for environment variable validation and management.
- Validate environment variables through CLI or configuration files (YAML/JSON)
- Multiple validation types:
- Type checking (string, integer, float, json)
- Numeric comparisons (gt, lt, ge, le, eq, ne)
- String validation (length, lengt, lenlt, enum, regex)
- Custom validation via shell commands
- Default values support
- Error reporting with descriptive messages
- Exit codes for CI/CD integration
Envil is particularly valuable in CI/CD pipelines where environment validation before deployment is critical. By validating environment variables early in the pipeline, you can:
- Catch configuration errors before starting resource-intensive build processes
- Prevent failed deployments due to missing or incorrect environment variables
- Save time and compute resources by failing fast when configurations are invalid
- Ensure consistent environments across different deployment stages
Example in a CI pipeline:
# Validate all required environment variables before building
envil -c config.yml || {
echo "Environment validation failed. Aborting build."
exit 1
}
# Proceed with build process only if validation passes
npm run buildYou can easily include Envil in your Docker images using multi-stage builds:
# Add Envil to your image and check
COPY --from=baldimario/envil /bin/envil /bin/envil
COPY config.yml config.yml
# This will fail with validation errors
RUN envil -c config.yml && rm /bin/envil && rm config.ymlThis allows you to validate environment variables before starting your application without adding dependencies to your final image.
After installation, view the full documentation with:
man envilFor local development, you can view the uncompressed man page with:
man ./man/man1/envil.1Envil supports shell completion for bash and zsh. To enable completion:
# Generate and install completion script
envil -C bash | sudo tee /etc/bash_completion.d/envil > /dev/null
# Or for user-specific installation
envil -C bash > ~/.bash_completion.d/envil
# Source the completion (or restart your shell)
source /etc/bash_completion.d/envil# Generate and install completion script
envil -C zsh | sudo tee /usr/share/zsh/site-functions/_envil > /dev/null
# Or for user-specific installation
envil -C zsh > ~/.zsh/completions/_envil
# Add to your .zshrc if using user-specific installation:
fpath=(~/.zsh/completions $fpath)The completion system provides:
- Flag completion (-e, -c, --type, etc.)
- Environment variable name completion for -e/--env
- File completion for -c/--config (filtered to .yml/.yaml/.json)
- Value completion for --type (string, integer, float, json)
The project requires the following libraries:
- libyaml: For YAML configuration file parsing
- json-c: For JSON configuration file parsing
On Debian/Ubuntu systems:
sudo apt-get install libyaml-dev libjson-c-devOn Red Hat/Fedora systems:
sudo dnf install libyaml-devel json-c-develOn macOS with Homebrew:
brew install libyaml json-cmake
sudo make installBasic variable validation:
envil -e VAR_NAME [options]Options:
-e, --env NAME: Environment variable to validate-d, --default VALUE: Default value if not set-p, --print: Print value if validation passes-c, --config FILE: Use configuration file-v, --verbose: Enable verbose logging-l, --list-checks: List available checks-C, --completion SHELL: Generate shell completion script-h, --help: Show help message
Validate enum with verbose output:
envil -e LOG_LEVEL --enum "debug,info,warn,error" -vValidate integer range:
envil -e PORT --type integer --gt 1024 --lt 65535 -vUsing default value:
envil -e API_URL -d "http://localhost:8080" --type string -pUsing configuration file with verbose output:
envil -c config.yml -vSetting environment variables with defaults:
# Set FOO with a default value and enum validation
FOO=$(envil -e FOO -d bar --enum bar,baz,buz)
# Export multiple variables with defaults
export DB_HOST=$(envil -e DB_HOST -d localhost --type string)
export DB_PORT=$(envil -e DB_PORT -d 5432 --type integer --gt 1024 --lt 65535)
export LOG_LEVEL=$(envil -e LOG_LEVEL -d info --enum debug,info,warn,error)# Integer validation
envil -e PORT --type integer --gt 1024 --lt 65535
# Float validation
envil -e THRESHOLD --type float --gt 0 --lt 1
# JSON validation
envil -e CONFIG --type json# Enum validation
envil -e LOG_LEVEL --type string --enum "debug,info,warn,error"
# Length validation
envil -e API_KEY --type string --len 32# Using shell command for validation
envil -e GIT_BRANCH --cmd "git rev-parse --verify HEAD"Run the examples script to see various validation scenarios in action:
./examples/examples.shThis script demonstrates:
- Handling missing environment variables
- Using default values
- Type validation
- Numeric range validation
- Configuration file validation with both YAML and JSON
- Multiple variable validation at once
You can specify multiple validations in a YAML or JSON configuration file:
PORT:
checks:
type: integer
gt: 1024
lt: 65535
LOG_LEVEL:
default: "info"
checks:
type: string
enum: debug,info,warn,error
CONFIG:
checks:
type: jsonUse the configuration with:
envil -c config.yml- 0: All validations passed
- 1: Configuration error (invalid config file or options)
- 2: Missing required variable
- 3: Type validation failed
- 4: Value validation failed (gt, lt, len, enum)
- 5: Custom command check failed
make test- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Run the tests (
make test) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
MIT License - see LICENSE file for details.