Short decision guides for the questions people ask before they write code: which call, which option, which tool, which backend.
Each guide has a decision table, "if X, use Y" rules, the pitfalls that catch people, and for every option a link to its full guide and a runnable Example. Every claim was checked against the code and its tests.
| Guide | Answers |
|---|---|
| How to read a file | Read vs Open vs Parse vs ParseReader; which accessor for which question |
| How to edit a file | the Set family vs Append / Insert*; Unset vs delete; Clone vs rebuilding; Save vs SaveAs |
| Which expansion setup | Get vs GetExpanded vs ExpandedMap; which ${…} operator; escape dialect; command substitution on or off |
| Which plugin hook | which option or capability for a need: env fallback, secret stores, decryption, save rules, auditing, sandboxed commands |
| CLI, library or embedding | dotenvctl vs the dotenv package vs envkit vs dotenvcmd.Execute |
| Which sync backend | GitHub vs Vercel vs your own exec plugin vs a providerkit plugin |
| Options for your kind of app | a 12-factor service, a CLI tool that edits files, a CI pipeline, a monorepo, Docker Compose compatibility |
| If you want to… | Use | Guide | Example |
|---|---|---|---|
| Load config values and never write the file | dotenv.Read(path) |
reading, step 1 | ExampleRead |
| Change a value and save without losing comments | Open → Set → Save |
editing, step 1 | ExampleFile_Set |
Generate a .env.example with sections |
NewComment / NewPair / NewBlank + Append |
editing, step 7 | ExampleFile_Append |
Derive .env.prod from .env.staging |
Clone → Set → SaveAs |
editing, step 9 | ExampleFile_Clone |
| Bind values to a typed struct | Read + a binder |
typed configuration | Example_typedConfig |
| Fail CI when an environment misses a key | dotenvctl matrix --contract .env.example |
recipes | ExampleBuildMatrix |
| Push part of a file to GitHub Actions secrets | dotenvctl github push --prefix … |
GitHub plugin | ExamplePlugin_Command |
- Documentation home and learning path
- Feature index: every feature with its guide and example