Guides, decision pages and runnable examples for every textdata module: the dotenv and jsonc libraries, the value plugins, the textdatactl and dotenvctl command lines, and the push providers. Every snippet in the guides is copied from a program under examples/ that the test suite builds and runs, and every "Try it" output is real.
Follow the steps in order the first time; each one builds on the previous. Every step names what you learn, the guide, and the program to run (cd examples/<area>/<name> && go run .).
| # | Step | What you learn | Guide | Example |
|---|---|---|---|---|
| 1 | First read | go get, read a .env and a JSONC file into a map, open them as documents, read by path, decode into a struct |
Install and read your first file | getting-started/first-read |
| 2 | Edit and save | change one value, save atomically, and see that every other byte is unchanged | Edit and save | getting-started/edit-save |
| 3 | dotenv syntax and reading | quoting, multi-line values, comments, duplicates, escapes; Read vs Open vs Parse; entries and kinds |
dotenv syntax, reading, entries | dotenv/syntax, dotenv/reading |
| 4 | Expansion | ${VAR}, the Compose operators, ${NAME:?} for required values, $(cmd) off by default, typed config |
dotenv expansion, typed config | dotenv/expansion, dotenv/typed-config |
| 5 | Edit a .env file properly |
Set vs SetAfter, comment out and restore, generate, clone to another environment, save modes |
dotenv editing, saving | dotenv/editing, dotenv/clone-env |
| 6 | JSONC read and edit | strict JSON, typed getters, paths and JSON Pointer, positions, Set, arrays, comments, Disable/Restore, Save |
parse and strict, read and paths, edit, save | jsonc/read-config, jsonc/edit-config |
| 7 | Layered config | a base file plus overrides with Merge, or "$extends" with an includer |
merge and clone, extends | jsonc/merge-layers, jsonc/extends |
| 8 | Lint, schema, format | lint rules, Validator plugins, JSON Schema from a struct with file:line:col issues, formatting and diffing |
lint and validate, schema, format, diff | jsonc/lint, jsonc-tools/schema-plugin |
| 9 | Secrets with value plugins | Lookuper vs Resolver, one plugin in both formats, gopass, file, Vault, AWS | plugins overview, then your backend | plugins/file-confined, plugins/vault-httptest |
| 10 | The command line | textdatactl, every dotenv and jsonc verb, --json, exit codes, run |
textdatactl, dotenvctl, jsonc CLI | cli/verb-tour, cli/run-child |
| 11 | Many environments | envs, the drift matrix with a contract as a CI gate, diff, HTML reports |
multi-env, recipes | cli/verb-tour |
| 12 | Push to GitHub and Vercel | select keys by prefix, guards for placeholders, dry runs, prune | selection, GitHub, Vercel | providers/github, providers/selection |
| 13 | Embed and extend the tools | run the CLIs in process, the envkit operations API, exec plugins, your own push provider |
embedding, envkit, exec plugins, write a provider | cli/embed-dotenvctl, cli/envkit-ops, providers/fake-provider |
| 14 | Write a plugin, test a format | the plugin abilities, your own Resolver and SaveGuard, the expand engine, the property harness | write a value plugin, base plugin, texttest | plugins/custom-resolver, base/property-harness |
| You want to | Read | Run |
|---|---|---|
| Load config at startup into a struct | dotenv typed config, jsonc decode | dotenv/typed-config, jsonc/read-config |
| Change one value in a file people commit, without reformatting it | Edit and save, jsonc edit | getting-started/edit-save |
| Keep secrets out of the file | Which value plugin, plugins overview | plugins/vault-httptest |
| Fail fast when a required value is missing | dotenv RequiredError, jsonc | dotenv/expansion |
| Check in CI that every environment defines every key | multi-env › contract | cli/verb-tour |
| Check a hand-written JSONC config against a schema | schema | jsonc-tools/schema-plugin |
| Format or diff JSONC files | format, diff | jsonc-tools/format, jsonc-tools/diff |
| Generate a commented config file from a struct | generate | jsonc-tools/generate-from-struct |
| Push deploy secrets to GitHub Actions or Vercel | GitHub, Vercel | providers/github |
| Run a command with a file's values | dotenvctl run, envkit child env | cli/run-child |
| Give your own CLI the dotenv or jsonc verbs | embedding | cli/embed-jsonc |
| Refuse to save a private key or an invalid file | base plugin › SaveGuard, jsonc save › SaveGuard | base/registry |
| Run a command with a timeout, on any OS, without leaking its output | shell | shell/run, shell/errors |
Expand one config value (${VAR}, $(cmd), ${gopass:…}) outside a .env or JSONC file |
value | value/env, value/secrets |
Fail instead of reading a missing variable or unknown ${scheme:…} as "" |
value § Step 7, dotenv, jsonc | value/strict, jsonc/strict-config |
| Edit one file from several processes without losing edits | atomicfile lock, jsonc Update, dotenv Update | base/file-lock, jsonc/update-config |
| Support a new secret store | write a value plugin | plugins/custom-resolver |
| Decide between options | Choosing | - |
| Find any feature | Feature index | - |
Your code or a shell calls a format (dotenv, jsonc), directly or through the CLI layer; the formats are built on the stdlib-only base packages and never touch the process environment. Value plugins plug into the base's plugin interfaces; push providers plug into the CLI.
- Overview
- Which format and which modules
- Which method for the main workflows
- Which value plugin or secret backend
- Options for your kind of app
- Library, CLI or embedding the CLI
Getting started (index)
dotenv (index)
jsonc (index)
- Parse JSONC and strict JSON
- Read values and paths
- Edit a document
- Disable and restore a member
- Merge and clone
- Layer files with $extends
- Expansion and plugins
- Lint and validate
- Save a document safely
jsonc tools (index)
Value plugins (index)
Command line (index)
- dotenvctl command reference
- jsonc CLI
- Multi-environment tools
- Recipes
- Exec plugins
- Embed the CLIs
- envkit: the operations API in Go
Push providers and clikit (index)
Base packages (index)
- Plugins: one interface set for every format
- The expand engine
- Run a command: shell
- Expand one value: value.Expand
- Atomic writes
- Paths and positions
- Testing a format with texttest
- Feature index: every feature, its package, the guide step and the example
- Module READMEs: base, dotenv, dotenv/cli, jsonc, jsonc/cli, clikit, textdatactl, GitHub provider, Vercel provider, plugins gopass, file, extends, vault, aws
- API reference: pkg.go.dev/github.com/ubgo/textdata