# Add a Config File to a Click CLI

Yes. An agent adds a TOML config file to a Click CLI through default_map, so saved defaults apply and flags still override them, and opens a pull request.

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

## What the agent does

The agent reads how the command declares its parameters, because Click's config mechanism is keyed on names the user never sees. In a tool like simonw/files-to-prompt, `files_to_prompt/cli.py` is one `@click.command()` whose options are declared with an explicit Python name ahead of the flags: `"extensions", "-e", "--extension"`, `"ignore_patterns", "--ignore"`, `"claude_xml", "-c", "--cxml"`, `"output_file", "-o", "--output"`. Two of them, `--extension` and `--ignore`, are `multiple=True`; the format switches and `--include-hidden`, `--ignore-files-only` and `--ignore-gitignore` are `is_flag=True` with no negative form. `pyproject.toml` depends on `click` alone and declares `requires-python = ">=3.8"`, and `.github/workflows/test.yml` runs `pytest` on Python 3.9 through 3.13. The people who would use a config file are the ones typing the same `--ignore` patterns and the same `-e` list on every call.

The mechanism is `default_map`. The agent adds an eager `--config` option with `expose_value=False` whose callback finds a file, parses it and assigns `ctx.default_map` before the other parameters are resolved. Click then treats each entry as that parameter's default, so anything given on the command line still wins, and a repeatable option accepts a list. Since `default_map` wants `ignore_patterns` and `claude_xml` while a person will write `ignore` and `cxml`, the loader carries an explicit table from the flag spellings in the README to the parameter names, and rejects any key outside it with a `click.UsageError` that names the key and the file. It also checks types, so `ignore = "*.lock"` as a bare string is refused with a message asking for a list.

Where the file lives and how it is parsed are both decided by what the repository supports. Lookup order is an explicit `--config PATH`, then `.files-to-prompt.toml` in the working directory, then `config.toml` under `click.get_app_dir("files-to-prompt")`, which follows `XDG_CONFIG_HOME` on Linux and the platform's convention elsewhere. Parsing uses `tomllib`, which exists from Python 3.11, so for the older versions the package still claims the agent adds `tomli; python_version < "3.11"` to the dependencies and imports whichever is present. Because none of the boolean flags can be switched back off from the command line, it adds `--no-config` to ignore every file for one call. `paths`, `--output` and `--null` are left out of the allowed keys: a saved output path would overwrite a file on every run.

Tests go into `tests/test_files_to_prompt.py` in the style already there, with `CliRunner` and `tmpdir.as_cwd()`: a project file sets `extension` and `ignore` and the output honours both; `-e` on the command line replaces the saved list; a saved `markdown = true` loses to `--cxml`, because `print_path` checks the XML switch first; `--no-config` restores the plain defaults; an unknown key and a wrong type each exit with a usage error. An autouse fixture points `XDG_CONFIG_HOME` at an empty temporary directory so a contributor's own config can never leak into the suite. The agent installs with `pip install -e '.[test]'`, runs `pytest`, and tries the feature by hand on the repository itself, writing a config file and running `files-to-prompt .` with and without overrides. A new README section documents the file, the lookup order and the allowed keys.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add config file support to this Click command-line tool. Read pyproject.toml, files_to_prompt/cli.py, tests/test_files_to_prompt.py, README.md and .github/workflows/test.yml first. Add an eager --config option (expose_value=False) whose callback loads a TOML file and sets ctx.default_map, so saved values act as defaults and command-line flags override them. Look for the file in this order: --config PATH, .files-to-prompt.toml in the working directory, then config.toml under click.get_app_dir(\"files-to-prompt\"). Keys in the file use the flag spellings from the README (extension, ignore, cxml, markdown, line-numbers, include-hidden, ignore-files-only, ignore-gitignore); map them to the Python parameter names explicitly, reject unknown keys and wrong types with a click.UsageError naming the key and file, and do not allow paths, output or null. Add --no-config to skip all files. Parse with tomllib, falling back to tomli on Python versions before 3.11, and add tomli as a conditional dependency. Add tests for: defaults applied, command-line override, cxml beating a saved markdown, --no-config, unknown key, wrong type; isolate the suite from a real user config with an autouse fixture. Run pytest, try it by hand on this repository, document it in the README and open a pull request.",
  "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

