hush

[hush]

a secret store for AI agents, the one with no get.

[CI] [MIT] [cross-platform] [no get]

get a secret once into the OS keychain, then inject it into commands forever, the value never hits stdout, the transcript, or the cloud.

A secret store for AI agents, with one hard rule: the agent never sees the plaintext.

Values never reach stdout, so they never land in the tool result, the transcript, or the cloud. A secret only ever moves from the store straight into the consumer. There's no get on purpose, a plain getter is the leak.

The point: you (an agent) are running as the user with their CLIs already authed, so you can already set a server-side secret or call a service, you just can't see the value without it landing in the chat. hush gets it once into the OS keychain, then you inject it into those commands forever. No chat paste, no temp files, no .env to commit by accident.

agents: start here

If you were handed this repo's url, install yourself, then follow the playbook. Get the hush script onto the box and read SKILL.md, that's the whole onboarding (it covers store / mint / inject and how to adopt hush in the repo you're working in). The script is one self-contained bash file; put it wherever your agent loads tools or just on your PATH:

git clone https://github.com/royashbrook/hushchmod +x hush/hush# then put hush/hush on your PATH, or move it into your agent's skills/tools dir

or run it straight from npm without cloning: npx @royashbrook/hush <cmd> (mac/linux; on windows use the clone, the orchestrator is bash).

Claude Code convenience (auto-loads as a skill): clone straight into the skills dir instead, whole session git clone https://github.com/royashbrook/hush ~/.claude/skills/hush, or one project ./.claude/skills/hush. Other agents: see AGENTS.md.

That's it, the human points you here and says "use the hush skill," and you take it from here. The one thing only a human can do is paste a secret they hold: when you hit that, run hush set <name> and a hidden dialog pops on their screen (you never see the value).

install (humans)

Same clone as above, or just grab the single hush script and put it on your PATH.

Backends: macOS Keychain, Linux libsecret (secret-tool), and Windows DPAPI (via PowerShell) are built in. On other platforms keep the same contract with your OS secret store (see SKILL.md). Cross-OS tested in CI (manual workflow_dispatch, all three runners).

maintenance (opt-in)

hush doctor checks local installation drift and backup health without opening the secret store. hush doctor --check-updates explicitly checks the public npm version. daily notices, agent-readable status, and reversible scheduler repair are covered in maintenance without surprises. nothing auto-upgrades.

quick start

hush set my-vendor-token                      # paste a value you hold (hidden prompt)printf '%s' "$TOK" | hush set my-vendor-token # ...or pipe it in (scripts/CI), still off argvhush set my-vendor-token --gui                # force the dialog (or --tty / --pipe; HUSH_PROMPT= too)hush mint app-operator-key                    # generate + store a random onehush run TOKEN=my-vendor-token -- some-cmd    # inject into a command, never printedhush sync lastpass --dry-run                  # preview a one-way LastPass synchush sync lastpass                            # upsert every name under LastPass group "hush"hush sync keepass --database vault.kdbx --db-secret keepass-password --dry-runhush sync bitwarden --dry-run                 # requires an unlocked BW_SESSIONhush list                                     # names only, never values

On an agent host where the dialog won't open (some runners have no GUI session, so macOS can't post the paste dialog, Connection Invalid ... hiservices-xpcservice): hush now says so plainly instead of a misleading "cancelled or empty", and the fix is to pipe the value (printf '%s' "$VAL" | hush set <name>) or run hush set <name> from a GUI-attached Terminal.

Naming: keep the default hush namespace and prefix names by project (blame-cf-token, lifescored-gemini-key) so one keychain search for hush finds everything. HUSH_NS is only for a genuinely separate store, not per-project. Need to fix an existing name? hush rename <old> <new> moves the value internally (never re-asked, never printed). Full docs + the portable contract: SKILL.md.

sync to LastPass

Install and log into the official LastPass CLI once, then preview and run the sync:

