How it works

Two repositories

The app — envkit itself, generic, installed from Homebrew — and your store, a private git repository holding your dotfiles. envkit finds the store through ~/.config/envkit/config.toml.

Keeping them separate is the point. The store is data you own; envkit is a tool that reads and writes it.

The manifest

envkit.toml in the store lists what is tracked, each file's kind, and which of its values are secret. It is plain TOML and safe to edit by hand.

Two directions

backup copies ~ → store. load copies store → ~. There is no sync, because a sync has to decide which side wins, and getting that wrong costs you the only copy of something.

status tells you where each file stands so you can choose.

Secrets

Declared secrets are extracted on backup into the OS keychain — macOS Keychain through security, Linux through pass under an envkit/ namespace — and replaced with a placeholder in the store. Shell files source a generated ~/.config/envkit/secrets.<shell> that calls envkit secret get at startup.

Because neither backend can list by service, envkit keeps its own index of managed key names at ~/.config/envkit/keys.list. It holds names only, never values.

Safety rails

• load refuses to overwrite a locally-changed file without --force
• every overwrite is backed up to ~/.envkit-backups/ first
• the undeclared-secret scanner blocks backup when it spots a likely secret you did not declare — override with --allow-unmanaged, or mark the file noscan
• secret get is fail-soft on a missing key so a typo cannot lock you out of your shell, but exits non-zero on a real keychain error