{
"markdown": "# @chriscode/hush\n\n> **The AI-native secrets manager.** Secrets stay encrypted at rest. AI can help without seeing values.\n\n[](https://www.npmjs.com/package/@chriscode/hush)\n[](https://hush.ch5.me)\n\n![\"Hush](\"./hero.webp\")
\n\nHush stores project authority in encrypted v3 repository documents. The current model is simple:\n\n- `.hush/manifest.encrypted` defines identities, bundles, targets, and imports\n- `.hush/files/**.encrypted` stores the actual secret entries and file-level readers\n- `hush run -- ` is the normal runtime path\n\nThere 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.\n\n**[Read the full documentation →](https://hush.ch5.me)**\n\n## Install\n\n```bash\npnpm add -D @chriscode/hush\n# or\nnpm install -D @chriscode/hush\n```\n\n### Prerequisites\n\n```bash\nbrew install sops age\n```\n\n## Quick start\n\n### 1. Bootstrap a v3 repository\n\n```bash\nnpx @chriscode/hush bootstrap\n```\n\nThat creates the encrypted repository shell, sets up keys, and writes the first v3 files:\n\n```text\n.hush/manifest.encrypted\n.hush/files/env/project/shared.encrypted\n```\n\n### 2. Inspect the current config\n\n```bash\nnpx @chriscode/hush config show\nnpx @chriscode/hush config active-identity\n```\n\nUse `hush config` to inspect repository state and update file readers.\n\n### 3. Add secrets safely\n\n```bash\nnpx @chriscode/hush set DATABASE_URL\nnpx @chriscode/hush set API_KEY --gui\n```\n\n`hush set` prompts for the value when needed, so the assistant never sees it.\n\n### 4. Run your app\n\n```bash\nnpx @chriscode/hush run -- npm start\nnpx @chriscode/hush run --target prod -- npm build\n```\n\nThis is the normal runtime path. Hush decrypts to memory and passes values to the command.\n\n## Why Hush?\n\n**Short answer:** Hush adds structured identity/ACL, agent-safe commands, provenance, and AI skill packaging on top of raw sops+age.\n\n| Tool | Encrypted at rest | Per-file ACLs | Agent-safe commands | Local/zero-server |\n|------|:-----------------:|:-------------:|:-------------------:|:-----------------:|\n| **Hush** | yes | yes | yes (`inspect`, `has`, `set`, `--gui`) | yes |\n| raw sops+age | yes | manual | no | yes |\n| dotenvx | yes (in repo) | no | values flow through agent context | yes |\n| Doppler / Infisical | yes | yes | partial | no (SaaS) |\n\n- **vs raw sops+age**: If you just need encrypted env files, raw sops works fine. Hush adds per-file reader ACLs, identity/bundle/target resolution, provenance/trace, AI-agent skill packaging, and `--gui` value isolation so a human types the secret and the agent never sees it.\n- **vs dotenvx**: dotenvx encrypts `.env` files in the repo, but values still flow through the agent's context when the agent edits or reads them. Hush keeps values out of the agent surface entirely.\n- **vs Doppler/Infisical**: Both are excellent SaaS options. Hush is local and zero-server — no cloud dependency, no SaaS account required.\n\n## Security\n\nHush delegates all cryptographic operations to [sops](https://github.com/getsops/sops) and [age](https://github.com/FiloSottile/age). No home-rolled crypto. Hush itself is a single-maintainer project and has not yet been externally audited — use it accordingly and report issues via [SECURITY.md](./SECURITY.md).\n\n**Threat model in brief:** Hush removes standing plaintext secret files and narrows the surface through which an agent can accidentally expose values. However, an agent that can execute arbitrary commands (`hush run -- env`) can still read injected values at runtime. Hush's protections for AI workflows are guardrails and auditability, not a sandbox. See the [threat model docs](https://hush.ch5.me/guides/threat-model/) for details.\n\n### Update check\n\nHush checks for new versions once per day via a standard HTTP request to the npm registry. No telemetry is sent — only a version check. To disable:\n\n```bash\nHUSH_NO_UPDATE_CHECK=1 hush run -- npm start\n```\n\nAlso respects `NO_UPDATE_NOTIFIER=1` and any `CI` environment variable.\n\n## Current v3 repository model\n\nHush v3 keeps repository authority in encrypted YAML documents under `.hush/`.\n\n| File | Purpose |\n|------|---------|\n| `.hush/manifest.encrypted` | Repository metadata, identities, bundles, targets, and imports |\n| `.hush/files/**.encrypted` | Secret entries plus readers for each encrypted file |\n| `.sops.yaml` | SOPS creation rules with the project public key |\n\n`hush bootstrap` creates the shell. `hush config` inspects or updates it. `hush run` is how you use it day to day.\n\n## Core commands\n\n| Command | What it does |\n|---------|---------------|\n| `hush bootstrap` | Create the v3 repository shell and initial active identity |\n| `hush config show [section]` | Show manifest, files, identities, targets, imports, or state |\n| `hush config active-identity [name]` | Show or change the active identity |\n| `hush config readers --roles ` | Update file readers |\n| `hush set ` | Add or update one secret safely |\n| `hush delete-key --from ` | Remove a secret from an encrypted file |\n| `hush copy-key ` | Copy one key between encrypted v3 files |\n| `hush move-key ` | Move one key between encrypted v3 files |\n| `hush edit [file]` | Edit all secrets in an editor |\n| `hush inspect` | List secret names (values masked) |\n| `hush list` | List variable names (values masked; `--reveal` to show) |\n| `hush has ` | Check whether a secret exists |\n| `hush run -- ` | Run with secrets in memory |\n| `hush materialize` | Write secrets to files for CI/tooling |\n| `hush push` | Push a target to Cloudflare |\n| `hush keys setup` | Verify the local project key |\n| `hush doctor` | Diagnose root, key, and store resolution |\n| `hush skill` | Install the AI skill |\n\n## Legacy v2 migration\n\nIf a repository still uses the old v2 layout, use the migration bridge:\n\n```bash\nnpx @chriscode/hush migrate --from v2\nnpx @chriscode/hush migrate --from v2 --cleanup\n```\n\nThat is the supported bridge from legacy repositories to the current v3 model.\n\n## AI-safe workflow\n\nFor AI assistants, the safe loop is:\n\n```bash\nnpx @chriscode/hush inspect\nnpx @chriscode/hush has DATABASE_URL\nnpx @chriscode/hush set DATABASE_URL\nnpx @chriscode/hush run -- npm start\n```\n\nYou can also install the shipped skill:\n\n```bash\nnpx @chriscode/hush skill\nnpx @chriscode/hush skill --global\nnpx @chriscode/hush skill --local\n```\n\n## Example workflow\n\n```bash\n# bootstrap the repo once\nhush bootstrap\n\n# inspect config and identities\nhush config show\nhush config active-identity owner-local\n\n# add secrets\nhush set DATABASE_URL\nhush set STRIPE_SECRET_KEY\n\n# run the app\nhush run -- npm start\n```\n\n## Shell completions\n\n```bash\nhush completion zsh > ~/.zsh/completions/_hush # also: bash, fish\n```\n\n## Scripting and agents\n\nDiscover the exact contract with `hush --help`; command help is repository-free and lists only accepted options and value domains. Prefer `--json` for automation: stdout is result data and stderr is diagnostics. See the [agent and automation contract](https://hush.ch5.me/guides/agent-automation/).\n\nMachine-readable output is available on the read-only surface — `has`, `check`,\n`inspect`, `status`, `doctor`, `resolve`, `trace`, `verify-target` all take\n`--json` and never emit secret values. `hush export-example --write` produces a\ncommittable `.env.example` so a fresh clone can see which keys it needs before\nit has the decryption key.\n\nStandalone single-file binaries (Linux, macOS, Windows; with SHA256SUMS) are\nattached to each [Forgejo Release](https://git.ch5.me/ch5/hush/releases) as an\nalternative to the npm package.\n\n## Team setup\n\nCopy the project age key into `~/.config/sops/age/keys/{project}.txt`. Hush auto-matches that file against the repo `.sops.yaml` recipient, or you can force it explicitly with `SOPS_AGE_KEY_FILE`. Then verify with:\n\n```bash\nhush config show state\n```\n\n## Troubleshooting\n\n### SOPS or age is missing\n\n```bash\nbrew install sops age\n```\n\n### The key does not match this repository\n\nRun:\n\n```bash\nhush keys setup\n```\n\n### You need to convert a legacy repo\n\nRun:\n\n```bash\nhush migrate --from v2\n```\n\nAdd `--cleanup` after you validate the migrated state.\n\n## License\n\nMIT\n",
"bytes": 8467,
"sha": "a37317ff068cebd07a5f0cad9ab6532a1caa718945ee5e6e951ae7c115013590",
"repo_slug": "ch5me/hush",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/okf_ch5me_hush_openwiki_index_md_58dd98aa/readme"
}