Everything dotenvctl does is callable from Go: import the cli module's packages and get the same behaviour with no subprocess.
On this page: Before you start · Packages · envkit — the operations API · providerkit — plugins · Mounting the github and vercel plugins · Embedding the CLI · discover · report · textdiff · outfmt · Complete API reference · CLI ↔ Go equivalence · Stability · Related
The CLI is a thin translator: flags in, an envkit call, formatted output. A program that imports these packages skips the translation and gets typed results instead of text.
You need Go 1.26 or newer (the cli module's go line). Add the module:
go get github.com/ubgo/dotenv/cli@latestThe parser and editor underneath are a separate, dependency-free module: github.com/ubgo/dotenv. Use it directly when you only need to read or edit one file. Use envkit when you want the higher-level operations: selection, discovery, the drift matrix, diff, edit, run.
Every snippet on this page is a Go Example function, compiled and output-checked by go test. Each one ends with its real // Output: block. To run them yourself from a clone:
cd cli && go test -run Example ./envkit/ ./providerkit/ ./discover/ ./report/ ./textdiff/ ./outfmt/ ./plugins/...ok github.com/ubgo/dotenv/cli/envkit 0.012s
ok github.com/ubgo/dotenv/cli/providerkit 0.008s
ok github.com/ubgo/dotenv/cli/discover 0.006s
ok github.com/ubgo/dotenv/cli/report 0.007s
ok github.com/ubgo/dotenv/cli/textdiff 0.004s
ok github.com/ubgo/dotenv/cli/outfmt 0.004s
ok github.com/ubgo/dotenv/cli/plugins/githubplugin 0.007s
ok github.com/ubgo/dotenv/cli/plugins/vercelplugin 0.006s
| Package | What it gives you |
|---|---|
envkit |
the operations: select, discover, matrix, diff, edit, run |
providerkit |
the plugin seam: build your own secret-store integration, or mount ours |
plugins/githubplugin, plugins/vercelplugin |
the two built-in plugins, mountable under any cobra root |
dotenvcmd |
the whole CLI as one function, Execute |
discover |
env-file family detection for a directory |
report |
self-contained HTML reports for matrix and diff |
textdiff |
the minimal line diff used by --dry-run |
outfmt |
the `{ok,data |
The contract for everything in envkit: typed options in, typed results out. No printing, no os.Exit, no cobra. Errors are plain wrapped errors, so inspect them with errors.Is / errors.As. Like the library beneath it, nothing in envkit reads or writes os.Environ.
SelectFile applies the selection grammar the CLI exposes as --prefix / --exclude-prefix / --include / --exclude / --strip-prefix. You want it whenever you push a subset of a file somewhere else. It returns the kept pairs and, separately, the keys a guard held back with the reason.
// ExampleSelectFile picks the deploy secrets out of a file: keep one prefix,
// rename without it, drop one key by name, resolve ${references}. Guarded
// values (placeholders, empties) land in Skipped with the reason.
func ExampleSelectFile() {
dir, err := apiEnvkitDir(map[string]string{".env.prod": `HOST=db.internal
GITHUB_SECRET_DB_URL=postgres://${HOST}/app
GITHUB_SECRET_API_KEY=__FILL_ME__
GITHUB_SECRET_SENTRY=
GITHUB_SECRET_LOCAL_ONLY=dev-token
LOG_LEVEL=info
`})
if err != nil {
fmt.Println("setup:", err)
return
}
defer func() {
// Cleanup is best-effort; a failure goes to stderr so the example's
// checked stdout output is unaffected.
if err := os.RemoveAll(dir); err != nil {
fmt.Fprintln(os.Stderr, "cleanup:", err)
}
}()
sel, err := envkit.SelectFile(filepath.Join(dir, ".env.prod"), envkit.SelectOptions{
Prefix: "GITHUB_SECRET_",
StripPrefix: true,
ExcludeKeys: []string{"GITHUB_SECRET_LOCAL_ONLY"}, // original name, before the strip
Expand: true,
})
if err != nil {
fmt.Println("select:", err)
return
}
for _, p := range sel.Pairs {
fmt.Printf("pair %s=%s\n", p.Key, p.Value)
}
for _, s := range sel.Skipped {
fmt.Printf("skipped %s (%s)\n", s.Name, s.Reason)
}
fmt.Println("names:", sel.Names())
// Output:
// pair DB_URL=postgres://db.internal/app
// skipped API_KEY (placeholder)
// skipped SENTRY (empty)
// names: [DB_URL]
}The resolution order is fixed: explicit Keys as given → otherwise all keys → Prefix keeps → ExcludePrefix drops → IncludeKeys adds → ExcludeKeys drops → StripPrefix renames → the placeholder and empty guards classify.
The guards are on by default. Values matching envkit.DefaultPlaceholderPattern (^__[A-Z0-9_]+__$) and empty values land in Skipped, not Pairs. Set IncludePlaceholders / IncludeEmpty to lift them, or PlaceholderPattern to use your own convention.
Already holding a parsed file? Select takes the *dotenv.File and skips the re-parse:
// ExampleSelect runs the same grammar over a file you already parsed, so it
// is not read twice. A key you NAME that does not exist is an error, never a
// silent skip.
func ExampleSelect() {
f := dotenv.Parse("A=1\nB=2\nC=3\n")
sel, err := envkit.Select(f, envkit.SelectOptions{Keys: []string{"C", "A"}})
if err != nil {
fmt.Println("select:", err)
return
}
fmt.Println(sel.Names(), sel.Map()["C"])
_, err = envkit.Select(f, envkit.SelectOptions{Keys: []string{"MISSING"}})
fmt.Println(err)
// Output:
// [C A] 3
// envkit: key "MISSING" not found
}Pitfalls
- A key you name (
KeysorIncludeKeys) that does not exist is an error, never a silent skip. Excluding an absent key is fine. ExcludeKeysmatches the original names, beforeStripPrefixrenames them.- Explicit
KeysbypassPrefixandExcludePrefix, butStripPrefixstill renames any of them that carry the prefix. StripPrefixdoes nothing withoutPrefix.- Stripping can produce two pairs with one name:
Prefix: "APP_"withStripPrefixandIncludeKeys: []string{"DB"}turns bothAPP_DBandDBintoDB.Pairsholds both;Map()keeps the last. Pick names that cannot collide. Expandis false in the zero value. The CLI's push verbs default--expandto on; a Go caller must set it.
Examples: ExampleSelectFile, ExampleSelect.
Discover lists the env-file family of one directory. Inventories does the same and summarizes each file: active keys, commented-out settings, name-only declarations and placeholder values. This is the dotenvctl envs view as data.
// ExampleDiscover lists a directory's env-file family in distance-from-prod
// order. Long names collapse (.env.production is "prod"), templates are
// tagged Contract, and editor droppings like .env.bak are ignored.
func ExampleDiscover() {
dir, err := apiEnvkitDir(map[string]string{
".env": "A=1\n",
".env.production": "A=1\n",
".env.staging": "A=1\n",
".env.example": "A=\n",
".env.bak": "A=old\n",
})
if err != nil {
fmt.Println("setup:", err)
return
}
defer func() {
// Cleanup is best-effort; a failure goes to stderr so the example's
// checked stdout output is unaffected.
if err := os.RemoveAll(dir); err != nil {
fmt.Fprintln(os.Stderr, "cleanup:", err)
}
}()
files, err := envkit.Discover(dir)
if err != nil {
fmt.Println("discover:", err)
return
}
for _, f := range files {
fmt.Printf("%-16s env=%-8s contract=%t\n", f.File, f.Env, f.Contract)
}
// Output:
// .env env=default contract=false
// .env.staging env=stag contract=false
// .env.production env=prod contract=false
// .env.example env=example contract=true
}// ExampleInventories summarizes each discovered file: active keys,
// commented-out settings, name-only declarations, and placeholder values.
func ExampleInventories() {
dir, err := apiEnvkitDir(map[string]string{
".env": "A=1\nB=__TODO__\n# C=3\nPATH\n",
".env.prod": "A=1\nB=real\nC=3\n",
})
if err != nil {
fmt.Println("setup:", err)
return
}
defer func() {
// Cleanup is best-effort; a failure goes to stderr so the example's
// checked stdout output is unaffected.
if err := os.RemoveAll(dir); err != nil {
fmt.Fprintln(os.Stderr, "cleanup:", err)
}
}()
inv, err := envkit.Inventories(envkit.InventoryOptions{Dir: dir})
if err != nil {
fmt.Println("inventories:", err)
return
}
for _, i := range inv {
fmt.Printf("%s: %d keys, %d disabled, %d inherited, %d placeholders\n",
i.Env, i.Keys, i.Disabled, i.Inherited, i.Placeholders)
}
// Output:
// default: 2 keys, 1 disabled, 1 inherited, 1 placeholders
// prod: 3 keys, 0 disabled, 0 inherited, 0 placeholders
}EnvNameForPath labels any path with the same vocabulary, and falls back to the basename for files outside the .env family:
// ExampleEnvNameForPath labels an explicit path with discovery's vocabulary,
// falling back to the basename for files outside the .env family.
func ExampleEnvNameForPath() {
for _, p := range []string{"ops/.env.production", ".env", "ops/.env.example", "config/app.env"} {
fmt.Printf("%s -> %s\n", p, envkit.EnvNameForPath(p))
}
// Output:
// ops/.env.production -> prod
// .env -> default
// ops/.env.example -> example
// config/app.env -> app.env
}Pitfalls
- Discovery is non-recursive and reads filenames only. A
deploy/subfolder is not scanned; pass it as the directory. - An empty directory gives an empty slice and no error. A missing directory is an error.
Inventory.Keyscounts distinct active keys, so a key set twice counts once.
Examples: ExampleDiscover, ExampleInventories, ExampleEnvNameForPath.
BuildMatrix compares env files key by key: one row per key, one column per environment. Pass Dir to discover the columns, or Files for explicit paths. Add ContractPath to check every environment against a template such as .env.example; that is the CI-gate question HasContractGaps answers.
// ExampleBuildMatrix compares every env file in a directory key by key and
// checks them against a contract. Values stay out of the result unless you
// pass Reveal.
func ExampleBuildMatrix() {
dir, err := apiEnvkitDir(map[string]string{
".env.example": "DB_URL=\nAPI_KEY=\nSENTRY_DSN=\n",
".env.stag": "DB_URL=postgres://stag\nAPI_KEY=__FILL_ME__\n# SENTRY_DSN=x\n",
".env.prod": "DB_URL=postgres://prod\nAPI_KEY=k-123\n",
})
if err != nil {
fmt.Println("setup:", err)
return
}
defer func() {
// Cleanup is best-effort; a failure goes to stderr so the example's
// checked stdout output is unaffected.
if err := os.RemoveAll(dir); err != nil {
fmt.Fprintln(os.Stderr, "cleanup:", err)
}
}()
m, err := envkit.BuildMatrix(envkit.MatrixOptions{
Dir: dir, // contract files are never columns
ContractPath: filepath.Join(dir, ".env.example"),
})
if err != nil {
fmt.Println("matrix:", err)
return
}
fmt.Println("columns:", m.Envs)
for _, row := range m.Rows {
fmt.Printf("%-10s", row.Key)
for _, c := range row.Cells {
fmt.Printf(" %s=%s%s", c.Env, envkit.StateSymbols[c.State], c.State)
}
fmt.Println()
}
fmt.Println("value hidden:", m.Rows[1].Cells[0].Value == "")
fmt.Println("contract gaps:", m.HasContractGaps(), m.ContractMissing["prod"])
// Output:
// columns: [stag prod]
// API_KEY stag=!placeholder prod=✓present
// DB_URL stag=✓present prod=✓present
// SENTRY_DSN stag=#disabled prod=—missing
// value hidden: true
// contract gaps: true [SENTRY_DSN]
}Cell states are the closed set present · empty · placeholder · disabled · inherited · missing, and envkit.StateSymbols maps each to the glyph every renderer uses. Values are absent from the result unless you pass Reveal: true, because a matrix is the artifact most likely to be pasted into a ticket. MatrixCell.Raw() returns the value anyway, for renderers that mask at display time; treat it as a secret.
DriftRows keeps the rows that are not present everywhere. MatrixOptions.OnlyDrift applies it for you.
// ExampleDriftRows keeps only rows with at least one cell that is not
// "present". It filters IN PLACE, so assign the result back and do not keep
// using the old slice.
func ExampleDriftRows() {
rows := []envkit.MatrixRow{
{Key: "SAME", Cells: []envkit.MatrixCell{{Env: "stag", State: envkit.StatePresent}, {Env: "prod", State: envkit.StatePresent}}},
{Key: "GAP", Cells: []envkit.MatrixCell{{Env: "stag", State: envkit.StatePresent}, {Env: "prod", State: envkit.StateMissing}}},
}
rows = envkit.DriftRows(rows)
for _, r := range rows {
fmt.Println(r.Key)
}
// Output:
// GAP
}A missing cell counts as drift. So one nearly empty file (a bare .env with one key, say) makes every row look like drift, and the filter seems to do nothing. SparseColumn names the column to blame, so you can explain it instead of showing an unchanged table:
// ExampleSparseColumn shows why a drift filter can look broken: one nearly
// empty file makes every row "drift". Build the full matrix, remember the
// row count, filter with DriftRows, then ask SparseColumn which column is
// to blame.
func ExampleSparseColumn() {
dir, err := apiEnvkitDir(map[string]string{
".env": "A=1\n",
".env.stag": "A=1\nB=2\nC=3\nD=4\nE=5\nF=6\nG=7\nH=8\nI=9\nJ=10\n",
".env.prod": "A=1\nB=2\nC=3\nD=4\nE=5\nF=6\nG=7\nH=8\nI=9\nJ=10\n",
})
if err != nil {
fmt.Println("setup:", err)
return
}
defer func() {
// Cleanup is best-effort; a failure goes to stderr so the example's
// checked stdout output is unaffected.
if err := os.RemoveAll(dir); err != nil {
fmt.Fprintln(os.Stderr, "cleanup:", err)
}
}()
m, err := envkit.BuildMatrix(envkit.MatrixOptions{Dir: dir})
if err != nil {
fmt.Println("matrix:", err)
return
}
rowsBefore := len(m.Rows)
m.Rows = envkit.DriftRows(m.Rows) // reuses m.Rows' backing array
fmt.Printf("rows: %d before, %d after the drift filter\n", rowsBefore, len(m.Rows))
if env, missing, ok := envkit.SparseColumn(m, rowsBefore); ok {
fmt.Printf("column %q is missing %d of %d keys\n", env, missing, len(m.Rows))
}
// Output:
// rows: 10 before, 9 after the drift filter
// column "default" is missing 9 of 9 keys
}.env.stag and .env.staging both classify as stag, and two folders' .env files both classify as default. A lookup keyed on that label would silently show one file's data under both columns. DisambiguateColumns makes every label unique: a collided label falls back to the filename, then to the full path. BuildMatrix already calls it; call it yourself when you build your own column list.
// ExampleDisambiguateColumns makes column labels unique. .env.stag and
// .env.staging both classify as "stag"; two directories' .env files both
// classify as "default". Labels fall back to the filename, then the path.
func ExampleDisambiguateColumns() {
paths := []string{"deploy/.env.stag", "deploy/.env.staging", "api/.env", "web/.env", "deploy/.env.prod"}
cols := make([]discover.EnvFile, 0, len(paths))
for _, p := range paths {
cols = append(cols, discover.EnvFile{Path: p, File: filepath.Base(p), Env: envkit.EnvNameForPath(p)})
}
for _, c := range envkit.DisambiguateColumns(cols) {
fmt.Println(c.Env)
}
// Output:
// .env.stag
// .env.staging
// api/.env
// web/.env
// prod
}Pitfalls
- Fewer than two columns is an error (
envkit: matrix needs at least two env files, found 1). A one-column matrix is a list. - With
Dir, contract files (.env.exampleand kin) are never columns. Pass them asContractPath. DriftRowsfilters in place: it reuses the input slice's backing array. Assign the result back (m.Rows = envkit.DriftRows(m.Rows)) and do not read the old slice afterwards.SparseColumnreturnsok=falsewhen the filter hid more than 10% of rows, because then the filter worked. It needs the row count from before filtering, so build withoutOnlyDrift, recordlen(m.Rows), then filter.- After disambiguation,
Matrix.Envsmay hold filenames or paths (.env.stag,api/.env) instead of environment names. Code that looks columns up by"stag"must allow for that.
Examples: ExampleBuildMatrix, ExampleDriftRows, ExampleSparseColumn, ExampleDisambiguateColumns.
Diff compares the effective view (last-wins) of two files: the configuration a program would see. Formatting, comments and shadowed duplicates are invisible on purpose; diff(1) is for bytes. With Expand: true, ${HOST} and the literal host compare equal.
// ExampleDiff compares the effective (last-wins) view of two files. With
// Expand, `${HOST}` and the literal host compare equal.
func ExampleDiff() {
dir, err := apiEnvkitDir(map[string]string{
".env.stag": "HOST=db\nDB_URL=postgres://${HOST}/app\nDEBUG=true\nPOOL=5\n",
".env.prod": "# production\nDB_URL=postgres://db/app\nPOOL=5\nPOOL=20\nSENTRY=on\n",
})
if err != nil {
fmt.Println("setup:", err)
return
}
defer func() {
// Cleanup is best-effort; a failure goes to stderr so the example's
// checked stdout output is unaffected.
if err := os.RemoveAll(dir); err != nil {
fmt.Fprintln(os.Stderr, "cleanup:", err)
}
}()
d, err := envkit.Diff(filepath.Join(dir, ".env.stag"), filepath.Join(dir, ".env.prod"), envkit.DiffOptions{Expand: true})
if err != nil {
fmt.Println("diff:", err)
return
}
fmt.Println("empty:", d.Empty())
for _, p := range d.Added {
fmt.Println("+", p.Key)
}
for _, p := range d.Removed {
fmt.Println("-", p.Key)
}
for _, c := range d.Changed {
fmt.Printf("~ %s: %s -> %s\n", c.Key, c.From, c.To)
}
// Output:
// empty: false
// + SENTRY
// - DEBUG
// - HOST
// ~ POOL: 5 -> 20
}DiffMaps gives the same comparison over maps you got elsewhere, such as a remote store or a template:
// ExampleDiffMaps runs the same comparison over maps you got elsewhere —
// a remote store, a template. The three slices are never nil.
func ExampleDiffMaps() {
local := map[string]string{"A": "1", "B": "2"}
remote := map[string]string{"A": "1", "B": "2"}
d := envkit.DiffMaps(local, remote, false)
fmt.Println(d.Empty(), d.Added != nil, len(d.Changed))
// Output:
// true true 0
}Pitfalls
- Both files must exist. A missing file would read as "everything was removed", so it is an error instead.
DiffResultcarries the real values (Added[].Value,Changed[].From/.To). Unlike the matrix there is no reveal switch; mask them yourself before you print or log a diff.Added,RemovedandChangedare never nil and are sorted by key, so JSON output never showsnulland is itself diffable.
Examples: ExampleDiff, ExampleDiffMaps.
Set, Unset and Restore change one entry and keep every other byte of the file: comments, blank lines, order, quoting style, = vs :.
// ExampleSet upserts a key without disturbing the rest of the file. A dry
// run returns the diff and writes nothing; setting a key to its current value
// is a full no-op.
func ExampleSet() {
dir, err := apiEnvkitDir(map[string]string{".env": "# database\nDB_PORT=5432\n"})
if err != nil {
fmt.Println("setup:", err)
return
}
defer func() {
// Cleanup is best-effort; a failure goes to stderr so the example's
// checked stdout output is unaffected.
if err := os.RemoveAll(dir); err != nil {
fmt.Fprintln(os.Stderr, "cleanup:", err)
}
}()
path := filepath.Join(dir, ".env")
pairs := []dotenv.Pair{{Key: "DB_HOST", Value: "db.prod"}}
preview, err := envkit.Set(path, pairs, envkit.EditOptions{Anchor: "DB_PORT", DryRun: true})
if err != nil {
fmt.Println("set:", err)
return
}
fmt.Println("dry run:", preview.Diff, "written:", preview.Written)
res, err := envkit.Set(path, pairs, envkit.EditOptions{Anchor: "DB_PORT"})
if err != nil {
fmt.Println("set:", err)
return
}
fmt.Println("created:", res.Created, "written:", res.Written)
again, err := envkit.Set(path, pairs, envkit.EditOptions{})
if err != nil {
fmt.Println("set:", err)
return
}
fmt.Println("second call changed:", again.Changed)
_, err = envkit.Set(path, []dotenv.Pair{{Key: "X", Value: "1"}}, envkit.EditOptions{Anchor: "NOPE"})
fmt.Println("bad anchor:", errors.Is(err, envkit.ErrAnchorNotFound))
body, err := os.ReadFile(path)
if err != nil {
fmt.Println("read:", err)
return
}
fmt.Print(string(body))
// Output:
// dry run: [+DB_HOST=db.prod] written: false
// created: [DB_HOST] written: true
// second call changed: false
// bad anchor: true
// # database
// DB_PORT=5432
// DB_HOST=db.prod
}Unset comments a key out by default, which Restore can undo; Delete: true removes the line instead.
// ExampleUnset comments a key out by default (reversible with Restore), or
// removes the line with Delete. Naming an absent key is ErrKeyNotFound.
func ExampleUnset() {
dir, err := apiEnvkitDir(map[string]string{".env": "A=1\nOLD=x\nGONE=y\n"})
if err != nil {
fmt.Println("setup:", err)
return
}
defer func() {
// Cleanup is best-effort; a failure goes to stderr so the example's
// checked stdout output is unaffected.
if err := os.RemoveAll(dir); err != nil {
fmt.Fprintln(os.Stderr, "cleanup:", err)
}
}()
path := filepath.Join(dir, ".env")
if _, err := envkit.Unset(path, []string{"OLD"}, envkit.EditOptions{}); err != nil {
fmt.Println("unset:", err)
return
}
if _, err := envkit.Unset(path, []string{"GONE"}, envkit.EditOptions{Delete: true}); err != nil {
fmt.Println("unset:", err)
return
}
_, err = envkit.Unset(path, []string{"NEVER"}, envkit.EditOptions{})
fmt.Println("absent key:", errors.Is(err, envkit.ErrKeyNotFound))
body, err := os.ReadFile(path)
if err != nil {
fmt.Println("read:", err)
return
}
fmt.Print(string(body))
// Output:
// absent key: true
// A=1
// # OLD=x
}// ExampleRestore re-activates a commented-out setting, removing exactly the
// marker that was there.
func ExampleRestore() {
dir, err := apiEnvkitDir(map[string]string{".env": "A=1\n#OLD=x\n"})
if err != nil {
fmt.Println("setup:", err)
return
}
defer func() {
// Cleanup is best-effort; a failure goes to stderr so the example's
// checked stdout output is unaffected.
if err := os.RemoveAll(dir); err != nil {
fmt.Fprintln(os.Stderr, "cleanup:", err)
}
}()
path := filepath.Join(dir, ".env")
res, err := envkit.Restore(path, []string{"OLD"}, envkit.EditOptions{})
if err != nil {
fmt.Println("restore:", err)
return
}
fmt.Println("diff:", res.Diff)
// Output:
// diff: [-#OLD=x +OLD=x]
}Pitfalls
- Setting a key to its current value is a full no-op:
Changedis false and the file is not rewritten, so its mtime does not move. Anchorplaces only a new key. An existing key is updated where it is and never moved.- A missing file is created at mode
0600bySet.UnsetandRestoreneed the file to exist. DryRun: truefillsDiffand writes nothing; the real run computes the same diff.- Branch on
envkit.ErrAnchorNotFoundandenvkit.ErrKeyNotFoundwitherrors.Is.
Examples: ExampleSet, ExampleUnset, ExampleRestore.
Run executes a command with the file's values in its environment and returns the child's exit code. It is dotenvctl run as a function.
// ExampleRun executes a command with the file's values. A nil Base gives a
// hermetic child that sees ONLY the file. A child that exits non-zero returns
// its code with a nil error, so a wrapper can pass it through.
func ExampleRun() {
dir, err := apiEnvkitDir(map[string]string{".env.test": "NAME=world\nGREETING=hello ${NAME}\n"})
if err != nil {
fmt.Println("setup:", err)
return
}
defer func() {
// Cleanup is best-effort; a failure goes to stderr so the example's
// checked stdout output is unaffected.
if err := os.RemoveAll(dir); err != nil {
fmt.Fprintln(os.Stderr, "cleanup:", err)
}
}()
path := filepath.Join(dir, ".env.test")
ctx := context.Background()
code, err := envkit.Run(ctx, path, []string{"sh", "-c", `echo "$GREETING"`}, envkit.RunOptions{Stdout: os.Stdout})
fmt.Println("exit:", code, "err:", err)
code, err = envkit.Run(ctx, path, []string{"sh", "-c", "exit 3"}, envkit.RunOptions{})
fmt.Println("exit:", code, "err:", err)
// Output:
// hello world
// exit: 0 err: <nil>
// exit: 3 err: <nil>
}Need only the environment, not the exec? ChildEnv returns the merged []string (file wins), and MergeEnv does the merge alone:
// ExampleChildEnv builds the environment a child would get without running
// anything. The file wins over the base, and the overridden base entry is
// removed rather than duplicated.
func ExampleChildEnv() {
dir, err := apiEnvkitDir(map[string]string{".env": "HOME_DIR=/srv\nMODE=prod\n"})
if err != nil {
fmt.Println("setup:", err)
return
}
defer func() {
// Cleanup is best-effort; a failure goes to stderr so the example's
// checked stdout output is unaffected.
if err := os.RemoveAll(dir); err != nil {
fmt.Fprintln(os.Stderr, "cleanup:", err)
}
}()
env, err := envkit.ChildEnv(filepath.Join(dir, ".env"), []string{"MODE=dev", "TERM=xterm"}, nil)
if err != nil {
fmt.Println("child env:", err)
return
}
slices.Sort(env) // the file's values are appended in map order
fmt.Println(strings.Join(env, " "))
// Output:
// HOME_DIR=/srv MODE=prod TERM=xterm
}// ExampleMergeEnv is the merge alone, for values you already hold.
func ExampleMergeEnv() {
env := envkit.MergeEnv([]string{"A=base", "B=keep"}, map[string]string{"A": "file"})
fmt.Println(env)
// Output:
// [B=keep A=file]
}Pitfalls
erris non-nil only for your failures: an unreadable file, an unresolvable reference, a command that cannot start. A child that runs and exits non-zero returns its code with a nil error.- A nil
Basemeans the child sees only the file's values, with noPATHorHOME. The command itself is still found through your process'sPATH, but anything the child starts may not be. Passos.Environ()for the usual inherit behaviour. - A nil
Selectmeans "every key, expanded". A non-nilSelectis used as given, and its zeroExpandis false, so${refs}then reach the child unresolved. SetExpand: truewhen you narrow the selection. MergeEnvandChildEnvappend the file's values in map order. Sort the slice if you compare or print it.- Nil
Stdin/Stdout/Stderrmean the parent's streams.
Examples: ExampleRun, ExampleChildEnv, ExampleMergeEnv.
providerkit is the seam the github and vercel plugins are built on, and you can build your own on it. A plugin is one method, Command(Deps) *cobra.Command. The kit then generates the standard verbs (push, list, prune) with the shared flags, the placeholder and empty guards, the confirm gate and the output vocabulary. Your code only talks to the backend.
providerkit.SelectOpts is an alias for envkit.SelectOptions and providerkit.Source for *envkit.Selection: one grammar, no translation layer. See Plugins for the full contract and the exec-plugin alternative (no Go needed).
A backend implements only what it truly supports: SecretWriter (Set), SecretLister (Names, names only) and SecretDeleter (Delete). The examples on this page use this in-memory store:
// apiKitStore is an in-memory secret store implementing all three capability
// interfaces — the shape a real backend adapter takes, minus the network.
type apiKitStore struct {
values map[string]string
}
// Set implements providerkit.SecretWriter.
func (s *apiKitStore) Set(_ context.Context, name, value string) error {
s.values[name] = value
return nil
}
// Names implements providerkit.SecretLister: names only, never values.
func (s *apiKitStore) Names(context.Context) ([]string, error) {
names := make([]string, 0, len(s.values))
for n := range s.values {
names = append(names, n)
}
slices.Sort(names)
return names, nil
}
// Delete implements providerkit.SecretDeleter.
func (s *apiKitStore) Delete(_ context.Context, name string) error {
delete(s.values, name)
return nil
}Driving it through the interfaces directly is what the kit's verbs do for you:
// ExampleSecretWriter drives a store through the three capability
// interfaces directly — what the kit's verbs do for you. Implement only the
// interfaces your backend truly supports; the kit builds verbs for those.
func ExampleSecretWriter() {
store := &apiKitStore{values: map[string]string{}}
ctx := context.Background()
var w providerkit.SecretWriter = store
var l providerkit.SecretLister = store
var d providerkit.SecretDeleter = store
for _, name := range []string{"B_KEY", "A_KEY"} {
if err := w.Set(ctx, name, "value"); err != nil {
fmt.Println("set:", err)
return
}
}
if err := d.Delete(ctx, "B_KEY"); err != nil {
fmt.Println("delete:", err)
return
}
names, err := l.Names(ctx)
if err != nil {
fmt.Println("names:", err)
return
}
fmt.Println(names)
// Output:
// [A_KEY]
}NewPushCmd builds push [KEY...] over a SecretWriter. Run non-interactively without --yes and it refuses; with --dry-run it reports and writes nothing.
// ExampleNewPushCmd generates a standard `push` verb over your store. The kit
// owns selection, the placeholder/empty guards, the confirm gate and the
// output; your store only writes. Non-interactive runs need --yes.
func ExampleNewPushCmd() {
store := &apiKitStore{values: map[string]string{}}
src := &envkit.Selection{
Pairs: []dotenv.Pair{{Key: "DB_URL", Value: "postgres://db/app"}},
Skipped: []envkit.Skip{{Name: "API_KEY", Reason: envkit.SkipPlaceholder}},
}
push := func() *cobra.Command {
return providerkit.NewPushCmd(apiKitDeps(src), store, providerkit.VerbConfig{})
}
fmt.Println("exit:", apiKitRun(push()))
fmt.Println("exit:", apiKitRun(push(), "--dry-run"))
fmt.Println("exit:", apiKitRun(push(), "--yes"))
fmt.Println("stored:", store.values)
// Output:
// dotenvctl: refusing to write without --yes in non-interactive mode
// exit: 2
// API_KEY: skipped-placeholder
// DB_URL: would-push
// exit: 0
// API_KEY: skipped-placeholder
// DB_URL: pushed
// exit: 0
// stored: map[DB_URL:postgres://db/app]
}NewListCmd lists remote names, sorted:
// ExampleNewListCmd lists remote NAMES, sorted. The kit never asks a backend
// for values.
func ExampleNewListCmd() {
store := &apiKitStore{values: map[string]string{"B_KEY": "x", "A_KEY": "y"}}
fmt.Println("exit:", apiKitRun(providerkit.NewListCmd(apiKitDeps(&envkit.Selection{}), store)))
// Output:
// A_KEY
// B_KEY
// exit: 0
}NewPruneCmd deletes remote names that are not in the local selection. It needs both a lister and a deleter. A key the selection guarded out (a placeholder) and a name passed to --keep are spared, and the output says why:
// ExampleNewPruneCmd deletes remote names that are not in the local
// selection. A name the selection guarded out (a placeholder) and a name
// passed to --keep are spared, and the output says why.
func ExampleNewPruneCmd() {
store := &apiKitStore{values: map[string]string{
"DB_URL": "live", "API_KEY": "live", "LEGACY": "live", "BUNDLE": "live",
}}
src := &envkit.Selection{
Pairs: []dotenv.Pair{{Key: "DB_URL", Value: "postgres://db/app"}},
Skipped: []envkit.Skip{{Name: "API_KEY", Reason: envkit.SkipPlaceholder}},
}
prune := providerkit.NewPruneCmd(apiKitDeps(src), store, store, providerkit.VerbConfig{})
fmt.Println("exit:", apiKitRun(prune, "--keep", "BUNDLE", "--yes"))
remaining, err := store.Names(context.Background())
if err != nil {
fmt.Println("names:", err)
return
}
fmt.Println("remaining:", remaining)
// Output:
// API_KEY: kept-skipped
// BUNDLE: kept-keep-flag
// LEGACY: deleted
// exit: 0
// remaining: [API_KEY BUNDLE DB_URL]
}The per-name outcomes are the closed Action set: pushed, would-push, skipped-placeholder, skipped-empty, deleted, would-delete, kept-skipped, kept-keep-flag. SkipAction maps a selection guard's reason onto it:
// ExampleSkipAction maps why the selection held a key back onto what a push
// reports for it.
func ExampleSkipAction() {
fmt.Println(providerkit.SkipAction(envkit.SkipPlaceholder))
fmt.Println(providerkit.SkipAction(envkit.SkipEmpty))
// Output:
// skipped-placeholder
// skipped-empty
}VerbConfig.Gate runs after selection and before any write, dry runs included. Print where the write will land (target, account), then call Confirm. VerbConfig.Meta adds that context to the --json payload, so scripts see where actions landed.
// ExampleVerbConfig adds a Gate (print where the write lands, then apply the
// standard Confirm contract) and Meta (resolution context for the --json
// payload) to a kit verb.
func ExampleVerbConfig() {
store := &apiKitStore{values: map[string]string{}}
src := &envkit.Selection{Pairs: []dotenv.Pair{{Key: "TOKEN", Value: "t-1"}}}
cfg := providerkit.VerbConfig{
Gate: func(_ context.Context, deps providerkit.Deps, info providerkit.GateInfo) error {
deps.Printer.Humanf("target : memory store")
deps.Printer.Humanf("keys : %s (dry run: %t)", strings.Join(info.Names, ","), info.DryRun)
return providerkit.Confirm(deps, info)
},
Meta: func(context.Context) (map[string]string, error) {
return map[string]string{"target": "memory"}, nil
},
}
human := apiKitDeps(src)
fmt.Println("exit:", apiKitRun(providerkit.NewPushCmd(human, store, cfg), "--dry-run"))
machine := apiKitDeps(src)
machine.Printer.JSON = true
fmt.Println("exit:", apiKitRun(providerkit.NewPushCmd(machine, store, cfg), "--yes"))
// Output:
// target : memory store
// keys : TOKEN (dry run: true)
// TOKEN: would-push
// exit: 0
// {"ok":true,"data":{"meta":{"target":"memory"},"results":[{"name":"TOKEN","action":"pushed"}],"dry_run":false}}
// exit: 0
}Confirm is the proceed contract every mutating verb follows: dry run and --yes proceed, an interactive human is asked, anything else is refused with a usage error:
// ExampleConfirm shows the proceed contract every mutating verb follows:
// dry-run and --yes proceed, an interactive human is asked, and anything else
// is refused with a usage error (exit code 2).
func ExampleConfirm() {
deps := apiKitDeps(&envkit.Selection{})
names := []string{"DB_URL"}
fmt.Println(providerkit.Confirm(deps, providerkit.GateInfo{Names: names, DryRun: true}))
fmt.Println(providerkit.Confirm(deps, providerkit.GateInfo{Names: names, Yes: true}))
err := providerkit.Confirm(deps, providerkit.GateInfo{Names: names})
if ce, ok := errors.AsType[*providerkit.CmdError](err); ok {
fmt.Println("code:", ce.Code, "quiet:", ce.Quiet)
}
deps.Interactive = func() bool { return true }
deps.Ask = func(prompt string) bool {
fmt.Printf("asked %q\n", prompt)
return true
}
fmt.Println(providerkit.Confirm(deps, providerkit.GateInfo{Names: names}))
// Output:
// <nil>
// <nil>
// dotenvctl: refusing to write without --yes in non-interactive mode
// code: 2 quiet: true
// asked "proceed? [y/N] "
// <nil>
}Put the verbs under one namespace command, and add that to your cobra root. Deps.Source is where the env file is read; using envkit.SelectFile there gives your plugin the same --prefix and guard semantics as dotenvctl.
// ExamplePlugin mounts a plugin under your own cobra root. Deps.Source reads
// the env file through envkit, so --prefix and the guards mean the same thing
// here as in dotenvctl.
func ExamplePlugin() {
dir, err := os.MkdirTemp("", "providerkit-example-")
if err != nil {
fmt.Println("setup:", err)
return
}
defer func() {
// Cleanup is best-effort; a failure goes to stderr so the example's
// checked stdout output is unaffected.
if err := os.RemoveAll(dir); err != nil {
fmt.Fprintln(os.Stderr, "cleanup:", err)
}
}()
envPath := filepath.Join(dir, ".env.prod")
if err := os.WriteFile(envPath, []byte("APP_DB=postgres://db\nAPP_KEY=__TODO__\nOTHER=x\n"), apiKitFileMode); err != nil {
fmt.Println("setup:", err)
return
}
deps := apiKitDeps(nil)
deps.Source = func(o providerkit.SelectOpts) (providerkit.Source, error) {
return envkit.SelectFile(envPath, o)
}
var plugin providerkit.Plugin = &apiKitPlugin{store: &apiKitStore{values: map[string]string{}}}
root := &cobra.Command{Use: "mytool"}
root.AddCommand(plugin.Command(deps))
fmt.Println("exit:", apiKitRun(root, "memstore", "push", "--prefix", "APP_", "--strip-prefix", "--yes"))
fmt.Println("exit:", apiKitRun(root, "memstore", "list"))
// Output:
// KEY: skipped-placeholder
// DB: pushed
// exit: 0
// DB
// exit: 0
}The plugin type in that example is a complete third-party plugin:
// apiKitPlugin is a complete third-party plugin: one namespace with the
// three kit verbs over its own store.
type apiKitPlugin struct {
store *apiKitStore
}
// Command implements providerkit.Plugin.
func (p *apiKitPlugin) Command(deps providerkit.Deps) *cobra.Command {
root := &cobra.Command{Use: "memstore", Short: "Sync values to an in-memory store"}
root.AddCommand(
providerkit.NewPushCmd(deps, p.store, providerkit.VerbConfig{}),
providerkit.NewListCmd(deps, p.store),
providerkit.NewPruneCmd(deps, p.store, p.store, providerkit.VerbConfig{}),
)
return root
}Plugins that drive a CLI (gh, vercel) call it through Deps.Runner. Production uses providerkit.ExecRunner{}; tests inject a fake that records argv and stdin and never starts a process:
// ExampleRunner swaps the exec seam for a recording fake. A store passes the
// secret on stdin, never in argv, because argv is visible in ps.
func ExampleRunner() {
runner := &apiKitRunner{}
var r providerkit.Runner = runner
if _, err := r.Run(context.Background(), "s3cr3t", "mycli", "secret", "set", "DB_URL"); err != nil {
fmt.Println("run:", err)
return
}
fmt.Println(runner.calls[0])
// Output:
// mycli secret set DB_URL <stdin "s3cr3t">
}Fail prints a failure in the active mode (dotenvctl: <msg> for humans, the error envelope under --json) and returns a *CmdError carrying the exit code: CodeUsage gives 2, every other code gives 1. Quiet is true because the message is already printed.
// ExampleFail prints a failure in the active mode and returns a *CmdError
// carrying the exit code: CodeUsage maps to 2, every other code to 1. Quiet
// is true because the message is already printed.
func ExampleFail() {
human := &outfmt.Printer{Out: os.Stdout, Err: os.Stdout} // Err: os.Stdout only so the Example shows the line
err := providerkit.Fail(human, outfmt.CodeExec, "push %s: %s", "DB_URL", "HTTP 403")
if ce, ok := errors.AsType[*providerkit.CmdError](err); ok {
fmt.Println("code:", ce.Code, "quiet:", ce.Quiet, "error:", ce)
}
machine := &outfmt.Printer{Out: os.Stdout, JSON: true}
err = providerkit.Fail(machine, outfmt.CodeUsage, "--org is mutually exclusive with --repo")
if ce, ok := errors.AsType[*providerkit.CmdError](err); ok {
fmt.Println("code:", ce.Code)
}
// Output:
// dotenvctl: push DB_URL: HTTP 403
// code: 1 quiet: true error: push DB_URL: HTTP 403
// {"ok":false,"error":{"code":"usage","message":"--org is mutually exclusive with --repo"}}
// code: 2
}On the host side, map whatever a command returned to a process exit code. Print the message only when Quiet is false:
// ExampleCmdError is the host side: map whatever a plugin command returned to
// a process exit code, and print the message only when the plugin has not
// already printed it (Quiet false).
func ExampleCmdError() {
exitCode := func(err error) int {
if err == nil {
return 0
}
if ce, ok := errors.AsType[*providerkit.CmdError](err); ok {
if !ce.Quiet && ce.Err != nil {
fmt.Println("dotenvctl:", ce.Err)
}
return ce.Code
}
fmt.Println("dotenvctl:", err)
return apiKitExitUsage // anything else out of cobra is a usage error
}
fmt.Println(exitCode(nil))
fmt.Println(exitCode(&providerkit.CmdError{Code: 1, Err: errors.New("backend unreachable")}))
fmt.Println(exitCode(&providerkit.CmdError{Code: 1, Quiet: true, Err: errors.New("already printed")}))
fmt.Println(exitCode(errors.New(`unknown flag: --tagret`)))
// Output:
// 0
// dotenvctl: backend unreachable
// 1
// 1
// dotenvctl: unknown flag: --tagret
// 2
}AddSelectionFlags gives any command the five shared selection flags (--prefix, --exclude-prefix, --include, --exclude, --strip-prefix). SelectionActive tells you whether the user selected anything, so a read verb can keep its plain output for bare calls.
// ExampleAddSelectionFlags gives your own command the shared selection flags
// (--prefix, --exclude-prefix, --include, --exclude, --strip-prefix), and
// SelectionActive tells you whether the user actually selected anything.
func ExampleAddSelectionFlags() {
run := func(args ...string) {
var sel providerkit.SelectOpts
c := &cobra.Command{
Use: "show",
RunE: func(*cobra.Command, []string) error {
fmt.Printf("active=%t prefix=%q strip=%t exclude=%v\n",
providerkit.SelectionActive(sel), sel.Prefix, sel.StripPrefix, sel.ExcludeKeys)
return nil
},
}
providerkit.AddSelectionFlags(c, &sel)
c.SetArgs(args)
if err := c.Execute(); err != nil {
fmt.Println("error:", err)
}
}
run()
run("--prefix", "APP_", "--strip-prefix", "--exclude", "APP_DEBUG")
// Output:
// active=false prefix="" strip=false exclude=[]
// active=true prefix="APP_" strip=true exclude=[APP_DEBUG]
}Pitfalls
- The kit's commands do not silence cobra. Mount them under a root with
SilenceErrorsandSilenceUsageset, or cobra printsError: …and the usage text after the kit has already printed the failure. Deps.InteractiveandDeps.Askmust be non-nil:ConfirmcallsInteractive()whenever a write is neither a dry run nor--yesand the printer is not in JSON mode.- JSON mode never prompts.
--jsonwithout--yesis always refused, even at a terminal, so the envelope cannot be mixed with a prompt. - A nil
Gatestill runsConfirm. No mutating kit verb runs ungated. Metaruns once at the end of a push or prune, and only under--json. If yourGatealready looked up the same values (the account for the banner), cache them for the run, for example in a field you clear in the verb'sPreRun, so the backend is asked once; the GitHub and Vercel plugins do this. AMetaerror drops the metadata and keeps the results. In cli v0.1.2 and earlier,Metaalso ran in human mode.- When a write fails half-way, the kit fails with exit 1 and keeps the results so far: in human mode as lines on stdout before the failure line on stderr, under
--jsonas thedataof the oneok:falseenvelope. Re-running is safe as long as yourSetis an upsert. NewListCmdwith an empty store printsDefaultEmptyListHint(no secrets found for this scope) in human mode. If your backend splits names across scopes, implementEmptyListHint() string(the optionalEmptyListHinterinterface) on the lister to name your own scope flag; the GitHub and Vercel plugins do. Under--jsonan empty store is{"names":[]}. In cli v0.1.2 and earlier, the hint named GitHub's--environmentand--orgfor every plugin, and a lister that returned nil printed"names":nullin JSON.AddSelectionFlagsadds only the five selection flags.--expand,--include-placeholdersand--include-emptyexist only on the kit's store verbs, where they default to expand-on and guards-on.- Cobra keeps flag values between
Executecalls on the same tree. Build a fresh tree withPlugin.Commandfor each invocation in a long-running process.
Examples: ExampleSecretWriter, ExampleNewPushCmd, ExampleNewListCmd, ExampleNewPruneCmd, ExampleVerbConfig, ExampleConfirm, ExamplePlugin, ExampleRunner, ExampleFail, ExampleCmdError, ExampleAddSelectionFlags, ExampleSkipAction.
githubplugin.New() and vercelplugin.New() return a *Plugin whose Command(deps) is the same tree dotenvctl github … and dotenvctl vercel … run. Mount it under your own root and you get the push, list and prune verbs, the confirm banner and the safety rules, without shelling out to dotenvctl. Both drive their backend CLI through Deps.Runner; the examples use a fake runner, so no gh, no vercel and no network is involved.
// ExampleNew mounts the github plugin under your own cobra root. All gh calls
// go through Deps.Runner — here a fake — and the secret value reaches gh on
// stdin, never in argv. The account is looked up once per run.
func ExampleNew() {
var out bytes.Buffer
runner := &apiGhRunner{}
src := &envkit.Selection{Pairs: []dotenv.Pair{{Key: "DB_URL", Value: "postgres://db/app"}}}
deps := providerkit.Deps{
Printer: &outfmt.Printer{Out: &out, Err: &out},
File: ".env.prod",
Source: func(providerkit.SelectOpts) (providerkit.Source, error) { return src, nil },
Runner: runner, // providerkit.ExecRunner{} in production
Interactive: func() bool { return false },
Ask: func(string) bool { return false },
}
root := &cobra.Command{Use: "mytool", SilenceErrors: true, SilenceUsage: true}
root.SetErr(io.Discard)
root.AddCommand(githubplugin.New().Command(deps))
apiGhRun(root, &out, "github", "push", "--repo", "acme/api", "--yes")
for _, c := range runner.calls {
fmt.Println(c)
}
// Output:
// target : acme/api
// account: octocat
// keys : 1
// DB_URL: pushed
// exit: 0
// gh api user --jq .login stdin=""
// gh secret set DB_URL --repo acme/api stdin="postgres://db/app"
}The gate checks every selected name against GitHub's grammar before any write and refuses the whole push if one is invalid:
// ExamplePlugin_Command shows the gate refusing a whole push when any
// selected name is not a legal GitHub secret name — nothing is written, and
// the exit code is 2 (usage).
func ExamplePlugin_Command() {
var out bytes.Buffer
runner := &apiGhRunner{}
src := &envkit.Selection{Pairs: []dotenv.Pair{
{Key: "DB_URL", Value: "postgres://db/app"},
{Key: "app.name", Value: "api"},
}}
cmd := githubplugin.New().Command(providerkit.Deps{
Printer: &outfmt.Printer{Out: &out, Err: &out},
File: ".env.prod",
Source: func(providerkit.SelectOpts) (providerkit.Source, error) { return src, nil },
Runner: runner,
Interactive: func() bool { return false },
Ask: func(string) bool { return false },
})
cmd.SilenceErrors, cmd.SilenceUsage = true, true
cmd.SetErr(io.Discard)
apiGhRun(cmd, &out, "push", "--repo", "acme/api", "--yes")
fmt.Println("gh calls:", len(runner.calls))
// Output:
// dotenvctl: key(s) [app.name] are not valid GitHub secret names ([A-Za-z_][A-Za-z0-9_]*) — rename them or select others; refusing a partial push
// exit: 2
// gh calls: 0
}The vercel plugin writes once per --target, with the value on stdin:
// ExampleNew mounts the vercel plugin under your own cobra root and pushes one
// value to two Vercel environments. Each target is one `vercel env add`, the
// value on stdin. The project line reads .vercel/project.json in the working
// directory; there is none here.
func ExampleNew() {
var out bytes.Buffer
runner := &apiVercelRunner{}
src := &envkit.Selection{Pairs: []dotenv.Pair{{Key: "DB_URL", Value: "postgres://db/app"}}}
root := &cobra.Command{Use: "mytool", SilenceErrors: true, SilenceUsage: true}
root.SetErr(io.Discard)
root.AddCommand(vercelplugin.New().Command(apiVercelDeps(&out, runner, src)))
apiVercelRun(root, &out, "vercel", "push", "--target", "production", "--target", "preview", "--yes")
for _, c := range runner.calls {
if strings.HasPrefix(c, "vercel env add") {
fmt.Println(c)
}
}
// Output:
// project: unlinked directory (vercel CLI will resolve or prompt)
// account: acme-bot
// targets: production, preview
// keys : 1
// DB_URL: pushed
// exit: 0
// vercel env add DB_URL production --force stdin="postgres://db/app"
// vercel env add DB_URL preview --force stdin="postgres://db/app"
}// ExamplePlugin_Command previews a prune: OLD exists in Vercel but not in the
// local selection, so a dry run reports it as would-delete and removes
// nothing.
func ExamplePlugin_Command() {
var out bytes.Buffer
runner := &apiVercelRunner{}
src := &envkit.Selection{Pairs: []dotenv.Pair{{Key: "DB_URL", Value: "postgres://db/app"}}}
cmd := vercelplugin.New().Command(apiVercelDeps(&out, runner, src))
cmd.SilenceErrors, cmd.SilenceUsage = true, true
cmd.SetErr(io.Discard)
apiVercelRun(cmd, &out, "prune", "--target", "production", "--dry-run")
// Output:
// project: unlinked directory (vercel CLI will resolve or prompt)
// account: acme-bot
// targets: production
// keys : 1
// OLD: would-delete
// exit: 0
}The examples share a small fake runner and a run helper, apiGhRun / apiVercelRun, defined in the same files. The helpers cut the auth-source label off the account: line, because that label comes from the real process environment.
Pitfalls
- In production pass
providerkit.ExecRunner{};ghorvercelmust be installed and logged in. A missing binary fails the gate withresolve account: …before anything is written. - The
account:banner line readsGH_TOKEN/GITHUB_TOKEN(github) orVERCEL_TOKEN(vercel) from your process environment to label the auth source. The token itself is passed to the backend CLI only through the inherited environment. - The vercel plugin reads
.vercel/project.jsonrelative to your process's working directory, not toDeps.File. In any other directory the banner saysunlinked directory. - Each push or prune looks up the target and the account once, for the banner, and reuses them for the
--jsonmetadata (ExampleNewshows the singlegh api user). In cli v0.1.2 and earlier, a push calledgh api usertwice. - Use
--repo(github) when your process does not run inside the target repository; without it the plugin asksgh repo viewfor the working directory's repo.
Examples: githubplugin.ExampleNew, githubplugin.ExamplePlugin_Command, vercelplugin.ExampleNew, vercelplugin.ExamplePlugin_Command. Flag-level docs: github plugin, vercel plugin.
dotenvcmd.Execute is the whole of dotenvctl as one function: it parses args, runs the verb, writes to the two writers you pass, and returns the exit code. It never calls os.Exit. cmd/dotenvctl/main.go is one line around it. Use it when you want every verb, flag and output format inside your own binary, or to drive the CLI in-process from tests with buffers.
// Execute runs dotenvctl in-process and returns its exit code:
// 0 ok, 1 operation failed, 2 usage error.
func Execute(args []string, stdout, stderr io.Writer, opts ...ExecuteOption) int
// WithProgramName sets the name the CLI prints for itself (failure
// prefix, --help hint, help Usage lines, --version). Empty means "dotenvctl".
func WithProgramName(name string) ExecuteOption
// Exit codes, frozen API.
const (
ExitOK = 0
ExitFailure = 1
ExitUsage = 2
)
// Context variables an exec plugin (dotenvctl-<name> on PATH) receives.
// Facts only, never secret values.
const (
EnvPluginFile = "DOTENVCTL_FILE" // absolute path of the -f file
EnvPluginJSON = "DOTENVCTL_JSON" // "1" with --json, else "0"
EnvPluginPlaceholder = "DOTENVCTL_PLACEHOLDER" // the active placeholder regexp
EnvPluginBin = "DOTENVCTL_BIN" // path of the running binary, for callbacks
EnvPluginVersion = "DOTENVCTL_VERSION" // the host version
)A complete call, from the CLI examples:
// ExampleExecute embeds the whole dotenvctl CLI in a Go program: Execute
// takes the argument list (without the program name) and two writers, and
// returns the exit code instead of calling os.Exit.
func ExampleExecute() {
dir, err := os.MkdirTemp("", "dotenvctl-")
if err != nil {
fmt.Println(err)
return
}
defer func() {
// Cleanup is best-effort; a failure goes to stderr so the example's
// checked stdout output is unaffected.
if err := os.RemoveAll(dir); err != nil {
fmt.Fprintln(os.Stderr, "cleanup:", err)
}
}()
// -f takes any path; the file holds one plain and one derived value.
envFile := filepath.Join(dir, ".env")
// 0600 because env files hold credentials.
if err := os.WriteFile(envFile, []byte("HOST=localhost\nURL=http://${HOST}:8080\n"), 0o600); err != nil {
fmt.Println(err)
return
}
code := dotenvcmd.Execute([]string{"-f", envFile, "get", "URL", "--expand"}, os.Stdout, os.Stderr)
fmt.Println("exit code:", code)
// A missing key is an operation failure: exit code 1. Its message names
// the temp path, so both writers are discarded here.
code = dotenvcmd.Execute([]string{"-f", envFile, "get", "PORT"}, io.Discard, io.Discard)
fmt.Println("exit code:", code)
// Output:
// http://localhost:8080
// exit code: 0
// exit code: 1
}Under your own program name. Embedded, failure lines and the usage hint say dotenvctl unless you pass WithProgramName with the words your users type to reach the verbs:
// ExampleExecute_programName mounts the CLI inside a host program under the
// words its users type, "myapp env": WithProgramName puts that name in the
// lines the CLI prints about itself, so a failure never names a dotenvctl
// binary the user does not have.
func ExampleExecute_programName() {
// No such verb: a usage failure, exit code 2, with the host's name in the
// message and in the hint. Stderr goes to stdout here so it is checked.
code := dotenvcmd.Execute([]string{"nosuchverb"}, os.Stdout, os.Stdout,
dotenvcmd.WithProgramName("myapp env"))
fmt.Println("exit code:", code)
// Output:
// myapp env: unknown command "nosuchverb" for "myapp env"
// Run 'myapp env --help' for usage.
// exit code: 2
}The name reaches the failure prefix, the Run '<name> --help' hint, the help Usage lines and the --version line. It does not reach the command examples inside --help (fixed text written for the dotenvctl binary), the JSON envelope (which carries no program name), or the exec-plugin lookup (still dotenvctl-<name> on PATH). The option is variadic, in the same functional-option style as the library's dotenv.Option, so every existing three-argument call compiles unchanged.
There is one in-process example of Execute per verb in cli/dotenvcmd/example_test.go (ExampleExecute_get, ExampleExecute_set, …).
The EnvPlugin* constants are the names of the variables an exec plugin gets. A Go program that is an exec plugin can read them with os.Getenv(dotenvcmd.EnvPluginFile) instead of repeating the strings.
Try it. An exec plugin is any executable named dotenvctl-<name> on PATH. This one prints its context and calls the host back:
#!/bin/sh
# dotenvctl-ctx: prints the context dotenvctl hands an exec plugin, then calls the host back.
echo "args: $*"
echo "json: $DOTENVCTL_JSON"
echo "file: $(basename "$DOTENVCTL_FILE")"
echo "placeholder: $DOTENVCTL_PLACEHOLDER"
"$DOTENVCTL_BIN" -f "$DOTENVCTL_FILE" keys$ printf 'DB_URL=postgres://db\nAPI_KEY=__TODO__\n' > .env.prod
$ dotenvctl -f .env.prod ctx --flag value
args: --flag value
json: 0
file: .env.prod
placeholder: ^__[A-Z0-9_]+__$
DB_URL
API_KEYPitfalls
Executebuilds a fresh command tree per call, so calls do not share state. It does use process-wide things: confirmation prompts reados.Stdin, interactivity is a terminal check onos.Stdin, and exec plugins inheritos.Environ()andos.Stdin.- Any first word that is not a built-in verb is looked up on
PATHasdotenvctl-<word>and run. Built-ins always win, so a PATH binary cannot shadowgithub. DOTENVCTL_BINisos.Executable(): inside your program that is your binary. A plugin's callback ("$DOTENVCTL_BIN" -f … list --json) then runs your program, so route those arguments toExecute.DOTENVCTL_VERSIONand--versionreport the version ofgithub.com/ubgo/dotenv/cliitself, read from your binary's dependency list, not your module's version. With areplaceto a local directory they reportdevel. In cli v0.1.2 and earlier, they reported your main module's version.- Messages say
dotenvctl:unless you passWithProgramName; the command examples in--helpalways saydotenvctl. In cli v0.1.2 and earlier there was no option and the prefix was fixed.
Related: Plugins for the exec-plugin protocol, Commands for every verb.
discover finds and classifies the env-file family of one directory without opening any file. envkit.Discover is a thin wrapper over it; import discover directly when you only need names and order.
// ExampleScan lists one directory's env-file family without opening any
// file. Order is distance from prod: default, local, dev, test, ci, stag,
// prod, unknown names, then contracts. Directories, editor droppings and
// files outside the family are skipped.
func ExampleScan() {
dir, err := os.MkdirTemp("", "discover-example-")
if err != nil {
fmt.Println("setup:", err)
return
}
defer func() {
// Cleanup is best-effort; a failure goes to stderr so the example's
// checked stdout output is unaffected.
if err := os.RemoveAll(dir); err != nil {
fmt.Fprintln(os.Stderr, "cleanup:", err)
}
}()
for _, name := range []string{".env.example", ".env.production", ".env.preview", ".env.local", ".env", ".env.swp", "app.env", ".envrc"} {
if err := os.WriteFile(filepath.Join(dir, name), []byte("A=1\n"), apiDiscoverFileMode); err != nil {
fmt.Println("setup:", err)
return
}
}
files, err := discover.Scan(dir)
if err != nil {
fmt.Println("scan:", err)
return
}
for _, f := range files {
fmt.Printf("%-16s %-8s contract=%t\n", f.File, f.Env, f.Contract)
}
_, err = discover.Scan(filepath.Join(dir, "missing"))
fmt.Println("missing dir is an error:", err != nil)
// Output:
// .env default contract=false
// .env.local local contract=false
// .env.production prod contract=false
// .env.preview preview contract=false
// .env.example example contract=true
// missing dir is an error: true
}Classify labels one filename. Use it for explicit file arguments, so they get the same labels discovery gives:
// ExampleClassify labels one filename with the same vocabulary Scan uses.
// Suffixes are matched case-insensitively and long forms collapse; only a
// whole-suffix junk name is ignored, so .env.prod.bak is a new, unknown
// environment called "prod.bak".
func ExampleClassify() {
for _, name := range []string{".env", ".env.Staging", ".env.dist", ".env.bak", ".env.prod.bak", "config.env"} {
ef, ok := discover.Classify(name)
fmt.Printf("%-14s ok=%-5t env=%q contract=%t\n", name, ok, ef.Env, ef.Contract)
}
fmt.Println(discover.EnvDefault)
// Output:
// .env ok=true env="default" contract=false
// .env.Staging ok=true env="stag" contract=false
// .env.dist ok=true env="dist" contract=true
// .env.bak ok=false env="" contract=false
// .env.prod.bak ok=true env="prod.bak" contract=false
// config.env ok=false env="" contract=false
// default
}Pitfalls
- The order is fixed:
default,local,dev,test,ci,stag,prod, then unknown names, then contracts; ties break by filename. - Only
.envand.env.<suffix>are candidates.app.envand.envrcare not. - Junk is matched on the whole suffix (
bak,tmp,old,orig,swp,swo,lock)..env.prod.bakis not junk: it becomes an unknown environment namedprod.bak. - Suffixes are lowercased, so
.env.Stagingisstag;Envfor unknown names is lowercased too. Pathjoins the directory as you gave it, without cleaning, so./stays in printed paths.
Examples: ExampleScan, ExampleClassify.
report renders a matrix or a diff as one self-contained HTML page: inline CSS, no JavaScript, no external requests, light and dark themes. Write the bytes with os.WriteFile; this is what dotenvctl matrix --format html -o FILE does.
// ExampleMatrixHTML renders a drift matrix as one self-contained HTML page.
// Fill Value only when Revealed is true; a masked page shows each cell's
// state symbol, never a value. The page embeds a generation timestamp, so
// two renders are not byte-identical.
func ExampleMatrixHTML() {
m := report.Matrix{
Envs: []string{"stag", "prod"},
Sources: []string{".env.stag", ".env.prod"},
Rows: []report.MatrixRow{{
Key: "DB_URL",
Cells: []report.MatrixCell{
{State: string(envkit.StatePresent), Symbol: envkit.StateSymbols[envkit.StatePresent]},
{State: string(envkit.StateMissing), Symbol: envkit.StateSymbols[envkit.StateMissing]},
},
}},
}
page, err := report.MatrixHTML(m)
if err != nil {
fmt.Println("render:", err)
return
}
fmt.Println(bytes.HasPrefix(page, []byte("<!doctype html>")))
fmt.Println(bytes.Contains(page, []byte("<script")), bytes.Contains(page, []byte("CONTAINS SECRETS")))
// Output:
// true
// false false
}// ExampleDiffHTML renders a diff page. With Revealed false every value cell
// is report.MaskGlyph, even if a value was passed in; with Revealed true the
// values appear and the page carries a "contains secrets" banner.
func ExampleDiffHTML() {
d := report.Diff{
FileA: ".env.stag",
FileB: ".env.prod",
Changed: []report.DiffChange{{Key: "DB_URL", From: "postgres://stag", To: apiReportSecret}},
}
for _, reveal := range []bool{false, true} {
d.Revealed = reveal
page, err := report.DiffHTML(d)
if err != nil {
fmt.Println("render:", err)
return
}
fmt.Printf("revealed=%t secret=%t glyph=%t banner=%t\n", reveal,
bytes.Contains(page, []byte(apiReportSecret)),
bytes.Contains(page, []byte(report.MaskGlyph)),
bytes.Contains(page, []byte("CONTAINS SECRETS")))
}
// Output:
// revealed=false secret=false glyph=true banner=false
// revealed=true secret=true glyph=false banner=true
}Masking is structural. With Revealed false the templates never print a value: matrix cells show their state symbol, and diff cells show report.MaskGlyph (••••••, fixed width, so value lengths leak nothing too). With Revealed true, the page shows values and a "contains secrets" banner.
Pitfalls
- The page includes a generation timestamp, so two renders of the same input differ. Do not compare report files byte for byte.
- The report types are separate from envkit's. Copy
Envs,Sources, rows,State(as a string) andSymbol(fromenvkit.StateSymbols) across yourself, and leaveValueempty unless you setRevealed. - In a revealed matrix only
presentandplaceholdercells show a value; the other states show their symbol.
Examples: ExampleMatrixHTML, ExampleDiffHTML.
textdiff.Lines is the preview behind every --dry-run: -old / +new lines for the one region where two renderings differ, or nil when they are identical.
// ExampleLines previews an edit as "-old"/"+new" lines for the one region
// that changed. Identical input returns nil, which callers read as "no-op".
// It trims the common prefix and suffix; it is not a general diff.
func ExampleLines() {
before := "# db\nDB_HOST=localhost\nDB_PORT=5432\n"
after := "# db\nDB_HOST=db.prod\nDB_PORT=5432\n"
for _, l := range textdiff.Lines(before, after) {
fmt.Println(l)
}
fmt.Println(textdiff.Lines(before, before) == nil)
// Two separate edits come back as one block spanning both.
fmt.Println(textdiff.Lines("A=1\nB=2\nC=3", "A=9\nB=2\nC=8"))
// Output:
// -DB_HOST=localhost
// +DB_HOST=db.prod
// true
// [-A=1 -B=2 -C=3 +A=9 +B=2 +C=8]
}Pitfalls
- It trims the common prefix and suffix and reports everything between as one block. Two edits far apart come back as one block spanning both. That is right for single-entry edits, which is what it is for; it is not a general diff.
- Nil means "no change". An empty, non-nil slice is never returned.
Examples: ExampleLines.
outfmt.Printer is dotenvctl's single output seam. Use it when your tool should print the same {ok,data|error} envelope scripts already parse from dotenvctl. Human mode prints lines and OK is silent; JSON mode prints exactly one envelope and Human is silent, so you can call both without checking the mode.
// ExamplePrinter prints the same verb in both modes. Human mode prints lines
// and OK is silent; JSON mode prints exactly one envelope per call and Human
// is silent, so --json output stays parseable.
func ExamplePrinter() {
for _, jsonMode := range []bool{false, true} {
p := &outfmt.Printer{Out: os.Stdout, JSON: jsonMode}
p.Human("DB_URL")
p.Humanf("%d keys", 1)
if err := p.OK(apiOutfmtPayload{Keys: []string{"DB_URL"}}); err != nil {
fmt.Println("write:", err)
}
}
// Output:
// DB_URL
// 1 keys
// {"ok":true,"data":{"keys":["DB_URL"]}}
}// ExamplePrinter_Fail reports a failure. Human mode prints
// "<Program>: <msg>" to Err (os.Stderr when Err is nil, so a captured value
// never contains an error); JSON mode prints the error envelope on Out.
// Program defaults to "dotenvctl". Fail only prints: the exit code is yours
// to return. Err is os.Stdout here only so the Example can show the line.
func ExamplePrinter_Fail() {
human := &outfmt.Printer{Out: os.Stdout, Err: os.Stdout}
hosted := &outfmt.Printer{Out: os.Stdout, Err: os.Stdout, Program: "myapp env"}
machine := &outfmt.Printer{Out: os.Stdout, JSON: true}
for _, p := range []*outfmt.Printer{human, hosted, machine} {
if err := p.Fail(outfmt.CodeNotFound, `key "DB_URL" not found`); err != nil {
fmt.Println("write:", err)
}
}
// Output:
// dotenvctl: key "DB_URL" not found
// myapp env: key "DB_URL" not found
// {"ok":false,"error":{"code":"not_found","message":"key \"DB_URL\" not found"}}
}The error codes are a closed set that scripts branch on:
// ExampleErrCode lists the closed set of error codes scripts branch on.
func ExampleErrCode() {
for _, c := range []outfmt.ErrCode{outfmt.CodeNotFound, outfmt.CodeIO, outfmt.CodeRequired, outfmt.CodeUsage, outfmt.CodeExec, outfmt.CodeDiff} {
fmt.Println(c)
}
// Output:
// not_found
// io
// required
// usage
// exec
// diff
}Pitfalls
- In human mode
Failwrites toErr, and a nilErrmeansos.Stderr, so a test that only setsOutsees no failure line; setErrtoo. Under--jsonthe failure envelope goes toOut. The human line starts withProgram(defaultdotenvctl, seeProgramName). In cli v0.1.2 and earlier,Failwrote toOutin both modes and the prefix was fixed. Failonly prints. Return an exit code yourself, or useproviderkit.Fail, which also builds the*CmdError.- One invocation, one envelope. When an operation fails part-way, use
FailWith(code, message, data)rather thanOKfollowed byFail: under--jsonit prints a singleok:falseenvelope that carriesdata(the partial record) next toerror. The kit'spushandprunedo this. - Pass a named struct to
OK, not a map, so the JSON shape is visible where it is produced. Human/Humanfdrop write errors on purpose;OKandFailreturn them.
Examples: ExamplePrinter, ExamplePrinter_Fail, ExampleErrCode.
Every exported identifier, by package. Signatures live in go doc; this table is the map.
| Kind | Identifier | Purpose |
|---|---|---|
| func | Select(f, opts) / SelectFile(path, opts) |
apply the selection grammar to a parsed file / a path |
| func | Discover(dir) / Inventories(opts) |
find the env-file family / summarize each file |
| func | BuildMatrix(opts) |
the keys × environments drift table |
| func | DriftRows(rows) |
keep only rows that aren't uniformly present (filters in place) |
| func | SparseColumn(m, rowsBefore) |
diagnose an ineffective drift filter (returns env, missing count, ok) |
| func | DisambiguateColumns(cols) |
make column labels unique when two files classify alike |
| func | EnvNameForPath(path) |
label an explicit path with discovery's vocabulary |
| func | Diff(a, b, opts) / DiffMaps(a, b, expanded) |
effective-config comparison of two files / two maps |
| func | Set / Unset / Restore |
byte-preserving edits |
| func | Run(ctx, path, argv, opts) |
execute with the file's values; returns the child's exit code |
| func | ChildEnv(path, base, sel) / MergeEnv(base, values) |
build a child environment (file wins) |
| type | SelectOptions, Selection, Skip, SkipReason |
selection inputs and results |
| type | Matrix, MatrixRow, MatrixCell, MatrixOptions, CellState |
matrix types |
| type | DiffResult, DiffPair, DiffChange, DiffOptions |
diff types |
| type | EditOptions, EditResult |
edit types |
| type | Inventory, InventoryOptions, EnvFile |
discovery types (EnvFile = discover.EnvFile) |
| type | RunOptions |
execution options |
| const | DefaultPlaceholderPattern, SparseColumnThreshold |
the __LIKE_THIS__ pattern; the sparse-column trigger share (0.6) |
| const | SkipPlaceholder, SkipEmpty |
skip reasons |
| const | StatePresent, StateEmpty, StatePlaceholder, StateDisabled, StateInherited, StateMissing |
cell states |
| var | StateSymbols |
state → glyph, shared by every renderer |
| var | ErrAnchorNotFound, ErrKeyNotFound |
sentinels for errors.Is |
Methods worth knowing: Selection.Names() / SkippedNames() / Map(), Matrix.HasContractGaps(), MatrixCell.Raw(), DiffResult.Empty().
| Kind | Identifier | Purpose |
|---|---|---|
| type | Plugin |
the one mandatory contract: Command(Deps) *cobra.Command |
| type | Deps |
everything a plugin receives from the host: Printer, File, Source, Runner, Interactive, Ask |
| type | SelectOpts = envkit.SelectOptions, Source = *envkit.Selection, Skip = envkit.Skip |
aliases — one grammar, no translation |
| type | SecretWriter, SecretLister, SecretDeleter, EmptyListHinter |
capability interfaces; implement what your backend truly supports (EmptyListHinter is optional: the empty-list hint, default DefaultEmptyListHint) |
| type | Runner, ExecRunner |
the injectable exec seam and its production implementation |
| type | VerbConfig, Gate, GateInfo |
per-verb customization: gate (banner + confirm) and --json metadata |
| type | Action, Result, CmdError |
the outcome vocabulary and the exit-code carrier |
| func | NewPushCmd, NewListCmd, NewPruneCmd |
generate the standard verbs for your capabilities |
| func | Confirm(deps, info) |
the standard prompt/--yes contract |
| func | Fail(printer, code, format, …) |
emit a failure and return the right exit code |
| func | AddSelectionFlags(cmd, sel) |
bind the five shared selection flags to any command |
| func | SelectionActive(sel) |
did the user actually select something? |
| func | SkipAction(reason) |
map a selection guard reason to a push action |
| const | ActionPushed, ActionWouldPush, ActionSkippedPlaceholder, ActionSkippedEmpty, ActionDeleted, ActionWouldDelete, ActionKeptSkipped, ActionKeptFlag |
the closed action set |
| Package | Surface |
|---|---|
plugins/githubplugin |
New() *Plugin, (*Plugin).Command(providerkit.Deps) *cobra.Command |
plugins/vercelplugin |
New() *Plugin, (*Plugin).Command(providerkit.Deps) *cobra.Command |
dotenvcmd |
Execute(args, stdout, stderr) int, ExitOK/ExitFailure/ExitUsage, EnvPluginFile/EnvPluginJSON/EnvPluginPlaceholder/EnvPluginBin/EnvPluginVersion |
discover |
Scan(dir), Classify(filename), EnvFile, EnvDefault |
report |
MatrixHTML(Matrix), DiffHTML(Diff), types Matrix/MatrixRow/MatrixCell/Diff/DiffPair/DiffChange, MaskGlyph |
textdiff |
Lines(before, after) |
outfmt |
Printer (fields Out, Err, Program, JSON) with OK/Fail/FailWith/Human/Humanf/ProgramName, DefaultProgram, ErrCode and its constants (CodeNotFound, CodeIO, CodeRequired, CodeUsage, CodeExec, CodeDiff) |
Every command maps to a call, so a script can graduate to a program without changing behaviour:
| CLI | Go |
|---|---|
dotenvctl get KEY --expand |
dotenv.Open + f.GetExpanded(key) |
dotenvctl list --prefix P --strip-prefix |
envkit.SelectFile(path, envkit.SelectOptions{Prefix: "P", StripPrefix: true}) |
dotenvctl keys --exclude-prefix P |
same, reading Selection.Names() |
dotenvctl set K=V --after ANCHOR --dry-run |
envkit.Set(path, pairs, envkit.EditOptions{Anchor: "ANCHOR", DryRun: true}) |
dotenvctl unset K / --delete |
envkit.Unset(path, keys, envkit.EditOptions{Delete: …}) |
dotenvctl restore K |
envkit.Restore(path, keys, envkit.EditOptions{}) |
dotenvctl envs --dir D |
envkit.Inventories(envkit.InventoryOptions{Dir: "D"}) |
dotenvctl matrix --contract C --only-drift |
envkit.BuildMatrix(…{ContractPath: "C", OnlyDrift: true}) |
dotenvctl diff A B --expand |
envkit.Diff("A", "B", envkit.DiffOptions{Expand: true}) |
dotenvctl matrix --format html -o F |
report.MatrixHTML(...) + os.WriteFile |
dotenvctl run -- cmd args |
envkit.Run(ctx, path, argv, envkit.RunOptions{Base: os.Environ()}) |
dotenvctl github push … |
mount githubplugin.New().Command(deps), or call providerkit.NewPushCmd with your own store |
dotenvctl vercel push … |
mount vercelplugin.New().Command(deps) |
| any of the above, verbatim | dotenvcmd.Execute(args, stdout, stderr) |
Two deliberate differences: the CLI's --expand default differs by verb (off for reads, on for pushes) while SelectOptions.Expand is explicit, and the CLI maps errors to exit codes while the Go API returns them.
envkit, providerkit, the plugins, dotenvcmd.Execute and its exported constants, and the helper packages are the public Go surface. Their exported signatures are API, and breaking one is a major-version event. The CLI's flag names and --json envelope are covered by the same promise. Unexported identifiers in dotenvcmd are not.
- Commands — every CLI verb and flag.
- Multi-environment —
envs,matrixanddifffrom the terminal. - Plugins — the plugin contract and exec plugins; github and vercel plugin pages.
- Feature index — every feature with its guide and Example.
- The library itself: README.