# Add a Config File to a Rust CLI

Yes. An agent adds a TOML config file to your Rust CLI, keeps each environment variable as an override, documents it in the help and man page, and opens a PR.

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

## What the agent does

The agent reads how settings reach the program today. In a Rust CLI like `ajeetdsouza/zoxide`, `src/config.rs` is six functions over environment variables: `data_dir` reads `_ZO_DATA_DIR` or falls back to `dirs::data_local_dir()/zoxide` and insists on an absolute path, `echo` and `resolve_symlinks` are true when `_ZO_ECHO` or `_ZO_RESOLVE_SYMLINKS` equal `1`, `exclude_dirs` splits `_ZO_EXCLUDE_DIRS` with `env::split_paths` into glob `Pattern`s and defaults to the escaped home directory, `fzf_opts` passes `_ZO_FZF_OPTS` through, and `maxage` parses `_ZO_MAXAGE` as a `u32` with a default of `10_000.0`. `src/db/mod.rs` calls `config::data_dir()` in `Database::open`, and the command structs in `src/cmd/` call the rest. `src/cmd/cmd.rs` has a `HelpTemplate` that prints an Environment variables section listing those six names, `README.md` documents them under Configuration, and `man/man1/zoxide.1` has the same list. `Cargo.toml` is at edition 2024 with `rust-version = "1.88.0"`, `clap` 4 with `derive`, `dirs` 6, `serde` with `derive`, and `build.rs` regenerates shell completions into `contrib/completions` from the clap definition.

The design keeps every existing variable working. The agent adds a `Config` struct in `src/config.rs` with `serde::Deserialize` and one optional field per setting, reads it once through a `std::sync::OnceLock` from `dirs::config_dir()/zoxide/config.toml`, or from the path in a new `_ZO_CONFIG_FILE` variable, and treats a missing file as empty. Each existing function then resolves in order: the environment variable, the file's field, the default. `exclude_dirs` takes a TOML array of strings rather than a path-separated list, `maxage` an integer, `echo` and `resolve_symlinks` booleans, and `data_dir` and `fzf_opts` strings, so a file value is validated with the same `Pattern::new`, `parse::<u32>` and `is_absolute` checks and an error names the file and the key. The `toml` crate is added with the smallest feature set that parses, which matters because `just lint` runs `cargo udeps` and `cargo msrv verify`, so the chosen version must build on 1.88.0 and every feature must be used.

Documentation changes in three places so they do not drift. The `HelpTemplate` in `src/cmd/cmd.rs` gains a Configuration file line under the environment variables, with the path and a note that variables win; `man/man1/zoxide.1` gets a FILES section and a line per key, written so `mandoc -man -Wall -Tlint` passes; and `README.md`'s Configuration section gets a `config.toml` example with every key and its default, formatted so `markdownlint` passes. `templates/` and `init.fish` are untouched, since the shell init scripts never read these settings directly.

Tests sit beside the code. Unit tests in `src/config.rs` use `tempfile` for a directory, write a `config.toml`, point `_ZO_CONFIG_FILE` at it and check the three-way precedence for each key, plus the error text for a relative `data_dir` and a bad glob. An integration test in `tests/` uses `assert_cmd` like `tests/completions.rs` does, runs `zoxide add` and `zoxide query` with a config file that sets `data_dir` to a temporary directory, and checks the database lands there. The agent runs what `justfile` runs: `cargo fmt --all --check`, `cargo clippy --all-features --all-targets -- -Dwarnings`, `cargo msrv verify`, `cargo udeps`, the `mandoc`, `markdownlint`, `shellcheck`, `shfmt` and `yamlfmt` lints, and `cargo nextest run --all-features --no-fail-fast --workspace`, inside the `nix-shell` the `justfile` names or with the tools installed directly.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "A Linear issue labelled agent says: \"Add a config file. Every _ZO_ setting should be settable in a TOML file in the user's config directory, with environment variables still taking precedence.\" Do the work in this repository. Read Cargo.toml, build.rs, src/main.rs, src/config.rs, src/cmd/cmd.rs, src/db/mod.rs, tests/completions.rs, justfile, .github/workflows/ci.yml, README.md and man/man1/zoxide.1 first. Add a serde Config struct read once from dirs::config_dir()/zoxide/config.toml or the path in _ZO_CONFIG_FILE, with a missing file treated as empty. Resolve each setting as environment variable, then file, then default, and validate file values with the same checks the variables get, naming the file and key in errors. Add the toml crate with minimal features that build on the pinned rust-version. Document the file in the help template, the man page and the README. Add unit tests for the precedence and the errors and an assert_cmd test that runs the binary with a config file. Run the full just lint and just test targets, and open a pull request that shows a complete example file.",
  "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 changes `Cargo.toml` and `Cargo.lock`, `src/config.rs`, the help template in `src/cmd/cmd.rs`, `man/man1/zoxide.1` and `README.md`, and adds an integration test under `tests/`. The description shows a full `config.toml` with every key and its default, states the precedence rule in one line, and quotes the clippy, msrv, udeps, mandoc, markdownlint and nextest summaries.

