# Add a Nix Flake to a Rust CLI

Yes. An agent turns a Rust CLI's shell.nix into a flake with a locked dev shell and a buildable package, keeps nix-shell working, checks it with Nix and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-nix-flake/rust-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 repository into its own cloud sandbox and reads how Nix is used today. In a CLI like ajeetdsouza/zoxide, `shell.nix` imports nixpkgs with `builtins.fetchTarball` at a fixed commit and layers `oxalica/rust-overlay` from a second pinned tarball, then builds a `mkShell` with the stable Rust toolchain, a nightly `rustfmt`, a `cargo-udeps` wrapper that points at the nightly compiler, `cargo-msrv`, `cargo-nextest`, `just`, `mandoc`, `nixfmt`, `shellcheck`, `shfmt`, `yamlfmt`, `markdownlint-cli`, Python's `black`, `mypy` and `pylint`, and ten shells from `bash` and `dash` to `nushell`, `xonsh` and `powershell`, because `tests/completions.rs` and part of `src/shell.rs` run the generated completions under each one behind the `nix-dev` Cargo feature. It sets `CARGO_TARGET_DIR` to `target_nix`. The `.envrc` says `use nix`, every entry in the `justfile` wraps its command in `nix-shell --cores 0 --pure --run`, and `.github/workflows/ci.yml` installs Nix with `cachix/install-nix-action`, points `nix_path` at the `nixos-unstable` channel, which the pinned tarballs ignore, and runs `just lint test`. The agent also reads `Cargo.toml`, edition 2024 with `rust-version` 1.88.0, `Cargo.lock`, `build.rs`, which generates completions at build time, and the `man/man1` and `contrib/completions` directories the Debian metadata installs.

It writes `flake.nix` with two inputs, `nixpkgs` and `rust-overlay`, and a `flake.lock` that pins them to the same two commits the tarball URLs named, so the first `nix develop` produces the environment the team already has rather than a newer one. `devShells.default` carries the `mkShell` over tool for tool, including the `cargo-udeps` wrapper and the `CARGO_TARGET_DIR` setting, with the toolchain still coming from the overlay so the nightly `rustfmt` keeps working. `packages.default` is new: a `rustPlatform.buildRustPackage` that reads the version from `Cargo.toml`, uses `cargoLock.lockFile = ./Cargo.lock`, and in `postInstall` copies `man/man1/*.1` into `share/man/man1` and the Bash, Fish and Zsh completions from `contrib/completions` into their standard directories, the same files the `[package.metadata.deb]` block ships, so `nix run` and `nix profile install` give a complete install. `checks.default` runs the test suite through the package build.

Then it keeps the old entry points working. `shell.nix` becomes a short shim that loads the flake through `flake-compat`, so `nix-shell` and the `justfile` commands behave as before, and `.envrc` changes from `use nix` to `use flake`. In `ci.yml` the `nix_path` line is dropped, since the lockfile now owns the pin, and `cachix-action` stays as it is because the flake's outputs push to the same cache. The agent adds `flake.nix` to the `nixfmt` lines in the `justfile` so `just lint` formats and checks it with the other Nix files, and lists `flake.lock` in the pull request as a file to update with `nix flake update` on a schedule, since the two tarball commits had no such mechanism.

To check it, the agent installs Nix in the sandbox with the single-user installer and `experimental-features = nix-command flakes`, runs `nix flake show` and `nix flake metadata` to confirm the inputs resolve to the pinned revisions, `nix develop --command cargo nextest run --all-features --workspace` to run the suite including the `nix-dev` shell tests inside the new dev shell, and `nix build` to produce the package and verify that `result/bin/zoxide --version`, the man pages and the completions are all present. Downloading ten shells and two Rust toolchains takes a while and is the honest cost of proving the shell is complete, and each command and its output stays in the run's record.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add a Nix flake to this Rust CLI. Read shell.nix, .envrc, the justfile, every GitHub Actions workflow, Cargo.toml, Cargo.lock, build.rs and any man page or completion directories first. Write flake.nix with nixpkgs and any overlay the shell already uses as inputs, pinned in flake.lock to the same revisions the current shell.nix fetches. Carry the dev shell over tool for tool, including environment variables, as devShells.default. Add packages.default with rustPlatform.buildRustPackage using the committed Cargo.lock, installing the man pages and shell completions the repository ships, and a check that runs the tests. Replace shell.nix with a flake-compat shim so nix-shell keeps working, switch .envrc to use flake, remove any channel pin the CI workflow no longer needs, and add the new Nix files to any formatting or lint command that covers Nix files. Install Nix in your sandbox, run nix flake show, nix flake metadata, the test suite inside nix develop, and nix build, and confirm the built binary, man pages and completions exist. Open a pull request with those outputs and a note on how to update flake.lock.",
  "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 that adds `flake.nix` and `flake.lock`, rewrites `shell.nix` as a few-line `flake-compat` shim, changes one word in `.envrc`, removes the `nix_path` line from the CI workflow and extends two `justfile` lines. No Rust source changes. The description explains each output in the flake, which revision each input is locked to and that they match the old tarball URLs, and what `postInstall` places where.

