Quickstart

Overview

This guide walks you through scanning your first project with Envark, understanding the output, and taking action on discovered issues. You’ll learn both the interactive TUI mode and direct CLI commands.

This quickstart assumes you have Node.js 18+ installed. If not, see the Installation guide first.

Step 1: Run Your First Scan

No installation needed - run Envark instantly with npx:

npx envark

This launches the interactive TUI (Terminal User Interface) in your current directory.

If you’re in a project directory, Envark automatically scans it. If you’re elsewhere, navigate to your project first with cd /path/to/project

Expected Output

You’ll see the Envark banner and command prompt:

███████╗███╗   ██╗██╗   ██╗ █████╗ ██████╗ ██╗  ██╗
██╔════╝████╗  ██║██║   ██║██╔══██╗██╔══██╗██║ ██╔╝
█████╗  ██╔██╗ ██║██║   ██║███████║██████╔╝█████╔╝
██╔══╝  ██║╚██╗██║╚██╗ ██╔╝██╔══██║██╔══██╗██╔═██╗
███████╗██║ ╚████║ ╚████╔╝ ██║  ██║██║  ██║██║  ██╗
╚══════╝╚═╝  ╚═══╝  ╚═══╝  ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝

Environment Variable Guardian v0.1.1

Type / to open command menu, or 'help' for available commands

> _

Type / (forward slash) to open the dropdown command menu:

> /

┌─ Commands ────────────────────────────────────┐
│ scan          Scan project for env variables  │
│ risk          Analyze environment risks       │
│ missing       Find undefined variables        │
│ duplicates    Find duplicate definitions      │
│ undocumented  Find undocumented variables     │
│ validate      Validate a .env file            │
│ generate      Generate .env.example           │
│ graph         Show dependency graph           │
│ help          Show help                       │
│ clear         Clear output                    │
│ exit          Exit Envark                     │
└───────────────────────────────────────────────┘

Navigate with arrow keys

Use ↓ and ↑ to highlight commands

Autocomplete with Tab

Press Tab to insert the selected command

Execute with Enter

Press Enter to run the command immediately

Step 3: Run a Complete Scan

Select the scan command or type it manually:

> /scan

Envark scans your entire project:

⠋ Scanning project...

Scan Results Example

After scanning completes (typically under 2 seconds for most projects):

✓ Scan complete (1.2s)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 PROJECT SCAN RESULTS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 Summary
  Total Variables:    24
  Defined:            20
  Used in Code:       22
  Missing:            3  ⚠️
  Undocumented:       5
  Dead (unused):      2

🔴 Critical Issues:    2
🟡 High Issues:        1
🟠 Medium Issues:      5

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Scanned 127 files in /home/user/my-project
Cache: MISS (first scan)

Next steps:
  • Run '/risk' to see detailed risk analysis
  • Run '/missing' to fix critical issues
  • Run '/validate .env' to check your env file

Critical issues mean variables used in your code are not defined anywhere. These will cause runtime crashes!

Step 4: Analyze Critical Risks

To see which variables will cause crashes, run:

> /missing

Missing Variables Output

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 MISSING ENVIRONMENT VARIABLES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

These variables are used in code but not defined:

🔴 STRIPE_SECRET_KEY
   Used in: src/payments/stripe.ts:12
            src/webhooks/stripe.ts:45
   Risk: CRITICAL - No default value
   → Add to .env file immediately

🔴 JWT_SECRET  
   Used in: src/auth/jwt.ts:8
   Risk: CRITICAL - No default value
   → Required for authentication

🟡 REDIS_URL
   Used in: src/cache/redis.ts:15
   Risk: HIGH - Has fallback to localhost
   → Will use localhost:6379 in development

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Found 3 missing variables (2 critical, 1 high)

⚠️  These will cause runtime errors if not fixed!

Step 5: View Detailed Risk Analysis

For a complete risk breakdown, run:

> /risk

Or filter by severity:

> /risk critical
> /risk high

Risk Analysis Output

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ENVIRONMENT VARIABLE RISK ANALYSIS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔴 CRITICAL (2)

STRIPE_SECRET_KEY
  ❌ Used but not defined (no default)
  📍 src/payments/stripe.ts:12
  💡 Add to .env: STRIPE_SECRET_KEY=your-key-here

JWT_SECRET
  ❌ Used but not defined (no default)
  📍 src/auth/jwt.ts:8
  💡 Generate with: openssl rand -hex 32

