Your org uses AWS SSM for infra credentials, 1Password for team secrets, and Vault for service tokens. Every developer has a slightly different .env file assembled from manual fetches across all three. New engineers spend their first day asking where things live. Offboarding is a manual checklist nobody fully trusts. Migrating from one backend to another means touching every repo.

Every existing tool assumes it is your only secrets backend. You have three. Or four. Or five.

SecretEnv runs any command with secrets injected as environment variables, sourced from whatever combination of backends your team already uses — without storing, encrypting, or managing any secrets itself. Instead, it orchestrates your existing backends through an alias registry that lives in your own backend: name your secrets once in the project manifest, change where the alias points to update every repo on its next run. No PRs. No re-encryption. No coordination.

secretenv run -- npm start
secretenv run --registry dev -- python manage.py runserver
secretenv run --registry staging -- docker compose up

Secrets are fetched at runtime, injected into the child process, and gone when it exits. No secret values written to disk.

SecretEnv is a coat of paint. If the walls aren't strong, the paint is useless. The walls are your backends. SecretEnv is not a security product — it's a workflow product that removes the most common vectors for secrets-in-git and secrets-on-disk. Auth, encryption, and storage stay where they already are.

SecretEnv separates three things every other tool conflates. Three files, three owners, three lifecycles.

The manifest tells SecretEnv what is needed. The registry tells SecretEnv where things live. The machine config tells SecretEnv which backends exist on this machine. Reading the repo teaches you nothing about backend topology, because topology never enters the repo.

For the file-by-file breakdown with full schemas, see docs/reference/three-file-model-deep.md.

Every repo commits a secretenv.toml declaring which secrets it needs — using alias names, not backend paths. Zero infrastructure information.

# secretenv.toml — committed to git
[secrets]
STRIPE_KEY      = { from = "secretenv://stripe-key" }
DATABASE_URL    = { from = "secretenv://db-url" }
DATADOG_API_KEY = { from = "secretenv://datadog-api-key" }
LOG_LEVEL       = { default = "info" }

Two value shapes only — secretenv:// aliases or static defaults. Direct backend URIs are a hard error.

A document stored in any backend your team already controls, mapping alias names to fully-qualified backend URIs:

# stored in aws-ssm-platform:///secretenv/registry
# managed via: secretenv registry set/unset/list

stripe-key      = "1password-work://payments/stripe/api_key"
db-url          = "aws-ssm-dev:///myapp/dev/db_url"
datadog-api-key = "1password-work://engineering/datadog/api_key"
redis-url       = "aws-ssm-dev:///myapp/dev/redis_url"

Change a backend? Update one line in the registry. Every repo picks it up automatically on the next run. The registry lives in a backend you already control so you can manage it with the access controls, audit trails, and versioning you already trust — no new tool, no new infrastructure.

Each developer's machine holds the credential topology — which named backend instances exist, where each registry lives. This file never touches a repo.

# ~/.config/secretenv/config.toml

[registries.default]
sources = ["aws-ssm-platform:///secretenv/org-registry"]

[registries.dev]
sources = [
  "aws-ssm-dev:///secretenv/dev-registry",       # team aliases, checked first
  "aws-ssm-platform:///secretenv/org-registry",  # org-wide fallback
]

[registries.prod]
sources = ["aws-ssm-prod:///secretenv/prod-registry"]

[backends.aws-ssm-platform]
type        = "aws-ssm"
aws_profile = "platform"
aws_region  = "us-east-2"

[backends.aws-ssm-dev]
type        = "aws-ssm"
aws_profile = "dev"
aws_region  = "us-east-1"

[backends.aws-ssm-prod]
type        = "aws-ssm"
aws_profile = "prod"
aws_region  = "us-east-1"

[backends.1password-work]
type       = "1password"
op_account = "company.1password.com"

This is Workflow 2's wiring. Same alias names across all three registries. --registry dev vs --registry prod routes the same secretenv.toml to env-specific backend instances. The manifest never sees env-specific paths.

Platform teams distribute this file across an org with profiles — one HTTPS-hosted TOML, one install command per developer.

