_ envguard

Catch config drift before deploy

Point it at your repo. It diffs code references against .env.example and exits non-zero when drift would block a deploy.

Quick Start →

envguard - Environment Variable Audit

  • • 12 references (8 unique keys)
  • • .env.example: .env.example

$ envguard --no-wizard

  • MISSING missing

    NEW_SECRET

    app/api.py:42

  • UNUSED unused

    LEGACY_FLAG

    .env.example

  • EXTERNAL external

    REMOTE_CONTAINER_SECRET

    deploy.sh:12

  • OPTIONAL optional

    LOCAL_TIMEOUT_MS

    config.py:8

1 missing1 unused+4 more

Demo output · envguard --details for tables

Six findings. One clean audit

The reference below matches the README “Why Use It” table, what each TYPE means when you run envguard --details.

Why Use It →

Fails CI by default

UNUSEDA key exists in .env.example but is not referenced in the scanned code.
MISSINGA required key is referenced in code but is not present in .env.example or fetched Supabase secrets. This is blocking by default.

Advisory - does not fail CI

OPTIONALA defaulted/guarded key is absent from config. This is advisory and does not fail CI.
EXTERNALA key appears to belong to another runtime/container, such as an embedded script executed over SSH. This is advisory and does not fail CI.
IGNOREDA missing key was explicitly ignored by project config or CLI flags.
ORPHANEDA Supabase secret exists but is not referenced in code or documented in .env.example.

_ envguard

Local code. Remote secrets. Same report

Include Supabase Edge Function secrets in the audit. Referenced keys count if they exist in .env.example or Supabase.

Supabase Edge Functions →

$ export SUPABASE_ACCESS_TOKEN=…

$ envguard supabase your-project-ref

  • ORPHANED orphaned

    LEGACY_EDGE_SECRET

    Supabase

  • MISSING missing

    SUPABASE_URL

    functions/index.ts:4

Summary: 1 missing, 1 orphaned

Demo output · envguard --details for tables

Wizard tokens stay in memory for that run, not written to pyproject.toml.

A guided audit that still fits CI

On an interactive terminal, bare envguard opens the command builder. Use envguard --json or envguard ci in pipelines.

envguard ci →--json →
1

Wizard

envguard wizard

  1. Project path
    .
  2. Dotenv template
    config/example.env
  3. Compare Supabase? [Y/n]
2

Preview

Generated command
$ envguard --path . --dotenv config/example.env \
  --exclude fixtures/**
3

CI

GitHub Actions Annotations

2 errors, 1 warning

  • MISSING DATABASE_URL · .env.example:2
  • MISSING SUPABASE_ANON_KEY · .env.example:3
  • UNUSED LEGACY_FLAG

Agent-ready env hygiene

Teach Codex and other agents to guard secrets first

envguard now ships an optional agent skill. Install it so coding agents know when to run the CLI, how to interpret findings, and how to discuss environment drift without leaking secret values.

  • Run envguard before editing dotenv, CI, deployment, or Supabase secret config.
  • Report missing, unused, optional, external, ignored, and orphaned keys without exposing values.
  • Prefer envguard output over hand-rolled grep so agents do not miss supported patterns.
Agent Skill docs →View SKILL.md →
Install envguard skill

Project skill

Skills CLI

npx skills add Tresnanda/envguard --skill envguard

Install envguard guidance into the current agent workspace.

Global skill

Skills CLI

npx skills add Tresnanda/envguard --skill envguard -g

Make the skill available across your agent projects.

Preview first

Skills CLI

npx skills add Tresnanda/envguard -l

List bundled skills before installing anything.

Prune unused keys from .env.example

envguard --fix interactively removes unused keys with per-key confirmation.

_ --fixExit codes →

$ envguard --fix

Before

DATABASE_URL=
LEGACY_FLAG=
SUPABASE_URL=

After

DATABASE_URL=
SUPABASE_URL=

✓ Removed 1 unused key(s) from .env.example

Ship with the env you meant

Requires Python 3.9+. The installer uses pipx, then run envguard to start the guided audit.

Install for macOS / Linux

curl -fsSL https://raw.githubusercontent.com/Tresnanda/envguard/main/install.sh | bash
Installation →GitHub →