# Add a Nix Flake to a Go CLI

Yes. An agent writes a flake.nix that builds your Go CLI with buildGoModule, installs its completions and man page, adds a dev shell, builds it and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-nix-flake/go-cli/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent clones the CLI into its own cloud sandbox and reads how it is built and released before writing a derivation. In a CLI like charmbracelet/glow, `go.mod` names the module `charm.land/glow/v3` with a `go 1.26.7` directive, and `go.sum` is checked in. `main.go` declares `Version` and `CommitSHA` as empty package variables that the release fills in; `.goreleaser.yml` includes a shared config from `charmbracelet/meta`, which the agent fetches to read the real build: `CGO_ENABLED=0`, `ldflags: -s -w -X main.Version={{ .Version }} -X main.CommitSHA={{ .Commit }} -X main.CommitDate={{ .CommitDate }}`, and `before` hooks that generate bash, zsh and fish completions with `go run . completion <shell>` and a man page with `go run . man`, gzipped. `Taskfile.yaml` runs `golangci-lint run` and `go test ./...`, `.golangci.yml` is a v2 config, and the README already lists `nix-shell -p glow` as an install path, which means nixpkgs carries a package of its own but the repository has no `flake.nix`, `default.nix` or `shell.nix`.

It writes `flake.nix` with `nixpkgs` as its one input and a `packages.default` built by `buildGoModule`. The derivation sets `pname` to `glow`, takes `version` from the git revision the flake is built at with an `unstable` prefix when there is no tag, uses `src = ./.`, and passes the same `ldflags` goreleaser uses, with `main.Version` set to that version and `main.CommitSHA` to the flake's `rev` when it has one. `vendorHash` starts as `lib.fakeHash`; the agent runs the build once, reads the hash from the mismatch error and writes it in. `nativeBuildInputs` adds `installShellFiles`, and `postInstall` runs the built binary to generate the three completions and the man page into the output with `installShellCompletion` and `installManPage`, mirroring the goreleaser hooks so a `nix profile install` gets the same files a release tarball does. `doCheck` runs the package tests with CGO disabled as the release does.

A `devShells.default` holds `go`, `golangci-lint`, `go-task` and `gopls`, so `nix develop` gives a contributor the same tools the Taskfile expects without a system Go. Because the `go` directive is `1.26.7`, the agent checks that the Go in the pinned nixpkgs revision satisfies it before anything else; where the channel's Go is older it pins the flake input to a revision that is new enough and says so in a comment, since `buildGoModule` cannot download a toolchain the way `go` does. `.gitignore` gains `result`, and `flake.lock` is committed so every build uses the same nixpkgs revision until someone runs `nix flake update`.

It proves the flake in the sandbox: it installs Nix in single-user mode, runs `nix build` and `nix flake check`, runs the built binary with `--version` to show the injected version and commit, lists the completions and the man page under the result path, and runs `nix develop --command go test ./...` to show the dev shell works. The README's install section gains a `nix run github:<owner>/<repo>` line beside the existing `nix-shell -p glow` one, with a sentence on the difference: the flake builds the commit you point it at, nixpkgs ships the version it packaged. The goreleaser config, the Dockerfile and the workflows are untouched.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add a Nix flake to this Go CLI. Read go.mod, go.sum, main.go, the goreleaser config including any shared config it includes, the Taskfile and the README first, and list the ldflags, build env and generated files a release produces. Write flake.nix with a buildGoModule package that uses the same ldflags with the version and commit from the flake, a vendorHash you compute by building, completions and a man page installed from the built binary, tests enabled, and a dev shell with Go, golangci-lint, task and gopls. Check the pinned nixpkgs ships a Go that satisfies the go directive and pin to a newer revision with a comment if it does not. Install Nix in your sandbox, run nix build, nix flake check, the binary with --version and the tests in the dev shell, commit flake.lock, add result to .gitignore, document nix run in the README, and open a pull request with the output. Do not change the release config.",
  "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 adding `flake.nix` and `flake.lock`, a `result` entry in `.gitignore`, and a few lines in the README. The description lists the ldflags the derivation shares with goreleaser, the nixpkgs revision pinned and the Go version it provides, the `vendorHash` and how it was computed, and the files the output contains: the binary, three completions and the man page.