secretenv run --registry dev -- npm start

  secretenv.toml          alias registry              backends
  ──────────────          ──────────────              ────────
  STRIPE_KEY              stripe-key               1Password (work account)
    └─ secretenv:// ────►   └─ 1password-work:// ──► op read ...
  DATABASE_URL            db-url                   AWS SSM (dev account)
    └─ secretenv:// ────►   └─ aws-ssm-dev://   ──► aws ssm get-parameter --profile dev
  LOG_LEVEL               (static default)
    └─ "info" ──────────────────────────────────────► injected directly

  All resolved → fetched in parallel → injected into process env → npm start

Resolution is all-or-nothing per invocation: if any required alias fails to resolve, the child process never starts. Partial environments are never injected.

# macOS
brew install secretenv

# Linux / macOS (universal)
curl -sfS https://secretenv.io/install.sh | sh

# Cargo
cargo install secretenv

secretenv setup aws-ssm:///secretenv/registry --region us-east-1

# ✓ Registry configured as [registries.default]
# ✓ Registry reachable: 12 aliases found
# ✓ AWS credentials detected (profile: default)

secretenv doctor

# ── Registries ───────────────────────────────────────────────────────
#   default
#     ✓ aws-ssm:///secretenv/registry    reachable via aws-ssm
#
# ── Backends ─────────────────────────────────────────────────────────
#   aws-ssm             (aws-ssm)
#     ✓ aws CLI v2.34.35
#     ✓ authenticated  profile=default  account=123456789  region=us-east-1

[secrets]
STRIPE_KEY   = { from = "secretenv://stripe-key" }
DATABASE_URL = { from = "secretenv://db-url" }
LOG_LEVEL    = { default = "info" }

secretenv run -- npm start

These are the day-to-day workflows SecretEnv was built for.

The platform team published acme-corp.toml once to an internal HTTPS host. Onboarding is now two commands:

# 1. Install the binary
brew install secretenv     # or: curl -sfS https://secretenv.io/install.sh | sh

# 2. Install your team's profile (your platform team owns + hosts this)
secretenv profile install acme-corp \
  --url https://internal.acme.com/secretenv/acme-corp.toml

# 3. Verify
secretenv doctor

Clone any repo, run secretenv run -- npm start. Done. The profile carries every backend instance and registry source the team has converged on — no copy-paste from a wiki page, no Slack thread asking where Stripe lives. Publish the profile once; every dev gets it via one command. Updating org-wide credential topology later is secretenv profile update on the developer's machine — the platform team never logs into anyone else's laptop.

Same secretenv.toml works across dev, staging, and prod. The registry cascade routes the same alias names to different backend instances per environment.

# Same project, same manifest, same code path.
# Only the registry selection changes.

secretenv run --registry dev     -- ./deploy.sh
secretenv run --registry staging -- ./deploy.sh
secretenv run --registry prod    -- ./deploy.sh

Each registry maps db-url, stripe-key, api-key to env-specific backends. Your repo never knows which AWS account or which Vault namespace it's running against.

Stripe key needs to move from 1Password to Vault. Today the flow is two steps:

# Before: stripe-key lives in 1Password
secretenv registry get stripe-key
# stripe-key → 1password-work://payments/stripe/api_key

# After moving the value from 1Password to Vault (using your existing tools):
secretenv registry set stripe-key "vault-prod://secret/payments/stripe_key"

# Every repo picks this up on the next secretenv run.
# No PRs. No re-encryption. No coordination.

Coming in v0.14 — secretenv registry migrate. Today's flow is two steps: move the value to the new backend with your existing tooling, then registry set to repoint the alias. The next release folds both into one operation — read from the current backend, write to the new one (where you have write permission), update the pointer atomically. Exact CLI shape is being figured out now; the indirection guarantee doesn't change — repos still inherit on next run.

Revoke the departing engineer's access to the registry backend. One operation in IAM, Vault, or 1Password. Done.

They can no longer resolve any alias. They can no longer fetch any secret via SecretEnv. The revocation is immediate and covers every repo simultaneously — no re-encryption, no manual checklist, no "did we get all of them."

This is where SecretEnv earns its keep. Real organizations have multiple AWS accounts, multiple credential sets, and multiple backend tools. Named backend instances handle this without new plugins or new concepts — just configuration.

