Skip to content
Hush

Configuration

Hush v3 stores repository authority under .hush/. There is no plaintext config tier for the repo structure.

Start with bootstrap

Terminal window
hush bootstrap

That creates the initial v3 layout:

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

It also writes machine-local state at:

~/.hush/state/projects/<project-slug>/active-identity.json

Repository structure

Manifest

.hush/manifest.encrypted holds the structural config for the repo.

The first bootstrap pass creates:

  • identities: owner-local, member-local, ci
  • bundle shell: project
  • target shells: runtime, example

Example shape:

version: 3
identities:
  owner-local:
    roles: [owner]
  member-local:
    roles: [member]
  ci:
    roles: [ci]
bundles:
  project:
    files:
      - path: env/project/shared
targets:
  runtime:
    bundle: project
    format: dotenv
    mode: process
  example:
    bundle: project
    format: dotenv
    mode: example

Files

Each file under .hush/files/**.encrypted is one ACL boundary.

The bootstrap pass creates one shared file shell:

path: env/project/shared
readers:
  roles: [owner, member, ci]
  identities: []
sensitive: true
entries: {}

Inspect the structure

Use hush config show to inspect structural state.

Terminal window
hush config show
hush config show identities
hush config show files
hush config show state

Available sections:

  • manifest
  • identities
  • bundles
  • targets
  • imports
  • files
  • state

Active identity

Hush v3 uses an explicit machine-local active identity pointer.

Show the current identity:

Terminal window
hush config active-identity

Switch identities:

Terminal window
hush config active-identity member-local
hush config active-identity ci

Bootstrap sets the initial active identity to owner-local.

File readers

Update file-scoped readers with hush config readers.

Terminal window
hush config readers env/project/shared --roles owner,member,ci
hush config readers env/project/shared --identities owner-local,member-local
hush config readers env/project/shared --roles owner,ci --identities ci

Rules for the first pass:

  • --roles updates role-based readers
  • --identities updates explicit identity readers
  • Omitted flags keep the existing value
  • The file path must match a declared .hush/files/**.encrypted document

Deprecated init alias

hush init is no longer the canonical setup flow.

Terminal window
hush init

It now prints a deprecation warning and delegates to hush bootstrap.

Legacy note

Legacy hush.yaml repositories still exist for migration work, but the canonical setup path is now .hush/ plus hush config.

Migrate a legacy repo

Use the big-bang migration flow when a repo still depends on hush.yaml.

Terminal window
hush migrate --from v2 --dry-run
hush migrate --from v2
hush migrate --from v2 --cleanup

The flow is intentionally one-way inside a repository:

  1. --dry-run inventories the legacy repo without mutating it
  2. hush migrate --from v2 creates .hush/ v3 state and machine-local migrated overrides
  3. --cleanup removes validated legacy leftovers such as hush.yaml and old encrypted source files

For the full migration walkthrough, see the migration guide for legacy hush.yaml repositories.