Quick Start

Get up and running with envcheck in minutes

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