File Reference

This page documents all files that Hush creates, reads, and manages.

Tip

With Hush’s “encrypted at rest” model, secrets are never written to disk during normal use. The hush run command decrypts secrets to memory and injects them as environment variables.

File Overview

File	Committed	Purpose
hush.yaml	Yes	Configuration file
.sops.yaml	Yes	SOPS encryption config
.hush.encrypted	Yes	Encrypted shared secrets
.hush.development.encrypted	Yes	Encrypted development secrets
.hush.production.encrypted	Yes	Encrypted production secrets
.hush.local.encrypted	No	Encrypted personal overrides (not committed)

Configuration Files

hush.yaml

The main configuration file. Defines sources and targets.

sources:
  shared: .hush
  development: .hush.development
  production: .hush.production

targets:
  - name: root
    path: .
    format: dotenv

Location: Repository root
Commit: Yes
Created by: hush init or manually

.sops.yaml

SOPS configuration file. Defines which keys can encrypt/decrypt.

creation_rules:
  - encrypted_regex: '.*'
    age: age1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Location: Repository root
Commit: Yes
Created by: Manually (SOPS requirement)

Source Files (For Initial Setup Only)

These plaintext .hush files are only used during initial setup when you first encrypt your secrets. After running hush encrypt, they are automatically deleted.

Caution

Never commit plaintext .hush files. After initial encryption, use hush edit to modify secrets or hush set <KEY> to add new ones.

.hush

Shared variables used across all environments.

DATABASE_URL=postgres://user:pass@host/db
STRIPE_SECRET_KEY=sk_xxx
EXPO_PUBLIC_API_URL=${API_BASE}/v1

.hush.development

Development-specific overrides.

API_BASE=http://localhost:8787
DEBUG=true

.hush.production

Production-specific overrides.

API_BASE=https://api.example.com
DEBUG=false

.hush.local

Personal overrides for your machine only.

# Add a local override (encrypted)
hush set MY_VAR --local

# Edit all local overrides
hush edit local

This creates .hush.local.encrypted which keeps your personal overrides encrypted too.

Tip

Use hush set <KEY> --local for personal development settings that shouldn’t be shared with the team.

Encrypted Files

These are the SOPS-encrypted versions of your secrets. Safe to commit (except .hush.local.encrypted).

.hush.encrypted

Encrypted shared secrets used across all environments.

Commit: Yes

.hush.development.encrypted

Encrypted development-specific secrets.

Commit: Yes

.hush.production.encrypted

Encrypted production-specific secrets.

Commit: Yes

.hush.local.encrypted

Encrypted personal overrides for your machine only.

Commit: No (add to .gitignore)

---

Created by: hush encrypt, hush set, hush edit
Used by: hush run, hush inspect, hush has, hush edit

Output Files (Generated by decrypt)

Note

Hush’s “encrypted at rest” model means output files are never written to disk during normal operation. With hush run, secrets are decrypted to memory and injected as environment variables—they never touch the filesystem.

The following files should only exist if you’ve run hush decrypt --force:

File	Why It Might Exist
.env / .env.development / .env.production	Created by hush decrypt --force for legacy tools
.dev.vars	Created by hush decrypt --force for Wrangler
.env.*.json / .env.*.sh / .env.*.yaml	Created by hush decrypt --force

If you see these files and didn’t run decrypt --force, they may be from legacy tooling. Hush will warn about them in hush check and hush status.

Typical Project Structure

With the “encrypted at rest” model, your project should look like this:

• .sops.yaml # SOPS config (committed)
• hush.yaml # Hush config (committed)
• .hush.encrypted # Encrypted shared (committed)
• .hush.development.encrypted # Encrypted dev (committed)
• .hush.production.encrypted # Encrypted prod (committed)
• .hush.local.encrypted # Personal overrides (NOT committed)
• Directorypackages/

  • Directoryapp/

    • package.json
  • Directoryapi/

    • package.json
    • wrangler.toml

Note: No plaintext .hush or .env files! Secrets are decrypted to memory by hush run.

Recommended .gitignore

Add these entries to your .gitignore:

# Hush - Plaintext source files (deleted after encrypt)
.hush
.hush.development
.hush.production
.hush.local

# Hush - Personal encrypted overrides (not shared)
.hush.local.encrypted

# Hush - Output files (generated by decrypt --force)
.env
.env.*
.env.*.json
.env.*.sh
.env.*.yaml
.dev.vars
*/.env.*
*/.dev.vars

# Keep encrypted files (these ARE committed)
!.hush.encrypted
!.hush.development.encrypted
!.hush.production.encrypted

Age Key File

SOPS uses age for encryption. Your private key is stored at:

~/.config/sops/age/key.txt

Danger

Never commit your age private key. Store it securely and share it with team members through a secure channel.

Key Format

# created: 2024-01-01T00:00:00Z
# public key: age1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
AGE-SECRET-KEY-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Multiple Keys

For team environments, each member has their own key. All public keys are listed in .sops.yaml:

creation_rules:
  - encrypted_regex: '.*'
    age: >-
      age1alice...,
      age1bob...,
      age1charlie...

Anyone with any of these private keys can decrypt the secrets.