All jobs

Add a Config File to a Go CLI

Yes. An agent adds a user config file to your Go command-line tool so flags get persistent defaults, with precedence tests, docs and a PR you pick up later.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads how the tool takes options today. In a CLI shaped like muesli/duf, every option is a github.com/spf13/pflag flag declared at package level in main.go: --all, --hide, --hide-fs, --hide-mp, --only, --only-fs, --only-mp, --output, --sort with default mountpoint, --width, --theme whose default comes from defaultThemeName() in themes.go by checking the terminal background, --style whose default comes from defaultStyleName() in style.go, --avail-threshold defaulting to 10G,1G, --usage-threshold defaulting to 0.5,0.9, plus --inodes, --json, --warnings and --version. main() calls flag.Parse() and then validates each value in turn with loadTheme, parseStyle, parseColumns and stringToSortIndex. There is no config file, no environment variable and no --config flag; a user who always wants --theme light --sort size types it every time.

It designs the file around what is already there. The format is JSON read with encoding/json, which main.go already imports for --json output, so no new module enters go.mod; the pull request says a TOML file would need a dependency and leaves that as a choice. The default path is duf/config.json under os.UserConfigDir(), which gives the platform directory on Linux, macOS and Windows, the three the build matrix in .github/workflows/build.yml covers, and a new --config flag overrides it. Precedence is the part that must be right: defaults, then the file, then flags on the command line. pflag records which flags were set with flag.CommandLine.Changed(name), so the loader applies a file value only to flags the user did not pass, by calling flag.Set on the named flag. That keeps every validation in main() untouched, because by the time it runs the flag values are what they would have been had the user typed them.

The loader lives in a new config.go with a struct whose fields mirror the flag names, a loadConfig(path string) that returns no error when the file is absent and a wrapped error when it is malformed, and a applyConfig that walks the fields and sets unchanged flags. Tests go in config_test.go using t.TempDir(): a file with theme and sort set, run with no flags, and with --sort used on the command line, asserting that the file wins over the default and the flag wins over the file, plus a malformed file and a missing file. Since .golangci.yml enables gosec, the agent expects a G304 report on reading a path from a variable and clears it with filepath.Clean and a comment, running golangci-lint run locally with the repository's config rather than disabling the linter.

Documentation follows the repository's own machinery. README.md gets a short Configuration section under Usage with the path per platform and an example file. The man page is not edited by hand: man.go builds it from the flag set under the mango build tag, and the manpage workflow runs go build -v -tags mango and commits duf.1, so the new --config flag appears there on the next push to master. The agent runs go build ./..., go test ./... and go vet ./... as build.yml does, and go build -tags mango to confirm the man page still generates.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add a user config file to this Go CLI. Read go.mod, main.go, themes.go, style.go, man.go, mounts_linux_test.go, .golangci.yml, .goreleaser.yml, README.md and the workflows under .github/workflows first, and list every pflag flag with its default. Use encoding/json, which main.go already imports, and add no new module. Read the file from duf/config.json under os.UserConfigDir() by default, with a new --config flag to override the path. Apply a file value only to flags the user did not set on the command line, detected with flag.CommandLine.Changed, by calling flag.Set so the existing validation in main runs unchanged. A missing file is not an error; a malformed one is, with the path in the message. Put the loader in config.go and tests in config_test.go that use t.TempDir and cover default, file and flag precedence, a missing file and a malformed file. Run go build ./..., go test ./..., go vet ./..., golangci-lint run with the repository config, and go build -tags mango to confirm the man page still generates. Add a Configuration section to README.md and open a pull request that shows the precedence rule and the test output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request on its own branch that adds config.go and config_test.go, declares a --config flag beside the others in main.go, calls the loader between flag.Parse() and the first validation, and adds a Configuration section to README.md. go.mod and go.sum are unchanged, which the description points out, and duf.1 is left for the manpage workflow to regenerate.

The description states the precedence rule in one line, shows an example config.json, lists the flags the file can set, and quotes go test ./... with the new tests named, go vet, the golangci-lint result including how the gosec file-read finding was handled, and the -tags mango build. It also notes that --json output and --version take their early exits in main() before the filters and theme are read, so the file does not change them, and why.

Before merging, a reviewer runs the binary with a config file and a conflicting flag to feel the precedence, checks that a bad file produces a readable error with its path rather than a stack trace, and decides whether the Homebrew cask and nfpm packages in .goreleaser.yml should ship an example file. A follow-up on the same session can add that without starting over.

Run it on every feature you want to hand off

This is the kind of change an engineer starts and leaves: a POST /o/{org}/sessions with this prompt and the repository in resources from the terminal, then the laptop closes. The run keeps going in its own sandbox and the result is a pull request to read in the morning. The sandbox parks with its disk when the turn ends, so a follow-up such as also read DUF_CONFIG from the environment wakes it with the branch, the module cache and the built binary still there.

Give the API key a webhook URL and Rush posts run.completed or run.failed with the session_url when each turn ends, so the pull request link reaches the channel where the team reads. A team with several small CLIs can send the same prompt to each repository, one run per repository, and each run reads that tool's own flag set.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

The hard part of a config file is not parsing it, it is the precedence rule and the edges: a flag that was set to its default value on purpose, a file that exists but is empty, a path that differs per platform. Those need tests that run, and a check across the three operating systems the build matrix already covers. The agent writes the tests and runs them in its own sandbox, with the repository's own linter config, before anyone reads the diff.

The record is the argument for the design. The transcript shows the agent reading main.go's flag declarations and flag.Parse() placement, choosing Changed over a custom tracking map, and running golangci-lint rather than guessing what gosec would say. A reviewer who disagrees with JSON over TOML can say so in a follow-up and the parked sandbox makes the change with the tests already in place.

Frequently asked questions

Why JSON and not TOML or YAML?

Because main.go already imports encoding/json for the --json flag, so the file costs no new dependency and go.mod stays as it is. The pull request names the TOML option and what module it would add, so the maintainer can ask for it in a follow-up if users would prefer it.

Does a flag on the command line always win over the file?

Yes. The loader only touches flags that flag.CommandLine.Changed reports as unset, so anything typed wins, including a flag set to the same value as its default. The tests in config_test.go cover that case explicitly.

Where does the file live on each platform?

Under os.UserConfigDir() in a duf directory, which resolves to the XDG config directory on Linux, Application Support on macOS and AppData on Windows. The --config flag points at any other path, and the README section lists all three locations.

Will the man page document the new flag?

Yes, without a manual edit. man.go generates the page from the pflag set under the mango build tag and the manpage workflow commits duf.1 on push to master, so --config appears there with the same description string as --help.

Does the config file affect --json output?

No. In main.go the --json branch runs renderJSON on every mount right after the mount table is read, before the filters, sort column, theme and style are validated, so none of those settings reach JSON output today and the file does not change that. The pull request describes that order so nobody expects a config value to change JSON.

More Go CLI jobs

The same job on other stacks

Keep reading