dotenvz

Cross-platform CLI for secure environment injection via the OS secret store.

dotenvz is a Rust CLI that stores your project's environment variables in a secret backend and injects them into child processes at runtime. It has no runtime dependency on .env files — those are used only during initial import/bootstrap.

OS providers (default, zero-config):

Platform	Secret backend
macOS	iCloud Keychain / Passwords.app (macos-passwords, default) or local-only login Keychain (macos-keychain)
Linux	Secret Service via D-Bus (secret-service crate)
Windows	Credential Manager (windows-sys Win32 API)

---

Key principle

The OS secret store is the source of truth. .env files are for bootstrapping only.

---

Scope

• Rust-based CLI binary
• macOS, Linux, and Windows — each backed by the native secret store

• Per-project config via .dotenvz.toml
• dotenvz init auto-detects the current OS and writes the correct provider value
• Named command aliases with automatic env injection (dotenvz dev, dotenvz build)
• Explicit exec mode: dotenvz exec -- <command> [args...]
• One-time import from .env into the secret store (dotenvz import)

Non-goals

• Shell hooks (.bashrc, .zshrc integration)
• Node.js runtime import integration
• Docker secret bridge
• Biometric / auth customization
• VS Code extension integration
• Team sharing / syncing secrets between developers
• Encrypted file storage as a runtime secret store

---

Installation

Pre-built binaries (recommended)

Download the archive for your platform from the latest GitHub Release:

Platform	Archive
macOS — Apple Silicon	dotenvz-{version}-aarch64-apple-darwin.tar.gz
macOS — Intel x86_64	dotenvz-{version}-x86_64-apple-darwin.tar.gz
Linux — x86_64	dotenvz-{version}-x86_64-unknown-linux-gnu.tar.gz
Windows — x86_64	dotenvz-{version}-x86_64-pc-windows-msvc.zip

Each archive contains both the dotenvz and dz binaries. A .sha256 sidecar is provided for integrity verification:

# macOS / Linux
tar -xzf dotenvz-{version}-{target}.tar.gz
sha256sum -c dotenvz-{version}-{target}.tar.gz.sha256
sudo mv dotenvz dz /usr/local/bin/

Build from source

cargo install --path .

---

Configuration

Place a .dotenvz.toml in your project root. Run dotenvz init to scaffold one:

project = "my-app"
provider = "macos-passwords"
default_profile = "dev"
schema_file = ".env.example"
import_file = ".env"

[commands]
dev   = "next dev"
build = "next build"
start = "next start"
test  = "cargo test"

Field	Description
project	Unique identifier used as the secret namespace
provider	Secret backend — "macos-passwords" (macOS default, iCloud Keychain / Passwords.app with local fallback), "macos-keychain" (local-only login Keychain), "linux-secret-service", or "windows-credential" (auto-set by dotenvz init)
default_profile	Profile used when --profile is not specified
schema_file	Path to a file listing expected keys (future validation)
import_file	.env file used by dotenvz import
[commands]	Named aliases: dotenvz <name> → command string with env injected

---

Commands

# Scaffold .dotenvz.toml
dotenvz init

# Import from .env into Keychain (one-time bootstrap)
dotenvz import
dotenvz import --file .env.staging

# Manage secrets
dotenvz set DATABASE_URL postgres://localhost/mydb
dotenvz get DATABASE_URL
dotenvz list
dotenvz rm DATABASE_URL

# Run a command with secrets injected
dotenvz exec -- next dev
dotenvz exec -- cargo run -- --port 8080

# Use a named alias from [commands]
dotenvz dev
dotenvz build
dotenvz test

Override the profile for any command:

dotenvz --profile production list
dotenvz --profile staging exec -- ./deploy.sh

---

How secrets are stored

Secrets are isolated by project and profile, so DATABASE_URL can coexist safely across dev, staging, and production on all platforms.

macOS — iCloud Keychain / Passwords.app (macos-passwords)