The run's record keeps the Nix install, the `nix build` with the hash mismatch that produced the `vendorHash`, `nix flake check`, the `--version` output showing the injected version and commit, and the test run inside `nix develop`, so a reviewer can follow each step without a Nix install of their own.

Before merging, a reviewer decides whether `flake.lock` should be updated on a schedule, confirms the version string format matches what the release binary prints, and checks whether the nixpkgs package of the same name should point at this flake or stay separate.

## Run it on every Go CLI without a flake

A maintainer with several CLIs hands this off from the terminal once per repository: one `POST /o/{org}/sessions` with this body and the repository in `resources`, and a `request_id` that is a UUID v5 of the repository name so a retried call returns the run it already started. The key's `webhook_url` reports each finished run with its pull request.

After the flake is merged, an automation in the Project with a `schedule` trigger set to a `cron` for one morning a month can run `nix flake update`, rebuild, run the tests and open a pull request only when the lock moved, which replaces the manual bump. An automation run has its own `max_runs_per_hour` cap.

## Why run it on Rush?

A flake for a Go CLI is short, and nearly every line is a fact about the repository: the module path, the ldflags, the files a release generates, the Go version the module demands. The agent reads those from `go.mod`, `main.go` and the real goreleaser config, including the one it includes from another repository, then installs Nix in its own sandbox and builds the flake until the hash, the version string and the installed files all check out, before the pull request exists.

The same body runs across every CLI a team ships, each pull request carrying its own hash, its own nixpkgs pin and its own build output, with the run's record showing the mismatch error that produced the hash. That is how a team adds reproducible builds to a dozen tools without one person learning each one's release quirks.

## Frequently asked questions

### Why does the flake need its own Go version check?

Because `go.mod` says `go 1.26.7`, and `buildGoModule` builds with the Go that nixpkgs provides rather than downloading a toolchain. If the pinned nixpkgs ships an older Go, the build fails before compiling. The agent checks this first and pins to a revision whose Go is new enough, with a comment saying which version it provides.

### What is vendorHash and will it change often?

It is the hash of the module dependencies Nix fetches for the build, so it changes whenever `go.mod` or `go.sum` changes. The pull request shows how it was computed, by building with `lib.fakeHash` and reading the expected hash from the error, so the next dependency bump is a two-minute follow-up.

### Does the binary from nix build report the same version as a release?

The same format. The derivation passes the same `-X main.Version` and `-X main.CommitSHA` flags goreleaser does, with the version taken from the flake's revision. A build from a tag prints that tag; a build from an untagged commit prints an `unstable` version with the short commit, which the pull request shows from the sandbox.

### Will this touch goreleaser or the release workflow?

No. The flake is an additional way to build and install the same code, and the goreleaser config, the Dockerfile and every workflow stay as they are. The README gains a `nix run` line next to the existing install paths.

### Does the dev shell replace the Taskfile?

No, it supplies the tools the Taskfile calls. `nix develop` puts `go`, `golangci-lint`, `task` and `gopls` on the path, and the same `task lint` and `task test` commands work inside it. The agent runs the tests in the shell in its sandbox to show that.

## More Go CLI jobs

- [Add a Progress Bar to a Go Command-Line Tool](https://getrush.ai/run/add-progress-bar/go-cli/)
- [Add a GitHub Release Workflow to a Go CLI](https://getrush.ai/run/add-release-workflow/go-cli/)
- [Add an SBOM to a Go CLI's GoReleaser Release](https://getrush.ai/run/add-sbom-to-release/go-cli/)

## The same job on other stacks

- [Add a Nix Flake to a Rust CLI](https://getrush.ai/run/add-nix-flake/rust-cli/)

## More jobs like this: Hand off a long task

- [Run Your Docker Images as a Non-Root User](https://getrush.ai/run/add-non-root-user/docker/)
- [Run Docker Compose Services as a Non-Root User](https://getrush.ai/run/add-non-root-user/docker-compose/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
