Skip to content
Hush

Getting Started

Get up and running with the current Hush v3 model in a few minutes.

Prerequisites

Hush requires Node.js 18+ and delegates encryption to standard tools.

  1. SOPS
  2. age
  3. direnv for automatic key loading in project shells
Terminal window
brew install sops age direnv

Installation

Terminal window
pnpm add -D @chriscode/hush

Setup

  1. Bootstrap the v3 repository

    Terminal window
    npx @chriscode/hush bootstrap

    This creates the encrypted repository shell, the initial shared file document, and .sops.yaml.

  2. Inspect the bootstrapped state

    Terminal window
    npx @chriscode/hush config show
    npx @chriscode/hush config active-identity

    Use hush config to inspect manifest state, active identity, file readers, and target definitions.

  3. Add your first secret safely

    Terminal window
    npx @chriscode/hush set DATABASE_URL
    npx @chriscode/hush set API_KEY --gui

    The value is written into the encrypted v3 file document. The assistant never needs to read a plaintext env file.

  4. Run your app

    Terminal window
    npx @chriscode/hush run -- npm start

    Hush resolves the selected v3 target, decrypts only for the child process, and cleans up.

  5. Adjust configuration when needed

    Terminal window
    npx @chriscode/hush config show files
    npx @chriscode/hush config readers env/project/shared --roles owner,ci

    hush config is the normal path for inspecting and updating the current repository model.

Current file layout

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

Migrating an older repository

If this repo still uses legacy v2 files, use the migration bridge instead of bootstrapping over it:

Terminal window
npx @chriscode/hush migrate --from v2
npx @chriscode/hush migrate --from v2 --cleanup

Verify your setup

Terminal window
npx @chriscode/hush config show
npx @chriscode/hush inspect

Troubleshooting

”no identity matched any of the recipients”

SOPS cannot find the matching age key.

Terminal window
npx @chriscode/hush keys setup
npx @chriscode/hush config show state

Team repository with existing keys

If the repository already exists, pull or verify the project key first:

Terminal window
npx @chriscode/hush keys setup

Shell completions

Enable tab-completion for hush commands and flags in your shell:

Terminal window
# bash
hush completion bash >> ~/.bashrc && source ~/.bashrc


# zsh
mkdir -p ~/.zsh/completions
hush completion zsh > ~/.zsh/completions/_hush
# Ensure fpath includes ~/.zsh/completions, then: autoload -Uz compinit && compinit


# fish
hush completion fish > ~/.config/fish/completions/hush.fish

See the completion command reference for details.

Next steps