Secrets are stored as synchronizable Generic Password items, making them visible in the macOS Passwords app and synced via iCloud Keychain across your devices. If iCloud is unavailable the provider falls back to the local login Keychain silently.

Keychain attribute	Value
Service (kSecAttrService)	dotenvz.<project>.<profile>
Account (kSecAttrAccount)	The env key (e.g. DATABASE_URL)
Password (kSecValueData)	The env value (UTF-8)
Synchronizable (kSecAttrSynchronizable)	true (iCloud sync)

macOS — Local Keychain only (macos-keychain)

Set provider = "macos-keychain" to store in the local login Keychain only (no iCloud sync). Layout is identical to macos-passwords minus the synchronizable flag.

Linux — Secret Service (D-Bus / GNOME Keyring / KWallet)

Each secret is stored as an item in the default collection with these attributes:

Item attribute	Value
application	dotenvz
project	The project name
profile	The active profile
key	The env key
Secret value	The env value (UTF-8)

Note: A running Secret Service daemon (e.g. gnome-keyring-daemon or kwallet) is required. dotenvz exits with a clear error if D-Bus is unavailable.

Windows — Credential Manager

Credential attribute	Value
Type	CRED_TYPE_GENERIC
TargetName	dotenvz/<project>/<profile>/<key>
CredentialBlob	The env value (UTF-8)
Persist	CRED_PERSIST_LOCAL_MACHINE

---

Project structure

src/
  main.rs              — entry point + provider wiring
  cli.rs               — clap command definitions
  errors.rs            — central error type
  commands/            — one file per CLI command
  config/              — .dotenvz.toml model + loader
  core/                — project context, resolver, process runner
  providers/
    secret_provider.rs    — SecretProvider trait
    macos_passwords.rs    — macOS iCloud Keychain / Passwords.app (default)
    macos_keychain.rs     — macOS local login Keychain
    linux_secret_service.rs — Linux Secret Service (D-Bus)
    windows_credential.rs   — Windows Credential Manager (Win32)
    mock.rs               — in-memory backend for tests
<!--
    exec.rs            — custom exec provider (JSON subprocess protocol)
    aws_secrets_manager.rs  — AWS Secrets Manager
    gcp_secret_manager.rs   — Google Cloud Secret Manager
    azure_key_vault.rs      — Azure Key Vault
-->
tests/
  fixtures/            — sample config and .env for tests
  integration_test.rs

---

Releasing

For maintainers only.

1. Bump version in Cargo.toml (follows SemVer)
2. Update CHANGELOG.md locally using git-cliff:

git cliff --unreleased --prepend CHANGELOG.md

Edit the generated entries if needed, then commit everything:

git add Cargo.toml CHANGELOG.md
git commit -m "docs: update CHANGELOG.md for v0.2.0"
git push

3. Create and push a tag matching the new version:

git tag v0.2.0
git push origin v0.2.0

The tag push triggers the release workflow, which builds native binaries for all 7 platforms in parallel, generates the GitHub Release body from the tag's commits via git-cliff, and publishes a single GitHub Release with all archives and SHA256 checksums.

The version field in Cargo.toml is the single source of truth — the git tag must match it prefixed with v.

---

Documentation

Document	Description
docs/ARCHITECTURE.md	Full architecture, module map, execution flow, provider categories
docs/OS_PROVIDERS_OVERVIEW.md	Overview of all three OS providers and how they compare
docs/PROVIDER_SPEC_MACOS.md	macOS Keychain provider — storage layout, operation flow, error handling
docs/PROVIDER_SPEC_LINUX.md	Linux Secret Service provider — D-Bus, GNOME Keyring, KWallet
docs/PROVIDER_SPEC_WINDOWS.md	Windows Credential Manager provider — Win32 Cred* API
docs/IMPLEMENTATION_GUIDE.md	Implementation notes, security considerations, testing approach
docs/TEST_PLAN.md	Test plan covering unit, integration, and platform smoke tests