envhaul

README

Haul config and secrets from AWS into .env files.

---

envhaul generates the .env files for every part of your project from one reviewable config file. Plain values live in the config next to references to AWS SSM Parameter Store and Secrets Manager, which envhaul resolves using your named AWS profiles, across as many accounts as you need.

# envhaul.yaml
name: dev
aws_profile: acme-dev
aws_region: us-east-1
ssm_prefix: /acme/dev

components:
  api:
    env_file: services/api/.env
    vars:
      APP_ENV: development                                       # inline, committed
      STRIPE_SECRET_KEY: "{{ssm:api/STRIPE_SECRET_KEY}}"         # /acme/dev/api/STRIPE_SECRET_KEY
      OPENAI_API_KEY: "{{ssm:api/OPENAI_API_KEY@acme-shared}}"   # another account
      DATABASE_URL: "postgresql://{{secret:acme/dev/db#username}}:{{secret:acme/dev/db#password|urlencode}}@localhost/acme"
  web:
    env_file: web/.env
    vars:
      VITE_API_BASE_URL: "http://localhost:8000"
      VITE_SENTRY_DSN: "{{ssm:api/SENTRY_DSN@acme-shared|default:}}"

$ envhaul sync
wrote  services/api/.env  (4 vars)
wrote  web/.env           (2 vars)

Features

• One config, every component. API, frontend, infrastructure and tooling each get their own .env, in variable order, from one file you can review.
• Secrets stay in AWS. Only references are committed. Generated files are written atomically with mode 0600, and values never appear in logs.
• Named profiles and multiple accounts. Each reference can name its own profile. SSO, assume-role and credential_process all work.
• Templates and pipes. Build connection strings from several secrets, and apply urlencode, trim, base64, default: and more.
• Safe workflows. validate checks the config offline with file:line:col errors, diff previews changes with values masked, and exec runs a command without writing secrets to disk.
• Fast. Each value is fetched once per run, SSM reads are batched, and requests run concurrently.

Install

brew install davidtucker/tap/envhaul                       # macOS, Linux
scoop bucket add davidtucker https://github.com/davidtucker/scoop-bucket && scoop install envhaul  # Windows
go install github.com/davidtucker/envhaul/cmd/envhaul@latest
curl -fsSL https://raw.githubusercontent.com/davidtucker/envhaul/main/install.sh | sh   # verifies checksums and signatures
docker run --rm ghcr.io/davidtucker/envhaul --help

deb, rpm and apk packages and archives for every platform are on the releases page.

Quick start

envhaul init        # write a starter envhaul.yaml and git-ignore .env
envhaul validate    # check it offline
envhaul list        # show where every value comes from
envhaul diff        # preview changes (values masked)
envhaul sync        # write the .env files

Command	What it does
sync [component...]	Resolve values and write env files (--strict fails on missing values)
diff [component...]	Show what would change; --show-values, --exit-code
get <component> <VAR>	Print one resolved value
exec <component> -- cmd	Run a command with the values in its environment, without writing a file
list [component...]	Show each variable's source (offline, --json)
validate	Check the config (offline)
init	Create a starter config

Reference syntax

{{ scheme:path [#key] [@profile] [| fn[:arg]]... }}

Example	Reads
{{ssm:api/KEY}}	SSM parameter api/KEY, joined onto ssm_prefix
{{ssm:/abs/path:3}}	SSM parameter at an absolute path, version 3
{{secret:db}}	The whole Secrets Manager secret
{{secret:db#password}}	One key of a JSON secret
{{ssm:api/KEY@shared}}	Using the shared AWS profile
{{secret:db#pass|urlencode}}	URL-encoded, e.g. for connection strings
{{ssm:opt|default:fallback}}	fallback when missing or empty

Pipes: urlencode, base64, base64decode, trim, lower, upper, default:value. See the reference guide.

Documentation

Full documentation is at davidtucker.github.io/envhaul:

• Configuration
• AWS profiles and permissions, including a least-privilege IAM policy
• Using envhaul in CI
• Security model and verifying releases

How it fits with other tools

envhaul focuses on one job: a reviewable, per-component map from variable names to values in AWS, resolved across accounts with your own profiles and written as .env files. It works alongside credential managers such as aws-vault, and differs from tools that encrypt secrets in the repository (sops) or sync them through a hosted service. See the FAQ for details.

Versioning

envhaul follows Semantic Versioning. From v1.0.0, config files with version: 1, command-line flags and --json output stay compatible across every v1.x release; deprecations warn for at least one minor release first. See the changelog.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md and the Code of Conduct. Want another secret store? Open a new source proposal.

Report security issues privately; see SECURITY.md.

License

Apache License 2.0