🟡 HIGH (1)

API_KEY
  ⚠️  Secret-like name found in config.js
  📍 src/config.js:5 - const API_KEY = "hardcoded"
  💡 Move to .env and use process.env.API_KEY

🟠 MEDIUM (5)

DATABASE_URL
  ⚠️  Used 8 times across 4 files
  ⚠️  No default value
  📍 src/db/connection.ts, src/migrations/run.ts...
  💡 Add default or ensure .env has this value

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Total Issues: 8
Run '/missing' for detailed remediation steps

Envark assigns risk levels using src/core/analyzer.ts based on usage patterns, definition status, and secret detection heuristics.

Step 6: Fix Critical Issues

Create or update your .env file with missing variables:

.env

# Payment Processing
STRIPE_SECRET_KEY=sk_test_your_stripe_key_here

# Authentication
JWT_SECRET=generated-secret-from-openssl-rand

# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/mydb

# Cache (optional - has default)
REDIS_URL=redis://localhost:6379

Never commit your .env file! Add it to .gitignore:

.gitignore

.env
.env.local
.env.*.local

Step 7: Validate Your Environment

After creating your .env file, validate it against your code:

> /validate .env

Validation Output

✓ Validating .env...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 VALIDATION RESULTS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ PASSED (20 variables)
  PORT, NODE_ENV, DATABASE_URL, STRIPE_SECRET_KEY...

❌ FAILED (2 variables)

JWT_SECRET
  Issue: Missing from .env
  Used in: src/auth/jwt.ts:8
  Required: YES

API_ENDPOINT
  Issue: Missing from .env  
  Used in: src/api/client.ts:15
  Required: YES

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

⚠️  2 required variables are missing

Step 8: Generate Documentation

Create a .env.example template for your team:

> /generate

This creates .env.example with all discovered variables:

.env.example

# Auto-generated by Envark
# Copy to .env and fill in your values

# Database Configuration
DATABASE_URL=postgresql://user:pass@localhost:5432/dbname

# Authentication
JWT_SECRET=your-secret-here

# Payment Processing  
STRIPE_SECRET_KEY=sk_test_...
STRIPE_PUBLIC_KEY=pk_test_...

# API Configuration
API_ENDPOINT=https://api.example.com
API_TIMEOUT=5000

# Server Settings
PORT=3000
NODE_ENV=development

# Redis Cache
REDIS_URL=redis://localhost:6379

Commit .env.example to version control so new developers know which variables to configure.

Direct CLI Commands

You can skip the TUI and run commands directly:

npx envark scan

CLI Examples with Output

$ npx envark scan

⠋ Scanning project...
✓ Scan complete (1.2s)

Project: /home/user/my-project
Scanned: 127 files (45 source, 3 env files)

Variables: 24 total
  • 20 defined
  • 22 used
  • 3 missing ⚠️
  • 5 undocumented

Risk Summary:
  🔴 Critical: 2
  🟡 High: 1
  🟠 Medium: 5

Run 'envark risk' for details

Using MCP Tools Programmatically

When Envark is configured as an MCP server, AI assistants can call these tools:

get_env_map Example

{
  "name": "get_env_map",
  "arguments": {
    "projectPath": "/home/user/my-project",
    "filter": "missing"
  }
}

Response:

{
  "summary": {
    "totalEnvVars": 24,
    "defined": 20,
    "used": 22,
    "missing": 3,
    "undocumented": 5,
    "dead": 2,
    "critical": 2
  },
  "variables": [
    {
      "name": "STRIPE_SECRET_KEY",
      "definedIn": [],
      "usedIn": ["src/payments/stripe.ts"],
      "languages": ["typescript"],
      "hasDefault": false,
      "isDocumented": false,
      "riskLevel": "critical",
      "issueCount": 1
    }
  ],
  "metadata": {
    "projectPath": "/home/user/my-project",
    "scannedFiles": 127,
    "cacheHit": false,
    "duration": 1243
  }
}

get_env_risk Example

{
  "name": "get_env_risk",
  "arguments": {
    "minRisk": "high"
  }
}

Response:

{
  "summary": {
    "critical": 2,
    "high": 1,
    "medium": 5,
    "low": 8,
    "info": 8
  },
  "riskReport": [
    {
      "name": "STRIPE_SECRET_KEY",
      "riskLevel": "critical",
      "issues": [
        {
          "type": "MISSING",
          "severity": "critical",
          "message": "Used in code but not defined",
          "recommendation": "Add STRIPE_SECRET_KEY to your .env file"
        }
      ],
      "usageCount": 2,
      "files": ["src/payments/stripe.ts", "src/webhooks/stripe.ts"]
    }
  ],
  "metadata": {
    "projectPath": "/home/user/my-project",
    "scannedFiles": 127,
    "cacheHit": true,
    "duration": 45
  }
}

Notice the second request used cache ("cacheHit": true) and completed in 45ms vs 1243ms. Envark caches results in .envark/cache.json until files change.

Performance & Caching

Envark is optimized for speed:

First scan: 1-2 seconds for 500-file projects
Cached scans: Under 100ms
Cache invalidation: Automatic when files change

Cache location:

.envark/
  └── cache.json    # Scan results with file hashes

Add .envark/ to .gitignore to keep cache files local:

.gitignore

.envark/

Common Workflows

Pre-Commit Hook

Add to .husky/pre-commit:

#!/bin/sh
npx envark risk critical
if [ $? -ne 0 ]; then
  echo "❌ Critical environment variable issues detected!"
  exit 1
fi

CI/CD Pipeline

Add to .github/workflows/env-check.yml:

name: Environment Check

on: [push, pull_request]

jobs:
  env-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - name: Check environment variables
        run: |
          npx envark risk critical
          npx envark validate .env.example

Team Onboarding Script

setup.sh

#!/bin/bash
set -e

echo "Setting up project environment..."

# Generate .env from template
if [ ! -f .env ]; then
  cp .env.example .env
  echo "✓ Created .env from template"
fi

# Validate environment
echo "Checking environment variables..."
npx envark validate .env

echo "✓ Environment setup complete!"

Next Steps

Now that you’ve completed the quickstart:

CLI Reference

Complete command documentation

MCP Integration

Connect Envark to your IDE

Advanced Features

AI assistant, graphs, and more

Get Started

Core Features

CLI Reference

MCP Integration

Guides

Overview

Step 1: Run Your First Scan

Expected Output

Step 2: Open the Command Menu

Step 3: Run a Complete Scan

Scan Results Example

Step 4: Analyze Critical Risks

Missing Variables Output

Step 5: View Detailed Risk Analysis

Risk Analysis Output

Step 6: Fix Critical Issues

Step 7: Validate Your Environment

Validation Output

Step 8: Generate Documentation

Direct CLI Commands

CLI Examples with Output

Using MCP Tools Programmatically

get_env_map Example

get_env_risk Example

Performance & Caching

Common Workflows

Pre-Commit Hook

CI/CD Pipeline

Team Onboarding Script

Next Steps

CLI Reference

MCP Integration

Advanced Features

Build docs developers (and LLMs) love

Get Started

Core Features

CLI Reference

MCP Integration

Guides

​Overview

​Step 1: Run Your First Scan

​Expected Output

​Step 2: Open the Command Menu

​Step 3: Run a Complete Scan

​Scan Results Example

​Step 4: Analyze Critical Risks

​Missing Variables Output

​Step 5: View Detailed Risk Analysis

​Risk Analysis Output

​Step 6: Fix Critical Issues

​Step 7: Validate Your Environment

​Validation Output

​Step 8: Generate Documentation

​Direct CLI Commands

​CLI Examples with Output

​Using MCP Tools Programmatically

​get_env_map Example

​get_env_risk Example

​Performance & Caching

​Common Workflows

​Pre-Commit Hook

​CI/CD Pipeline

​Team Onboarding Script

​Next Steps

CLI Reference

MCP Integration

Advanced Features

Build docs developers (and LLMs) love

Overview

Step 1: Run Your First Scan

Expected Output

Step 2: Open the Command Menu

Step 3: Run a Complete Scan

Scan Results Example

Step 4: Analyze Critical Risks

Missing Variables Output

Step 5: View Detailed Risk Analysis

Risk Analysis Output

Step 6: Fix Critical Issues

Step 7: Validate Your Environment

Validation Output

Step 8: Generate Documentation

Direct CLI Commands

CLI Examples with Output

Using MCP Tools Programmatically

get_env_map Example

get_env_risk Example

Performance & Caching

Common Workflows

Pre-Commit Hook

CI/CD Pipeline

Team Onboarding Script

Next Steps