# Three AWS accounts — one plugin, three named instances
[backends.aws-ssm-platform]   # type = "aws-ssm", aws_profile = "platform", aws_region = "us-east-2"
[backends.aws-ssm-dev]        # type = "aws-ssm", aws_profile = "dev",      aws_region = "us-east-1"
[backends.aws-ssm-prod]       # type = "aws-ssm", aws_profile = "prod",     aws_region = "us-east-1"

# Two 1Password accounts
[backends.1password-work]      # type = "1password", op_account = "company.1password.com"
[backends.1password-personal]  # type = "1password", op_account = "personal.1password.com"

Registry entries reference named instances as their URI scheme:

# dev registry — aliases point to dev account
db-url     = "aws-ssm-dev:///myapp/dev/db_url"
stripe-key = "1password-work://payments/stripe/dev_key"

# prod registry — same alias names, different backends
db-url     = "aws-ssm-prod:///myapp/prod/db_url"
stripe-key = "1password-work://payments/stripe/prod_key"

Alias names stay identical across environments. The registry routing handles the rest. Same pattern scales to all 15 backends.

# Use [registries.default] from config
secretenv run -- npm start

# Use a named registry from config
secretenv run --registry dev -- npm start

# Use a direct URI — single source, no cascade
secretenv run --registry aws-ssm-dev:///secretenv/registry -- npm start

The --registry flag accepts either a name (looks up [registries.<name>] in config) or a direct URI (uses that document, no cascade). The same disambiguation applies to the SECRETENV_REGISTRY environment variable — the canonical mechanism for CI.

Registry selection precedence:

1. --registry <name-or-uri>          ← explicit per-invocation
2. SECRETENV_REGISTRY=<name-or-uri>  ← CI / shell-session override
3. [registries.default] in config    ← machine default
4. hard error                        ← no assumption made

A named registry can cascade across multiple sources. First match wins. Use this for team-specific aliases that shadow org-wide defaults.

[registries.dev]
sources = [
  "aws-ssm-dev:///secretenv/dev-registry",       # team aliases — checked first
  "aws-ssm-platform:///secretenv/org-registry",  # org-wide fallback
]

stripe-key in the dev registry shadows stripe-key in the org registry. Org-wide entries that exist only in the fallback resolve transparently. Writes always go to sources[0].

SecretEnv works in CI via the SECRETENV_REGISTRY environment variable. Set it once at the org or repo level — no config file needed on the runner.

# GitHub Actions
jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions: { id-token: write }
    steps:
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/github-actions-role
          aws-region: us-east-1

      - name: Install secretenv
        run: curl -sfS https://secretenv.io/install.sh | sh

      - name: Run with secrets
        env:
          SECRETENV_REGISTRY: aws-ssm:///secretenv/registry
        run: secretenv run -- ./deploy.sh

In CI you're not authenticating SecretEnv — you're authenticating the backend CLI. Set up the backend CLI's service account credentials the same way you would if you were calling it directly. SecretEnv adds no auth layer.

Adopting SecretEnv at scale follows a predictable rollout sequence. Each stage is independently reversible.

1. Discovery. Inventory existing secret backends. Identify a registry-host candidate (any backend the platform team controls and every engineer can reach — AWS SSM, Vault, 1Password, Cloudflare KV).
2. Pilot. One team, one registry, hand-written config.toml. Validate end-to-end with secretenv doctor --extensive.
3. Author the org profile. Publish a single acme-defaults.toml to an HTTPS-reachable host (CDN, internal artifact store, or secretenv.io/profiles). Profiles are TOML fragments containing [registries.*] and [backends.*] blocks.
4. Org-wide install. Distribute the one-line installer; new joiners get the correct config from minute one. Local config always wins where keys overlap, so a profile can never silently break a developer's workflow.
5. CI integration. Set SECRETENV_REGISTRY at org-level CI variable scope. Add secretenv doctor --json as a pre-deploy gate.
6. Offboarding playbook. Codify "revoke registry-backend access" in your IAM runbook. One operation; covers every repo.

Profile rollback is a profile re-publish + secretenv profile update on the fleet — there is no server-pushed update channel; the developer pulls.

Profiles are how a platform team converges every dev machine to the team's intent without touching individual machines.