brew install lastpass-cli                     # macOSlpass login [email protected]hush sync lastpass --dry-run                  # names + destinations only, no values fetchedhush sync lastpass                            # all names -> hush/<name>hush sync lastpass --group team/secrets api-key deploy-keyhush sync lastpass --exclude local-only       # repeat to keep local-only names out of bulk sync

This is an upsert into each LastPass entry's password field. A missing entry is created, a unique entry is updated, and duplicate LastPass names fail closed. Values move over stdin, never argv, stdout, or a temp file. Each write uses --sync=now, so hush reports success only after LastPass has synchronized it to the server. Multiline hush values are refused because lpass password-field edits accept one line and would otherwise truncate them.

The sync runs wherever both hush and the official lpass CLI run: macOS, Linux, and Cygwin. The official CLI does not currently provide a native PowerShell or Node entry point, so native Windows remains limited by that dependency rather than by the hush store backend.

schedule it with experimental auto-login (macOS)

A cold npm install includes an optional Node-based launchd helper:

npm install -g @royashbrook/hushbrew install lastpass-clihush-lastpass-schedule install --auto-login --email [email protected] --every 6hhush-lastpass-schedule status

Auto-login is experimental. Its complete contract passes deterministic fake-CLI tests, but we could not complete a real trusted login because Homebrew lastpass-cli crashed in its MFA path before any vault access. This matches upstream lastpass-cli issue #719. It may work with account/MFA combinations unaffected by that bug, but it is not live-tested.

The design performs one interactive lpass login --trust, then asks once for the LastPass master password through hush's hidden prompt. Scheduled runs are intended to use that local Keychain value to restore the lpass session after reboot. This is explicit opt-in: no LastPass login material is stored unless --auto-login is present. The helper never uses lpass --plaintext-key, and its dedicated login secret is always excluded from vault sync. Failed setup installs nothing; revoked or expired trust makes later jobs fail closed.

Use hush-lastpass-schedule remove to unload the job. It retains the non-secret config and the hush login secret so removal cannot silently destroy credentials. Delete that secret separately with hush rm hush-lastpass-master-password if you want to revoke the opt-in completely.

An API key cannot replace this login: the published LastPass Business API manages accounts, companies, and reports, but does not expose vault-item writes. The scheduler is Node so other native schedulers can be added without changing the sync contract, but this release installs launchd on macOS only.

All three macOS sync schedulers use local-time calendar slots, so launchd runs a slot missed during sleep when the Mac wakes. --every is the maximum cadence; unusual values that do not divide a day or week evenly may run slightly early at the boundary, never later.

sync to a local KeePass database

KeePassXC opens the same encrypted KDBX file on macOS, Linux, and Windows. Put that file in an iCloud Drive folder and it becomes an offline-first backup that another iCloud machine can open without a service login:

brew install --cask keepassxchush set hush-keepass-master-passwordhush sync keepass --database "$HOME/Library/Mobile Documents/com~apple~CloudDocs/hush/hush.kdbx" \  --db-secret hush-keepass-master-password --init

--init refuses to overwrite a file. Later runs omit it and upsert entries in group hush:

hush sync keepass --database "$HOME/Library/Mobile Documents/com~apple~CloudDocs/hush/hush.kdbx" \  --db-secret hush-keepass-master-password --dry-runhush sync keepass --database "$HOME/Library/Mobile Documents/com~apple~CloudDocs/hush/hush.kdbx" \  --db-secret hush-keepass-master-password --exclude local-only

The database password and entry passwords reach keepassxc-cli only over stdin. They are never put on argv, stdout, logs, or a temp plaintext file. The database-password secret is always excluded. Missing entries are created, unique entries are updated, duplicate names fail closed, and multiline values are refused rather than truncated.

encrypted snapshots into iCloud (macOS, opt-in)

For whole-store encrypted snapshots instead of a password-manager mirror, npm also ships hush-backup and hush-backup-schedule. Requires GnuPG (brew install gnupg).