The run's record holds the Nix install, `nix flake metadata` showing the locked inputs, the full `cargo nextest` run inside `nix develop` with the shell-backed completion tests included, and the `nix build` with a listing of `result/bin`, `result/share/man/man1` and the completion directories, so a reviewer can see the package is complete without building it themselves.

Before merging, a reviewer decides whether to keep the `flake-compat` shim or delete `shell.nix` once everyone has moved to `nix develop`, whether the Cachix push should include the new package output, and how often `nix flake update` should run, which is a one-line schedule in a workflow or an automation.

## Run it on every Rust repository with a shell.nix and no flake

In the console, an automation in the Project that has the repository, with a `schedule` trigger set to `cron` for one early morning a week, starts a run with this prompt. The prompt asks the run to finish at once if `flake.nix` already exists, and otherwise to do the migration, so each repository is converted once and later fires cost one file check. After the migration a second automation with the same trigger can run `nix flake update`, build the package and open a pull request when the lock moved, which replaces the manual bump of a tarball commit.

From your own server, send this body as `POST /o/{org}/sessions` with each repository in `resources`, with a `request_id` that is a UUID v5 of the repository name so a retried call returns the run it already started. Set a `webhook_url` on the key to receive `run.completed` with `data.session_url` when each pull request is open.

## Why run it on Rush?

The hard part of a flake is not writing it, it is proving that `nix develop` gives the same tools the old shell did and that `nix build` produces a complete package, and that proof means downloading two toolchains and a shelf of shells into a clean store. The agent's sandbox is exactly that clean machine: it installs Nix, resolves the lock, runs the whole test suite inside the new shell and builds the package, and every command and its output is in the run's record beside the pull request, so a reviewer reads a listing instead of repeating a long build.

The same request runs across every Rust CLI an organisation maintains, each in its own sandbox with its own `shell.nix` and its own pinned revisions, which is how a team moves all of them to flakes with locked inputs in one review cycle rather than one evening per repository.

## Frequently asked questions

### Will nix-shell and direnv still work after the change?

Yes. `shell.nix` becomes a `flake-compat` shim that loads the flake's dev shell, so `nix-shell` and the `justfile` commands that call it behave as before, and `.envrc` moves to `use flake`, which direnv supports with the nix-direnv extension most Nix users already have.

### Why pin flake.lock to the old revisions instead of the newest nixpkgs?

So the first `nix develop` reproduces the environment the team is on today and the pull request changes the mechanism, not the tool versions. Updating is then a separate `nix flake update` with its own diff, and the pull request says how to schedule it.

### Does the package output replace the crates.io or Debian release?

No. It adds a third install path for Nix users, `nix run` or `nix profile install` from the repository, and installs the same man pages and completions the Debian package metadata lists. The release workflows are untouched.

### What about the tests that need ten shells installed?

They stay behind the `nix-dev` Cargo feature and run inside `nix develop`, where the dev shell provides every shell the old `shell.nix` listed. The agent runs them in the sandbox, so the pull request shows the completion tests passing under the new shell.

### Will the Cachix cache still be used in CI?

Yes. `cachix-action` watches the Nix store regardless of whether a flake or a `shell.nix` filled it. The only CI change is dropping the `nix_path` channel pin, which the lockfile makes redundant.

## More Rust CLI jobs

- [Add Shell Completions to a Rust CLI](https://getrush.ai/run/add-shell-completion/rust-cli/)
- [Add Snapshot Tests for the Shell Scripts a Rust CLI Generates](https://getrush.ai/run/add-snapshot-tests/rust-cli/)
- [Fix a Failing CI Run for a Rust CLI](https://getrush.ai/run/fix-failing-ci/rust-cli/)

## The same job on other stacks

- [Add a Nix Flake to a Go CLI](https://getrush.ai/run/add-nix-flake/go-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/)