# Install or re-install with updated metadata
secretenv profile install acme-corp --url https://internal.acme.com/secretenv/acme-corp.toml

# Update — ETag-conditional re-fetch; reports up-to-date or refreshed
secretenv profile update

# List + uninstall
secretenv profile list
secretenv profile uninstall acme-corp

Profiles are additive merges, never overrides — local config.toml always wins. Self-hosted / air-gapped orgs override the canonical base via SECRETENV_PROFILE_URL. Hard size cap of 1 MiB per profile guards against compromised distributions. Full guide: docs/reference/profiles.md.

secretenv doctor is the front door for everything operational — onboarding validation, CI pre-deploy gates, on-call diagnostics. It runs three levels of checks, all in parallel.

secretenv doctor              # default (L1 + L2)
secretenv doctor --json       # machine-readable for CI / monitoring
secretenv doctor --fix        # interactive remediation (aws sso login, op signin, vault login, ...)
secretenv doctor --extensive  # deep probe — exercises registry reads

Exit code is non-zero if any backend reports anything other than Ok. doctor --json is designed to run in under 2s wall-clock for a 10-backend topology and is suitable as a CI pre-deploy gate or a per-minute monitoring probe.

• Resolution is all-or-nothing per invocation. If any required alias fails to resolve, the child process never starts. Partial environments are never injected.
• No on-disk cache. Every run hits live backends. Deliberate — no stale-cache class of bug, no key material between runs.
• Failure modes report cleanly. BackendUnauthenticated, AliasNotFound, RegistryUnreachable, BackendCliMissing are the four operationally interesting failure shapes; each carries enough context to triage without re-running.
• Logging. RUST_LOG=secretenv=debug emits structured logs to stderr. --verbose on run emits per-secret fetch progress.

Every backend tool claims stability. SecretEnv proves it.

The smoke harness exercises the real binary against real backend CLIs in real shells — not mocks, not contract tests. Every assertion validates: spawn the CLI, route input via tempfile or stdin, parse stdout, handle stderr, observe exit code. 508 assertions across 15 backends as of v0.13.0.

In the v0.13 cycle, this harness caught a latent pipe-deadlock in the Infisical backend that had survived 15 days and 6 release cycles since Infisical shipped in v0.7.0. CI was green every release. Unit tests passed. Three-agent audits passed. Only the live-backend smoke — running the real binary against the real CLI in a real shell — surfaced it. The fix was one line; the lesson was the harness.

Test surface grew with feature surface across ~3 weeks of single-backend-per-minor-release cadence. That's the boring-by-design property platform teams buy.

SecretEnv delegates all authentication to each backend's native CLI. The version column below is what the v0.13.0 release smoke ran against.

Click any backend for its per-backend doc page — configuration, URI format, authentication, doctor output, examples. Or browse the backend index for the full table with selection guidance.

The URI scheme is your named instance. Multiple instances of the same backend type — for multiple accounts, multiple vaults, or multiple credential sets — are configured in config.toml and referenced by their instance name.

SecretEnv never calls cloud APIs directly. Every fetch is a shell-out to the native CLI. This means SecretEnv inherits your MFA, SSO, biometric unlock, and any other auth your backend requires — with no new authentication surface to audit.

# run — primary use case
secretenv run [--registry <name-or-uri>] [--dry-run] [--verbose] -- <command>

# registry — alias CRUD + history + onboarding helpers
secretenv registry list    [--registry <name-or-uri>]
secretenv registry get     <alias>  [--registry <name-or-uri>]
secretenv registry set     <alias> <backend-uri>  [--registry <name-or-uri>]
secretenv registry unset   <alias>  [--registry <name-or-uri>]
secretenv registry history <alias>  [--registry <name-or-uri>] [--json]
secretenv registry invite  [--registry <name-or-uri>] [--invitee <id>] [--json]

# profile — distribute team config fragments via HTTPS
secretenv profile install   <name> [--url <url>]
secretenv profile list      [--json]
secretenv profile update    [<name>]
secretenv profile uninstall <name>

# doctor — three-level health checks (L1 CLI + L2 auth + L3 read)
secretenv doctor [--json] [--fix] [--extensive]

