> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/dotandev/envcheck/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Get up and running with envcheck in minutes

## Prerequisites

Before starting, make sure you have [installed envcheck](/installation).

## Your First Environment Check

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

<Steps>
  <Step title="Navigate to Your Project">
    Open a terminal and navigate to your project directory:

    ```bash theme={null}
    cd /path/to/your/project
    ```
  </Step>

  <Step title="Initialize Configuration">
    Generate a default `.envcheck.yaml` configuration file:

    ```bash theme={null}
    envcheck init
    ```

    You should see:

    ```
    Successfully initialized .envcheck.yaml
    ```

    This creates a `.envcheck.yaml` file with sensible defaults:

    ```yaml theme={null}
    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
    ```
  </Step>

  <Step title="Run Your First Check">
    Execute envcheck to validate your environment:

    ```bash theme={null}
    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.
    ```
  </Step>

  <Step title="Fix Any Issues">
    Address any failing checks. For example, if `.env` is missing:

    ```bash theme={null}
    touch .env
    ```

    Then run envcheck again:

    ```bash theme={null}
    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!
    ```
  </Step>
</Steps>

## 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:

```yaml theme={null}
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:

```yaml theme={null}
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:

```bash theme={null}
envcheck --config /path/to/custom-config.yaml
```

### Verbose Output

Get detailed information about what envcheck is doing:

```bash theme={null}
envcheck --verbose
```

### JSON Output for CI/CD

Export results in JSON format for integration with CI/CD pipelines:

```bash theme={null}
envcheck --json
```

Example JSON output:

```json theme={null}
{
  "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:

```bash theme={null}
#!/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`):

```bash theme={null}
#!/bin/sh
envcheck || {
  echo "Environment check failed. Commit aborted."
  exit 1
}
```

Make it executable:

```bash theme={null}
chmod +x .git/hooks/pre-commit
```

### GitHub Actions

Integrate envcheck into your CI pipeline:

```yaml theme={null}
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:

```dockerfile theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
ports:
  - 3000   # Port number
  - 5432
  - 8080
```

### Files Section

Validate file and directory existence:

```yaml theme={null}
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:

```yaml theme={null}
network:
  - url: https://api.github.com  # URL to check (required)
    status_code: 200              # Expected status code (optional)
```

## Tips and Best Practices

<Card title="Start Simple" icon="seedling">
  Begin with basic checks (tools and files) and gradually add more validators as your project grows.
</Card>

<Card title="Version Control" icon="code-branch">
  Always commit `.envcheck.yaml` to version control so all team members use the same validation rules.
</Card>

<Card title="Optional vs Required" icon="check-double">
  Use `required: false` for optional tools or files that enhance development but aren't strictly necessary.
</Card>

<Card title="Semver Ranges" icon="code-compare">
  Use flexible version ranges (e.g., `>=18.0.0`) rather than exact versions to avoid unnecessary failures.
</Card>

## 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:

```yaml theme={null}
version: "1"

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

files:
  - path: .env
    required: true
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Configuration Guide" icon="gear" href="/configuration/overview">
    Learn about all available configuration options
  </Card>

  <Card title="CLI Commands" icon="terminal" href="/cli/commands">
    Explore all CLI commands and options
  </Card>

  <Card title="CI/CD Integration" icon="server" href="/advanced/ci-cd">
    Integrate envcheck into your pipelines
  </Card>

  <Card title="Examples" icon="code" href="/examples/nodejs">
    Browse example configurations for different project types
  </Card>
</CardGroup>