@chriscode/hush

The AI-native secrets manager. Secrets stay encrypted at rest. AI can help without seeing values.

Hush stores project authority in encrypted v3 repository documents. The current model is simple:

• .hush/manifest.encrypted defines identities, bundles, targets, and imports
• .hush/files/**.encrypted stores the actual secret entries and file-level readers
• hush run -- <command> is the normal runtime path

There are no plaintext secret files to teach an AI assistant to avoid. Hush decrypts only for the active process or materialized target, then cleans up.

Read the full documentation →

Install

pnpm add -D @chriscode/hush
# or
npm install -D @chriscode/hush

Prerequisites

brew install sops age

Quick start

1. Bootstrap a v3 repository

npx hush bootstrap

That creates the encrypted repository shell, sets up keys, and writes the first v3 files:

.hush/manifest.encrypted
.hush/files/env/project/shared.encrypted

2. Inspect the current config

npx hush config show
npx hush config active-identity

Use hush config to inspect repository state and update file readers.

3. Add secrets safely

npx hush set DATABASE_URL
npx hush set API_KEY --gui

hush set prompts for the value when needed, so the assistant never sees it.

4. Run your app

npx hush run -- npm start
npx hush run -e prod -- npm build

This is the normal runtime path. Hush decrypts to memory and passes values to the command.

Current v3 repository model

Hush v3 keeps repository authority in encrypted YAML documents under .hush/.

| File | Purpose | |------|---------| | .hush/manifest.encrypted | Repository metadata, identities, bundles, targets, and imports | | .hush/files/**.encrypted | Secret entries plus readers for each encrypted file | | .sops.yaml | SOPS creation rules with the project public key |

hush bootstrap creates the shell. hush config inspects or updates it. hush run is how you use it day to day.

Core commands

| Command | What it does | |---------|---------------| | hush bootstrap | Create the v3 repository shell and initial active identity | | hush config show [section] | Show manifest, files, identities, targets, imports, or state | | hush config active-identity [name] | Show or change the active identity | | hush config readers <file-path> --roles <csv> | Update file readers | | hush set <KEY> | Add or update one secret safely | | hush inspect | List secret names with masked values | | hush has <KEY> | Check whether a secret exists | | hush run -- <command> | Run with secrets in memory | | hush push | Push a target to Cloudflare | | hush keys setup | Verify the local project key | | hush skill | Install the AI skill |

Legacy v2 migration

If a repository still uses the old v2 layout, use the migration bridge:

npx hush migrate --from v2
npx hush migrate --from v2 --cleanup

That is the supported bridge from legacy repositories to the current v3 model.

AI-safe workflow

For AI assistants, the safe loop is:

npx hush inspect
npx hush has DATABASE_URL
npx hush set DATABASE_URL
npx hush run -- npm start

You can also install the shipped skill:

npx hush skill
npx hush skill --global
npx hush skill --local

Example workflow

# bootstrap the repo once
hush bootstrap

# inspect config and identities
hush config show
hush config active-identity owner-local

# add secrets
hush set DATABASE_URL
hush set STRIPE_SECRET_KEY

# run the app
hush run -- npm start

Team setup

Copy the project age key into ~/.config/sops/age/keys/{project}.txt, then verify with:

hush config show state

Troubleshooting

SOPS or age is missing

brew install sops age

The key does not match this repository

Run:

hush keys setup

You need to convert a legacy repo

Run:

hush migrate --from v2

Add --cleanup after you validate the migrated state.

License

MIT