# setup — bootstrap config wizard
secretenv setup <registry-uri> [--region R] [--profile P] [--account A] [--vault-address ...] [--force] [--skip-doctor]

# completions, resolve, get
secretenv completions <bash|zsh|fish> [--output <path>]
secretenv resolve <alias> [--registry <name-or-uri>]
secretenv get <alias> [--registry <name-or-uri>] [--yes]

Global flag: --config <path> (defaults to $XDG_CONFIG_HOME/secretenv/config.toml)

Environment variables:

SECRETENV_REGISTRY=<name-or-uri>   # registry override — primary CI mechanism
SECRETENV_PROFILE_URL=<base-url>   # override the default profile fetch base
RUST_LOG=secretenv=debug           # structured logging (default: secretenv=warn)

All commands are available as of v0.13.0. Full per-flag reference + exit codes: docs/reference/cli-reference-full.md.

¹ fnox is multi-mode. Age mode keeps an age private key on disk; KMS modes (aws-kms / azure-kms / gcp-kms) gate decryption on IAM and have no persistent disk key. SecretEnv's distinction is orthogonal to encryption: the alias-registry layer removes backend topology from every repo. See docs/comparisons/vs-fnox.md for the mode-by-mode breakdown.

• .env files — Manual, error-prone, accumulate stale values, get committed accidentally, sit on disk in plaintext, make offboarding a checklist nobody fully trusts. This is the workflow SecretEnv replaces. Full: docs/comparisons/vs-dotenv.md.
• fnox — A thoughtful multi-mode tool covering age-encryption, KMS-gated decryption, and cloud references. In KMS modes, fnox closes the persistent-key + offboarding concerns at the KMS-key level. SecretEnv's distinction is orthogonal: an alias-registry layer above the backend that decouples repos from backend URIs entirely. Migrating a secret in fnox (any mode) means editing every fnox.toml; in SecretEnv it's one registry set. Full: docs/comparisons/vs-fnox.md.
• direnv — Shell-hook model requires writing custom glue per project. Backend integration is manual scripting. Paths live in .envrc files. No standard for what a project needs or where things live. Full: docs/comparisons/vs-direnv.md.

Per-tool deep dives for op run / doppler run / Pulumi ESC / External Secrets Operator / sops / Vault Enterprise + Conjur as identity platforms: see the docs/comparisons/ directory.

Pick SecretEnv if:

• Your team uses 2+ secret backends and wants a unified onboarding/offboarding story
• You want infrastructure topology hidden from your repos (no AWS account IDs, no Vault namespaces in code)
• You've experienced backend migrations and want to avoid touching N microservices next time
• You want to avoid SaaS gates for a core workflow tool
• You operate across local dev + ephemeral CI + persistent CI, and want one tool for all three

Pick something else if:

• You're committed to a single backend long-term — the single-backend wrappers (op run, doppler run, infisical run) are simpler and more deeply integrated with their UIs
• Your entire deployment is Kubernetes — External Secrets Operator has tighter in-cluster integration
• You need a hosted policy engine, hosted audit trail, or rotation orchestration as a service — Pulumi ESC, Vault Enterprise, or CyberArk Conjur are purpose-built for that
• You need at-rest file encryption for gitops workflows — sops owns that category
• You want client-side encryption with KMS-gated decryption stored in committed config — fnox in KMS mode is purpose-built for that

SecretEnv is not a security product. It is a workflow product that removes the most common vectors for secrets-in-git and secrets-on-disk — the failures that happen at scale.

The model is simple: SecretEnv has no credential storage, no login command, and no auth surface of its own. If your backend is authenticated, SecretEnv works. If it isn't, SecretEnv fails with the same error the native CLI would give you. Fix it there.

• Secrets committed to git accidentally — eliminated; nothing to commit.
• Secret values sitting on disk in plaintext — eliminated; nothing written.
• Infrastructure paths exposed in repos — eliminated; aliases only.
• Manual offboarding gaps — one backend access revocation covers everything.
• Backend lock-in — registry update migrates every repo simultaneously.
• Stale secrets — fetched on every invocation; rotation is transparent on next run (subject to backend caching).