npm install -g @royashbrook/hushhush mint hush-backup-key  # only if absent; never overwrite an existing recovery key# keep a recovery copy outside this machine's Keychain before proceedinghush-backup --dry-runhush-backup-schedule install --every 6h --keep 30hush-backup-schedule status

Values stream into GPG; only ciphertext snapshots are written. The key is passed on a private file descriptor, not in arguments or logs. run performs one backup; remove stops the schedule without removing keys, config, or backups. A loaded job is not proof of backup success: check the dated log at ~/Library/Logs/hush-backup.log and a completed .gpg snapshot. iCloud upload is handled by macOS, not verified by this tool. Existing manual com.hush-backup schedules must be retired deliberately before installing the new job.

See backup options and the packaged recovery runbook. Recovery needs the separately saved key; an encrypted backup cannot recover its own key. Scheduling and interactive dialogs are macOS only. The unattended Bash/GPG path targets POSIX hosts with an explicit alternate directory; Windows backup-helper execution is not yet verified.

schedule KeePass into iCloud (macOS)

The npm package includes a Node/launchd helper. A cold setup creates the database if absent, asks for its password through hush when needed, performs the first sync, and loads the recurring job:

npm install -g @royashbrook/hushbrew install --cask keepassxchush-keepass-schedule install --every 6hhush-keepass-schedule status

The default destination is iCloud Drive/hush/hush.kdbx. Scheduled runs update an encrypted local mirror under Application Support/hush, then atomically publish a completed copy. KeePassXC never opens CloudDocs from launchd, avoiding macOS's headless iCloud privacy block. A publish that takes more than 30 seconds fails with an actionable error instead of hanging. Use --database, --db-secret, --group, repeatable --exclude, or positional names to narrow it. remove unloads the LaunchAgent but keeps the destination, local mirror, and mode-0600 metadata config.

Keep one durable copy of the database password outside this KDBX. After a machine loss, the iCloud file cannot recover the hush secret that unlocks it. Treat one machine as the writer while iCloud is syncing to avoid conflicted KDBX copies.

sync to Bitwarden

The official Bitwarden CLI supports create and edit operations, API-key login, and session-based vault access. Install it, then keep the three required credentials in hush:

brew install bitwarden-clihush set bitwarden-client-idhush set bitwarden-client-secrethush set bitwarden-master-password

Bitwarden's personal API key authenticates the CLI, but does not replace the master password. Vault reads and writes still require an unlock session. The npm-shipped scheduler handles that lifecycle without repeated interaction:

hush-bitwarden-schedule install --every 6hhush-bitwarden-schedule status

Install verifies all three hush names, performs bw login --apikey when needed, unlocks with --passwordenv, runs a value-free dry-run, then installs launchd. Each scheduled run obtains a short-lived session, syncs, and locks the CLI. API credentials, the master password, and the session are absent from argv, logs, the plist, and the mode-0600 metadata config.

The underlying command can also be used inside any already-unlocked Bitwarden CLI session:

hush sync bitwarden --dry-runhush sync bitwarden                         # all non-auth secrets -> folder hushhush sync bitwarden --folder backups api-key deploy-keyhush sync bitwarden --exclude local-only

Missing login items are created and unique items are updated. Exact duplicate names in the target folder fail closed. Existing item JSON flows directly from bw into the JSON transformer, and encoded create/edit bodies flow directly into bw over stdin. Passwords never enter argv, stdout, logs, or temp files. The three default Bitwarden auth secrets are always excluded. Bitwarden automatically pushes successful create and edit changes to the server.

The core sync is Bash plus Node and follows the platforms supported by hush and bw. The included scheduler currently installs a macOS LaunchAgent. hush-bitwarden-schedule remove unloads it while retaining the non-secret config and hush credentials.

not a vault

An agent with shell access can read+write this store, so it's not a lock against a hostile process. It's structure that keeps plaintext out of the transcript and makes "store once, inject everywhere" the easy path. It's also only as durable as the machine it's on (a local keychain), back the machine up, or sync onward into a real secret manager, and don't make hush the only copy of a secret you can't regenerate. MIT licensed.