envkit

module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 16, 2026 License: Apache-2.0

README

envkit

Modular secrets provider + dev/runtime environment bootstrapper. One committable manifest describes the shape of a project's secrets — where each value comes from and where it lands on a machine — and envkit sync materializes it anywhere: desktop, headless box, or CI. Values never touch the repo.

providers ──▶ policy ──▶ stores/targets
rbw · bw · aws-sm · generate ·   keyring (Secret Service) · systemd-creds (TPM) ·
detect · check · exec plugins    .env files (monorepo multi-output) · process env
(v0.2: keychain, SSO login)      (v0.3: AF_UNIX broker + systemd LoadCredential)

Adding a provider is ~60 lines of Go plus one registry line — or a standalone envkit-provider-<name> binary with no envkit changes at all. See docs/providers.md.

The manifest (envkit.toml)

One committed file is the whole configuration: the team shares it, and any machine with the referenced providers installed fetches from the same locations. Personal deviations live in the gitignored envkit.local.toml (same shape — store/creds-dir overrides, provider overrides, static extras). ~/.config/envkit/config.toml is optional user defaults; nothing requires it.

version = 1

[providers.aws-sm]             # committed provider settings — the common
profile = "my-team-dev"        # locations everyone reads from
region = "us-west-2"

[[secret]]
name = "api-key"
from = "rbw:myapp/api-key"     # provider:ref — rbw | generate | detect | check | any envkit-provider-* plugin
to   = "keyring:service=myapp,type=api-key"   # transparently a TPM systemd-cred on headless machines
env  = "MYAPP_API_KEY"         # exposure name for `envkit run` / `envkit export`
need = "required"              # required | optional | one-of:<group>

[[secret]]
name = "db-password"
from = "generate:hex32"        # generated once per machine, NEVER regenerated (even --force)
to   = "env:DB_PASSWORD@back-end/.env"

[[envfile]]                    # monorepo outputs: many .env files from one manifest
path = "back-end/.env"
[envfile.static]
NODE_ENV = "development"

Commands
envkit sync materialize everything; --check dry-run, --force re-pull (generate-once values are never touched)
envkit check readiness report; exit code reflects it (0 ready · 1 missing · 3 auth needed)
envkit get NAME print one secret from local stores (keyring→creds→env fallback); --pull reaches the provider
envkit run -- CMD exec with the manifest environment
envkit export --format fish shell eval
envkit init scaffold; --import pipe-manifest FILE translates a legacy manifest
envkit rotate NAME re-pull one value; --regenerate for generate-once, with confirmation
envkit doctor stores, providers, domain, repo hygiene (gitignore + file modes)

Design rules

  • Shape, never values: no manifest field accepts a secret literal.
  • Config is scoped to the project, not the machine: envkit.toml (committed, shared) > envkit.local.toml (gitignored, personal) > flags. Account boundaries live where they really are — in which vaults/profiles each machine's providers are logged into — not in tool-enforced labels.
  • Never block headless: locked vaults degrade to a readiness report with a remedy hint; prompting happens only in envkit login.
  • Store auto-detection: keychain on macOS, keyring in a display session, TPM-sealed systemd-creds --user on headless Linux.
  • Provider modularity: built-ins behind one interface, plus exec plugins — any envkit-provider-<name> on PATH (JSON-in, bytes-out; see internal/provider/execplugin).

Roadmap: internal/broker/DESIGN.md (LoadCredential broker), aws-sm provider + .env-setup.json compat (v0.2).

Apache-2.0.

Directories

Path Synopsis
cmd
envkit command
internal
cli
Package cli is the only package that knows about flags and printing.
 Package cli is the only package that knows about flags and printing.
execx
Package execx is the single seam through which envkit shells out (rbw, systemd-creds, tailscale, git).
 Package execx is the single seam through which envkit shells out (rbw, systemd-creds, tailscale, git).
gitx
Package gitx derives repo identity from git, used for {repo} templating in provider refs (env-setup convention: dev/{repo}/secrets) and for default project names.
 Package gitx derives repo identity from git, used for {repo} templating in provider refs (env-setup convention: dev/{repo}/secrets) and for default project names.
keyringx
Package keyringx is envkit's single platform-keychain abstraction.
 Package keyringx is envkit's single platform-keychain abstraction.
machine
Package machine holds OPTIONAL per-user defaults (~/.config/envkit/ config.toml).
 Package machine holds OPTIONAL per-user defaults (~/.config/envkit/ config.toml).
manifest
Package manifest defines envkit.toml: the committable, values-free shape of a project's secrets.
 Package manifest defines envkit.toml: the committable, values-free shape of a project's secrets.
provider
Package provider defines the source side of the pipeline.
 Package provider defines the source side of the pipeline.
provider/awssm
Package awssm reads AWS Secrets Manager.
 Package awssm reads AWS Secrets Manager.
provider/bw
Package bw wraps the official Bitwarden CLI.
 Package bw wraps the official Bitwarden CLI.
provider/check
Package check verifies device-bound state (OAuth login dirs like ~/.claude).
 Package check verifies device-bound state (OAuth login dirs like ~/.claude).
provider/detect
Package detect derives machine-local values (this machine's identity, not the stack's) — kept out of git for the same reason as secrets.
 Package detect derives machine-local values (this machine's identity, not the stack's) — kept out of git for the same reason as secrets.
provider/execplugin
Package execplugin is the second provider tier (the git/docker credential-helper model): any `envkit-provider-<name>` binary on PATH is a provider, indistinguishable from a built-in.
 Package execplugin is the second provider tier (the git/docker credential-helper model): any `envkit-provider-<name>` binary on PATH is a provider, indistinguishable from a built-in.
provider/generate
Package generate produces per-instance secrets.
 Package generate produces per-instance secrets.
provider/rbw
Package rbw wraps the rbw Bitwarden CLI.
 Package rbw wraps the rbw Bitwarden CLI.
resolve
Package resolve is the engine: manifest entries flow provider → policy → store, and the readiness report falls out.
 Package resolve is the engine: manifest entries flow provider → policy → store, and the readiness report falls out.
secret
Package secret holds the Value type every provider returns and every store consumes.
 Package secret holds the Value type every provider returns and every store consumes.
store
Package store defines the sink side of the pipeline.
 Package store defines the sink side of the pipeline.
store/creds
Package creds stores secrets as user-scoped systemd credentials — TPM-sealed when a TPM exists, host-key-sealed otherwise.
 Package creds stores secrets as user-scoped systemd credentials — TPM-sealed when a TPM exists, host-key-sealed otherwise.
store/envfile
Package envfile writes .env files.
 Package envfile writes .env files.
store/keyring
Package keyring is the OS-keychain store.
 Package keyring is the OS-keychain store.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.