• Machine compromise — if the machine is owned, active backend sessions are inherited. This is true for every secrets tool. The real defense is credential scoping at the backend level.
• Post-injection process exposure — once secrets are injected as env vars, they are readable by any process running as the same user. This is a property of the env-var model, not a SecretEnv issue.
• Runtime production injection — for ECS / Lambda / Kubernetes, the platform-native injection mechanisms are the right answer. SecretEnv is for local dev + CI + general-purpose runtime.
• Encryption at rest. SecretEnv stores no secret values, so it provides no encryption-at-rest property. Encryption at rest is the responsibility of whichever backend holds the value (Vault's storage encryption, SSM SecureString + KMS, 1Password's E2E vault). Tools like fnox (KMS modes) and sops do provide ciphertext-in-repo and are the right answer if that's the property you need.
• Policy engines, audit log services, rotation orchestration — these belong to your backend (or a dedicated identity platform). SecretEnv routes to them; it does not replace them.

• No decryption surface at all. SecretEnv neither holds nor needs a decryption key — it has nothing encrypted to decrypt. This is a structural property of being a router, not a security feature we engineered. Tools that gate decryption on cloud IAM (fnox-KMS, op-run, doppler-run) achieve comparable containment a different way.
• No secret values written to disk. In-memory secrets use zeroize::Zeroizing and are zeroed on drop.
• No secrets in CLI argv. Every backend uses safe stdin / tempfile forms (-f /dev/stdin, value=-, mode-0600 tempfiles). Unsafe argv forms are gated behind opt-in <backend>_unsafe_set flags and emit warnings on every use.
• Control-character validation on URIs. NUL and ASCII <0x20 (except tab) are rejected at parse time; stops a class of injection-via-registry attacks.
• Manifest VCS-sentinel boundary. The upward walk for secretenv.toml stops at .git/.hg/.svn/.secretenv-root. Prevents a hostile parent directory from hijacking resolution.
• Registry-write determinism. Writes use BTreeMap ordering — clean diffs make registry tampering reviewable in PRs.
• CLI version pinning. Backends validate the wrapped CLI's version (e.g., Conjur v7 is rejected; only v8 accepted) — incompatible CLIs surface as clear errors, not silent corruption.

The honest line: encryption posture is comparable across SecretEnv and fnox-KMS-mode. The differentiator is alias indirection — SecretEnv's registry decouples the alias from the backend URI so a migration is one registry set instead of editing every config. That property is orthogonal to encryption.

A 14-category threat-model comparison across .env, direnv, op run, doppler run, fnox, and SecretEnv lives in docs/security.md. For responsible disclosure, see SECURITY.md.

The core is an SDK. It parses secretenv.toml, resolves --registry to a source list, fetches registry documents, resolves aliases, fetches secret values in parallel, and injects them into the child process. The core never knows about AWS, Vault, 1Password, or any specific backend — it only speaks the trait interface.

Every backend is an independent Rust crate in crates/backends/ implementing two traits defined in secretenv-core. Adding a new backend is a new crate plus one line of factory registration — never a change to core. All 15 backends compile into the single binary; no feature flags. The presence (or absence) of [backends.<name>] in config.toml determines which backends are active at runtime.

For the trait interface and step-by-step backend-development guide: docs/reference/adding-a-backend.md.

SecretEnv is built in Rust and welcomes contributions. The easiest entry point is adding a new backend — each one is a self-contained crate with a focused, well-defined interface.

git clone https://github.com/TechAlchemistX/secretenv
cd secretenv
cargo build
cargo test

See CONTRIBUTING.md for the full guide. Issues tagged good first issue are scoped for first-time contributors.

GNU Affero General Public License v3.0 (AGPL-3.0-only) — see LICENSE.

SecretEnv is free to use, modify, and redistribute under AGPLv3. §13 of the AGPL requires that any network-deployed modified version make its corresponding source code available to its users. If you fork SecretEnv and operate the fork as a service, you must offer its source to your users. Using SecretEnv as a CLI inside your organization — even commercially — is unaffected by §13; it triggers only on network-service deployment of a modified fork.

MIT was the license for v0.1 and v0.2.0. v0.3.0 onward is AGPL-3.0-only.

Contributions are welcome under the project's Contributor License Agreement. The CLA lets the project relicense contributions while keeping your own rights intact. No CLA = no merge.