Skip to main content

​
Prerequisites

Before starting, make sure you have installed envcheck.

​
Your First Environment Check

Let’s create your first environment validation in just a few steps.
1

Navigate to Your Project

Open a terminal and navigate to your project directory:
cd /path/to/your/project
2

Initialize Configuration

Generate a default .envcheck.yaml configuration file:
envcheck init
You should see:
Successfully initialized .envcheck.yaml
This creates a .envcheck.yaml file with sensible defaults:
version: "1"
tools:
  - name: node
    version: ">=18.0.0"
  - name: git
env_vars:
  - name: NODE_ENV
    required: false
ports:
  - 3000
files:
  - path: .env
    required: false
network:
  - url: https://github.com
    status_code: 200
3

Run Your First Check

Execute envcheck to validate your environment:
envcheck
You’ll see output showing which checks passed and which failed:
Running environment checks...

✓ node 18.17.0 found
✓ git found
✓ Port 3000 is available
✗ .env does not exist
  Create .env file
✓ https://github.com connected (200)

--- 1 issue(s) found. Fix them to continue.
4

Fix Any Issues

Address any failing checks. For example, if .env is missing:
touch .env
Then run envcheck again:
envcheck
When all checks pass:
Running environment checks...

✓ node 18.17.0 found
✓ git found
✓ Port 3000 is available
✓ .env exists
✓ https://github.com connected (200)

--- All checks passed!

​
Customize Your Configuration

Now let’s customize the configuration for your specific project needs.

​
Example: Node.js Project

For a typical Node.js web application: 
version: "1"

tools:
  - name: node
    version: ">=18.0.0"
    required: true
  - name: npm
    version: ">=9.0.0"
    required: true
  - name: git
    required: true

env_vars:
  - name: NODE_ENV
    required: false
  - name: DATABASE_URL
    required: true

ports:
  - 3000
  - 5432

files:
  - path: .env
    required: true
  - path: package.json
    required: true

​
Example: Go Project

For a Go application: 
version: "1"

tools:
  - name: go
    version: ">=1.18.0"
    required: true

env_vars:
  - name: GOPATH
    required: false
  - name: GOBIN
    required: false

files:
  - path: go.mod
    required: true
  - path: main.go
    required: false

​
Advanced Usage

​
Custom Configuration Path

Use a configuration file from a different location: 
envcheck --config /path/to/custom-config.yaml

​
Verbose Output

Get detailed information about what envcheck is doing: 
envcheck --verbose

​
JSON Output for CI/CD

Export results in JSON format for integration with CI/CD pipelines: 
envcheck --json
Example JSON output: 
{
  "results": [
    {
      "status": "success",
      "message": "node 18.17.0 found",
      "suggestion": null
    },
    {
      "status": "error",
      "message": "DATABASE_URL is not set",
      "suggestion": "Set DATABASE_URL environment variable"
    }
  ],
  "summary": {
    "errors": 1,
    "warnings": 0,
    "successes": 4
  },
  "passed": false
}

​
Exit Codes

envcheck returns appropriate exit codes for scripting:
  • 0 - All checks passed
  • Non-zero - One or more checks failed
This makes it perfect for pre-commit hooks and CI/CD: 
#!/bin/bash
if envcheck; then
  echo "Environment validated!"
  npm start
else
  echo "Environment validation failed. Fix issues and try again."
  exit 1
fi

​
Integration Examples

​
Git Pre-commit Hook

Add envcheck to your pre-commit hook (.git/hooks/pre-commit): 
#!/bin/sh
envcheck || {
  echo "Environment check failed. Commit aborted."
  exit 1
}
Make it executable: 
chmod +x .git/hooks/pre-commit

​
GitHub Actions

Integrate envcheck into your CI pipeline: 
name: Environment Check

on: [push, pull_request]

jobs:
  envcheck:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install envcheck
        run: cargo install envcheck
      
      - name: Run environment checks
        run: envcheck --json

​
Docker

Validate the environment inside Docker containers: 
FROM node:18

# Install envcheck
RUN cargo install envcheck

# Copy config
COPY .envcheck.yaml .

# Validate environment at build time
RUN envcheck

# Continue with your application setup
COPY . .
CMD ["npm", "start"]

​
Configuration Reference

​
Tools Section

Validate installed tools and their versions: 
tools:
  - name: node              # Tool name (required)
    version: ">=18.0.0"     # Semver range (optional)
    required: true          # Fail if missing (default: true)
Supported semver operators: >=, <=, >, <, =, ^, ~

​
Environment Variables Section

Check environment variables: 
env_vars:
  - name: DATABASE_URL      # Variable name (required)
    required: true          # Fail if not set (default: true)
    pattern: "^postgres://" # Regex pattern (optional)

​
Ports Section

Verify port availability: 
ports:
  - 3000   # Port number
  - 5432
  - 8080

​
Files Section

Validate file and directory existence: 
files:
  - path: .env              # File path (required)
    required: true          # Fail if missing (default: true)
    is_directory: false     # Expect directory (default: false)
    permissions: 0o600      # Unix permissions in octal (optional)

​
Network Section

Check network connectivity: 
network:
  - url: https://api.github.com  # URL to check (required)
    status_code: 200              # Expected status code (optional)

​
Tips and Best Practices

Start Simple

Begin with basic checks (tools and files) and gradually add more validators as your project grows.

Version Control

Always commit .envcheck.yaml to version control so all team members use the same validation rules.

Optional vs Required

Use required: false for optional tools or files that enhance development but aren’t strictly necessary.

Semver Ranges

Use flexible version ranges (e.g., >=18.0.0) rather than exact versions to avoid unnecessary failures.

​
Common Validation Patterns

​
Microservices

Each service can have its own configuration: 
project/
├── service-a/
│   └── .envcheck.yaml
├── service-b/
│   └── .envcheck.yaml
└── service-c/
    └── .envcheck.yaml

​
Monorepo

Use a root configuration for common requirements: 
version: "1"

tools:
  - name: node
    version: ">=18.0.0"
  - name: git

files:
  - path: .env
    required: true

​
Next Steps

Configuration Guide

Learn about all available configuration options

CLI Commands

Explore all CLI commands and options

CI/CD Integration

Integrate envcheck into your pipelines

Examples

Browse example configurations for different project types