rust · ~200KB binary · zero deps

sniff out
missing
.env keys .

potto compares .env against .env.example, points at the keys you forgot, and fixes them on the way out. Run it locally, in CI, or as a pre-commit hook.

install · one command

see it work → read the source

~/project — potto check

$ potto check
✗  missing in .env
   ├─ DATABASE_URL         (declared in .env.example:3)
   ├─ STRIPE_WEBHOOK_SECRET (declared in .env.example:7)
   ╰─ SENTRY_DSN           (declared in .env.example:12)

#  3 keys drifted. your teammate will thank you.
$ potto sync
✓  .env.example updated (+3 keys, atomic write)
$ echo "exit $?"
exit 0

real output · captured on a 47-key project

01 · the drift problem

Every stale .env.example is a pull request waiting to break.

A teammate adds STRIPE_WEBHOOK_SECRET locally, ships the feature, forgets to document it. Three days later, your CI is green and your staging is on fire. potto catches that drift before the commit lands.

before .env.example

DATABASE_URL=postgres://localhost/app
PORT=3000
# three keys quietly missing...

after potto sync .env.example

DATABASE_URL=postgres://localhost/app
PORT=3000
STRIPE_WEBHOOK_SECRET=
SENTRY_DSN=
REDIS_URL=

02 · why potto

Small tool.
Short memory.
Long attention span.

Four things potto is good at — and nothing else.

Walks up the tree: Auto-discovers .env and .env.example in parent directories, so your monorepo root doesn't need to think about cwd.
Atomic sync: potto sync writes to a temp file and renames — a crash mid-run can't corrupt your example file.
CI-ready exit codes: Exit 0 when synced, exit 1 when drifted. --quiet strips the chatter for logs; --verbose shows every file it touched.
Tiny and honest: ~200KB static binary, zero network access, zero telemetry. Handles CRLF, blank lines, comments, and quoted values without surprises.

03 · three commands

That's the whole API.

potto check

Drift detector

Reports keys in .env.example missing from .env. Exit 1 on drift — CI-friendly.

$ potto check
✗ 3 missing

potto sync

Auto-mender

Appends missing keys to .env.example atomically. Preserves comments and order.

$ potto sync
✓ +3 keys

potto compare

Bidirectional diff

Shows keys in either file that are missing from the other. Read-only, no writes.

$ potto compare
# 2↑ 1↓

04 · install

Pick your package manager.

Static binary, no runtime, no surprises. Works on Linux, macOS, and Windows.

$ cargo install potto rust

$ brew install iamkorun/tap/potto macos

$ curl -fsSL https://iamkorun.github.io/potto/install.sh | sh linux

$ docker run --rm -v $PWD:/w ghcr.io/iamkorun/potto check ci

.github/workflows/env.yml

name: env-drift
on: [pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: cargo install potto
      - run: potto check --quiet

.pre-commit-config.yaml

repos:
  - repo: local
    hooks:
      - id: potto
        name: sync .env.example
        entry: potto check
        language: system
        pass_filenames: false

05 · ship it

Never break a teammate again.

Put potto in your pre-commit hook. Forget about .env.example forever.

★ star on github ☕ buy me a coffee

sniff out missing .env keys .