@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.encrypteddefines identities, bundles, targets, and imports.hush/files/**.encryptedstores the actual secret entries and file-level readershush 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.
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