Core concepts

hushenv has three pieces and one rule.

References

A reference is a placeholder in your .env that names a secret without containing it:

DATABASE_URL=postgres://app:{hushenv.DB_PASSWORD}@localhost:5432/app

References can stand alone or sit inside a larger string, as above. The syntax is {hushenv.NAME}. For compatibility, {mysm.NAME} and {mysmtool.NAME} are also accepted.

The vault

The vault is a single file, ~/.hushenv/vault.json. Secret names are stored in plaintext — they aren’t sensitive, and hushenv ls needs them. Each value is encrypted individually with AES-256-GCM. The secret’s name is bound into the encryption as additional authenticated data, so a value cannot be moved or swapped between entries without failing to decrypt.

The keychain

The master key that decrypts the vault is generated by hushenv init and stored in your operating system’s native keychain — macOS Keychain or Windows Credential Manager. There is no key file on disk. On machines without a keychain (CI, containers), provide the key through the HUSHENV_MASTER_KEY environment variable instead.

The invariant

Plaintext exists in exactly one place: the environment of the process started by hushenv run, in memory, while that process runs. hushenv never writes a resolved .env to disk and has no command that materialises your secrets into a file. This is what makes the tool safe to point an agent at.