Everyone reads your config. This one writes it back.

Thu, 23 Jul 2026 00:00:00 +0000

There’s a particular small betrayal I got tired of. You write a config file by hand. You leave a comment above the timeout explaining why it’s thirty seconds and not five, because the last person who dropped it took the site down. You group the keys the way that makes sense in your head. Then your tool changes one value, writes the file back out, and hands you an alphabetised slab of YAML with every comment gone… and the database password that used to live in an environment variable now sitting in the file, committed to git.

The value it changed is correct. Everything a person put there is gone.

That isn’t a bug in anything. It’s what “serialise the merged view” means: fold every source into one map, and a writer holding that map has nothing to write back but the whole of it. Most config libraries do exactly this, because reading is the job, and writing… writing was never really the point.

I know, because for years I was fine with it too.

I didn’t set out to build a config library. A long time ago I wrote a thin wrapper over Viper to do one small thing it left to the caller: load a handful of config files and merge them in a defined order, so I wasn’t writing the same loop into every project. Viper did everything else, and did it well. My bit closed a gap you could measure in inches, and it worked well enough that it followed me from one project to the next for a very long time, barely changing shape. Viper did the work, my wrapper handled the loading, and that was that.

Then the gaps stopped being measured in inches. When go-tool-base came together and the config piece finally got some proper attention, I kept adding the things Viper had always left to me. Typed sections that stay current across a reload. Validation. Hot-reload that fails closed instead of swapping in a half-broken file the moment someone fat-fingers the YAML. Each one was a reasonable little workaround on its own. Stacked up, they’d turned into a description of a different component than the one I was wrapping.

The thing that finally decided it was, of all things, a comment. Someone wanted a write that kept the file intact and touched only the key that owned it, and there’s no wrapping your way to that. The information you’d need is thrown out during the merge, long before anyone gets round to writing. Viper couldn’t give it to me, and neither could anything else, because they’d all made the same trade for the same sensible reason.

So I stopped wrapping and built the thing underneath. It’s now a small family of modules, all public: config, and a growing set of adapters around it.

The file is a document, not a dump

config never folds its layers away. It keeps every source as its own layer, in precedence order, and a write lands in the layer that owns the key you changed. So when you do this:

store.Apply(ctx, config.Set("server.port", 9090))

it changes server.port, and nothing else. The comment above it survives. The key order survives, the quoting, the anchors. The password that arrived from the environment stays in the environment, because the store knows that’s where it came from and doesn’t go pasting it into a file. If a change can’t actually take effect, because a higher layer is shadowing the key you aimed at, it tells you, rather than writing something that will never be read.

This is the bit the rest of the field mostly doesn’t do. Viper is the one everyone reaches for, and its WriteConfig marshals its internal map straight back to disk; its own maintainers will tell you it’s a dump, not an editor, and not meant for updating a file you care about. koanf, the cleaner, modern one I genuinely rate, simply doesn’t write at all… a deliberate call to keep the library small, and a fair one. conflex has a dumper that re-serialises the merged map, same as Viper. Every one of them can put a value on disk. I haven’t found one that can do it without flattening the file a person actually wrote.

Where the value came from

The other thing falls out of keeping the layers apart. When a value can be set by a default, a file, an environment variable and Consul, “which one won, and why?” stops being academic the first time you’re staring at the wrong value at two in the morning.

store.View().Explain("database.host")
// database.host = db-prod (from env:APP_DATABASE_HOST); also defined in /etc/app/config.yaml

It’ll name the source that won and the ones it beat. None of the readers can answer that, and it’s not a small omission on their part… it’s structural. Once you’ve merged everything into one map, the map is all you have. The provenance was thrown away at the door. Because config records it during the merge instead of reconstructing it after, the answer’s just there when you go looking.

The same store, whatever you point it at

Everything so far is what config does with a source. The other half is how many things get to be one, and it’s where the little modules earn their keep. Three questions, and you only ever compile the answers you use.

What format is it in? YAML out of the box; anything else through its own small adapter, config-json, config-toml, config-hcl and the rest, one module per format so a consumer who wants TOML pays for a TOML parser and nobody else does. That “a module per source” instinct isn’t mine alone, mind you… it’s how koanf is built, and it’s the right shape.

Where does the file live? On disk usually, and that’s built in. But it might be baked into the binary, sat on a box you reach over SSH, or in an S3 bucket, and each of those is just another filesystem config reads and writes through an adapter, config-sftp, config-aws-s3, config-gcp-gcs and the rest. The same store that rewrites one key in /etc/app.yaml and leaves the comments around it alone does exactly that to a file living in an S3 bucket, and mostly doesn’t care about the difference.

Or is it a file at all? config-consul makes a Consul store an ordinary layer, with the same precedence and provenance a file gets, and behind it the cloud parameter stores: config-aws-ssm, config-azure-appconfig, config-gcp-parameter. Everyone reads these; Viper reads Consul, koanf reads Vault. The part I haven’t seen elsewhere is that Consul writes back: a change goes home as a compare-and-swap, so if the value moved under you since you read it, the write fails cleanly instead of stamping on whatever’s there now. The “keep the file yours” idea, pointed at a distributed key-value store.

Secrets managers are next. But the shape’s set now: whatever your config is written in, wherever it lives, it’s the same layered store, and a two-way street.

It’s already running

This isn’t a library out looking for a first user. go-tool-base, the toolkit all of this was pulled out of, runs on config now and is finishing its own move off Viper. The framework it came from is the thing eating its own dog food, which is roughly how I like to find out whether something actually holds up before I ask anyone else to trust it.

The docs, all of it, live at config.go.phpboyscout.uk.

It started because I was annoyed about a deleted comment. Turns out that annoyance was load-bearing.

Provenance on PHP Boy Scout

Everyone reads your config. This one writes it back.

The file is a document, not a dump

Where the value came from

The same store, whatever you point it at

It’s already running