CLI reference

hushenv init

Generates a master key, stores it in the OS keychain, and creates an empty vault at ~/.hushenv/vault.json. Safe to run again — it won’t overwrite an existing vault or key.

hushenv set <name> [value]

Stores a secret, encrypted.

hushenv set DB_PASSWORD              # hidden prompt (recommended)
echo 'value' | hushenv set DB_PASSWORD --stdin

Passing the value as a positional argument works but is discouraged — it lands in your shell history. The command warns you when you do.

Secret names use letters, digits, and underscores and can’t start with a digit (^[A-Za-z_][A-Za-z0-9_]*$). Empty values are rejected.

hushenv get <name>

Reveals a secret’s plaintext value. This requires an interactive terminal and a confirmation prompt. A non-interactive shell — including most agent shells — is refused by default.

hushenv get DB_PASSWORD
hushenv get DB_PASSWORD --force      # skip the prompt (use sparingly)

hushenv ls

Lists secret names and their last-updated date. Never prints values.

hushenv rm <name>

Deletes a secret from the vault.

hushenv mv <old> <new>

Renames a secret. Alias: hushenv rename. The value is re-encrypted under the new name — the name is bound into the ciphertext as additional authenticated data, so a rename is a re-encrypt. Pass --force to overwrite an existing <new>.

hushenv mv OLD_NAME NEW_NAME
hushenv mv OLD_NAME NEW_NAME --force   # overwrite if NEW_NAME already exists

hushenv run [options] -- <command>

Resolves the references in your env file(s) and runs the command with the secrets injected into its environment.

hushenv run -- pnpm dev
hushenv run -f .env.local -- pnpm dev
hushenv run -f .env.local -f .env -- pnpm dev   # first file wins on conflicts

If a referenced secret is missing from the vault, the command fails before your app starts and tells you exactly which hushenv set commands to run. Existing environment variables are never overwritten by file values.

hushenv import [options]

Migrates an existing .env into the vault: stores the real values encrypted and rewrites the file to references in place. This is the fastest way to adopt hushenv in a project that already has a populated .env.

hushenv import                 # interactive: choose which values to vault
hushenv import --dry-run       # show the plan, change nothing
hushenv import -f .env.local   # a specific file (default ./.env)
hushenv import --all           # non-interactive; use the heuristic defaults
hushenv import --prefix APP    # namespace imported names (DB_PASSWORD -> APP_DB_PASSWORD)

It skips values that are already references, empty, multiline, or have invalid names, and by heuristic leaves obvious non-secrets — booleans, plain numbers, and localhost URLs — in the file. When a name already exists in the vault with a different value, it asks whether to overwrite, keep, or rename; --force and --skip-existing make that choice non-interactively. The rewrite preserves your comments, ordering, quoting, and line endings, and every imported secret is round-tripped (re-decrypted and compared) before the file is touched.

After importing, rotate any secret whose old plaintext was ever committed — import cannot scrub it from your git history.

Exit codes

• 0 — success
• 1 — general error
• 2 — a referenced secret or named secret was not found

Environment variables

• HUSHENV_MASTER_KEY — supply the master key directly (32 bytes, base64). Used on machines without a keychain.
• HUSHENV_HOME — override the vault location (default ~/.hushenv).