Troubleshooting

envkit: command not found over SSH or in cron

~/.local/bin is on your interactive PATH but often not on a non-interactive one, so a command that works when you log in fails from a script or a CI job.

command -v envkit || echo "not on this PATH"

Set the PATH explicitly in the unit, cron entry or script rather than relying on the login shell.

secret get returns nothing

A missing key prints a warning and returns empty with exit code 0 — by design, so a typo cannot break shell startup. It looks identical to success.

envkit secret list          # is the key actually there?
envkit doctor               # config, store and keychain in one pass

If the key is listed but the value is empty, the keychain is the place to look.

The keychain will not open

On Linux, pass needs an initialised GPG key:

envkit setup
gpgconf --list-dirs agent-socket   # is the agent reachable from here?

In a non-interactive context the agent may be unable to prompt for a passphrase. That surfaces as a keychain error, which exits non-zero — unlike a missing key.

backup refuses to run

The undeclared-secret scanner found something that looks like a secret you have not declared. That is the feature working.

Either declare it in the file's secrets list, or:

envkit backup --allow-unmanaged

If a file trips it repeatedly for good reason, set noscan = true on that entry.

load skipped a file

load will not overwrite a file you have changed locally. Check with envkit diff <path>, then envkit load --force if the store's copy should win. The previous contents go to ~/.envkit-backups/ either way.

A file shows as other-os

It is tracked in the OS layer for a different operating system, so it is correctly not restored here. See Many machines.