A pull request with the loader and the two new options in `files_to_prompt/cli.py`, the conditional `tomli` line in `pyproject.toml`, the new tests and fixture, and a "Configuration file" section in `README.md` with a sample file. Its description states the lookup order, the table from file keys to parameters, what happens when two sources disagree, and the `pytest` output. It also pastes a short terminal transcript from the sandbox: the same `files-to-prompt .` call with no file, with a project file, and with a flag overriding the file.

A reviewer checks the precedence rules against their own habits, in particular that a project-level file replaces the user-level one outright and is not merged with it, which the pull request says and which is the simpler rule to explain. They check the error text for a bad key, since that message is the whole user interface when a config is wrong. They confirm the `tomli` marker matches `requires-python`. And they decide whether discovering a file in the working directory is acceptable for a tool that is often run inside other people's repositories; the pull request notes that `--no-config` and the explicit flag exist for that case.

## Run it on every Linear issue labelled cli-config

For a team that maintains several Click tools, add an automation in the console on each tool's Project: a `linear` trigger on `linear.issue.labeled` with the label `cli-config`, and this prompt with the file name and key list adjusted to that tool. When a teammate labels an issue such as "let me save my ignore patterns", the run starts with the issue after the prompt as its context, works in that Project's repository and opens a pull request on a branch of its own. The label has to be applied by a person in your Rush org.

To start it from a script instead, for instance one that walks every CLI repository you own, send this body to `POST /o/{org}/sessions` once per repository with a `request_id` that is a UUID v5 of the repository's full name. A second pass of the script then returns the runs it already started instead of opening duplicate pull requests.

## Why run it on Rush?

A config loader is small, and the mistakes in it are all in the interactions: a saved default against an explicit flag, a list against a string, a file in the working directory against one in the home directory. The agent works in its own sandbox, where it can create each of those situations for real, with real files in real directories, and the run keeps the commands and what they printed. The transcript in the pull request is copied from that record.

The sandbox also starts empty, which matters for exactly this feature. There is no stray config in a home directory to make a test pass by accident, so a suite that is green there is green because of the fixture that isolates it. A reviewer who has their own `~/.config` full of files gets a result that does not depend on it.

## Frequently asked questions

### Do command-line flags still win over the file?

Yes. Values from the file are loaded into Click's `default_map`, which only supplies defaults. Anything passed on the command line replaces the saved value for that option, and a repeated option given on the command line replaces the saved list rather than adding to it.

### How do I turn off a boolean that the file turned on?

The tool's flags have no `--no-` forms, so the pull request adds `--no-config`, which skips every config file for that call. Adding paired negative flags is a larger interface change, and the description lists it as a possible follow-up.

### Why TOML and not YAML or JSON?

The standard library reads TOML from Python 3.11 on, so the newest interpreters need no new dependency and older ones need only the small `tomli` backport. YAML would add a parser dependency for every user, and JSON has no comments, which people want in a file of ignore patterns.

### Does it also read pyproject.toml?

Not in this request. A `[tool.files-to-prompt]` table is a natural next source for a tool run inside Python projects, and the loader's key table would apply to it unchanged. Say so in the prompt and the agent adds it to the lookup order and the tests.

## More Click jobs

- [Add a --dry-run Flag to a Click CLI](https://getrush.ai/run/add-dry-run-flag/click/)
- [Add Shell Completion to a Click CLI](https://getrush.ai/run/add-shell-completion/click/)
- [Fix "TypeError: CliRunner.__init__() got an unexpected keyword argument 'mix_stderr'" in Click 8.2](https://getrush.ai/run/fix-clirunner-mix-stderr-unexpected-keyword-argument/click/)

## The same job on other stacks

- [Add a Config File to a Go CLI](https://getrush.ai/run/add-config-file/go-cli/)
- [Add a Config File to a Rust CLI](https://getrush.ai/run/add-config-file/rust-cli/)
- [Add a Config File to a Textual App](https://getrush.ai/run/add-config-file/textual/)

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