All jobs

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 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 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

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

The same job on other stacks

Keep reading