The transcript holds every lint from the `justfile`, the `cargo msrv verify` result that proves the new crate builds on 1.88.0, the `cargo udeps` run that proves nothing unused was added, and the nextest run with the new cases, so a reviewer sees the same checks CI will repeat rather than a claim that they pass. `GET /o/{org}/p/{project}/sessions/{id}/changes` returns the diff file by file.

Before merging, a reviewer checks that a file with an unknown key is rejected rather than ignored, that `_ZO_CONFIG_FILE` pointing at an unreadable path is an error while a missing default file is not, that the help text still fits the template's column layout, and that the man page passes `mandoc` with no warnings. A follow-up message to the same session adds a `zoxide config` subcommand that prints the resolved settings, and the sandbox still has the toolchain and the lint tools.

## Run it on every Linear issue labelled agent

In the Project that holds the CLI, add an automation with this prompt and a `linear` trigger on `linear.issue.labeled` filtered to the `agent` label. Each labelled CLI issue starts its own run in its own sandbox and ends in its own pull request; the issue text follows the prompt as data, and the trigger fills in no placeholder.

A handler on your own server does the same without the automation: it receives Linear's webhook, puts the issue text into `input`, and sends `POST /o/{org}/sessions` with the repository in `resources` and a `request_id` that is a UUID v5 of the issue id, so a redelivered webhook returns the run already started.

## Why run it on Rush?

The lint target here is nine tools under Nix, and a new dependency has to pass `cargo msrv verify` and `cargo udeps` as well as clippy with warnings denied. On a laptop that is an afternoon of tool installs before the first run. In a Rush sandbox the agent sets up that toolchain itself, runs the whole lint and test set as many times as the change needs, and keeps every run in the record.

A config file touches the help, the man page and the README at once, and the pull request has to show all three agree. The transcript holds the `mandoc` and `markdownlint` runs beside the tests, so a reviewer checks the documentation the same way as the code. Several CLIs can gain a config file at once, each in its own sandbox, each with its own pull request.

## Frequently asked questions

### Will my existing _ZO_ variables stop working?

No. Each setting resolves as the environment variable first, then the file, then the default, so a variable set today behaves exactly as before and the file only fills in what the environment leaves unset.

### Where does the file live?

At `dirs::config_dir()/zoxide/config.toml`, which is the platform's config directory, or wherever `_ZO_CONFIG_FILE` points. A missing default file is treated as empty; a `_ZO_CONFIG_FILE` that cannot be read is an error that names the path.

### How are bad values reported?

With the same checks the variables use: a relative `data_dir`, a glob that does not parse in `exclude_dirs` and a non-integer `maxage` each produce an error that names the file and the key. An unknown key is rejected so a typo does not silently do nothing.

### Does this change the shell init scripts or completions?

No. The `templates/` the init command renders and the completions `build.rs` generates do not read settings, and the prompt leaves them alone. `build.rs` regenerates `contrib/completions` only if the clap definition changes, which this does not.

### Why TOML?

It is the format Cargo already uses, the `toml` crate deserialises through the `serde` the project depends on, and the file is small enough that any format reads the same. Say YAML or JSON in the prompt if your users expect one of those.

## More Rust CLI jobs

- [Add Test Coverage Reporting to CI for a Rust CLI](https://getrush.ai/run/add-coverage-to-ci/rust-cli/)
- [Add Criterion Benchmarks to a Rust CLI](https://getrush.ai/run/add-criterion-benchmarks/rust-cli/)
- [Add Dependabot to a Rust CLI](https://getrush.ai/run/add-dependabot/rust-cli/)

## The same job on other stacks

- [Add a Config File to a Textual App](https://getrush.ai/run/add-config-file/textual/)
- [Add a Config File to a Tokio Server](https://getrush.ai/run/add-config-file/tokio/)
- [Add a Config File to a Click CLI](https://getrush.ai/run/add-config-file/click/)

## 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/)
