All jobs

Add a --dry-run Flag to a Click CLI

Yes. An agent adds a --dry-run flag to your Click command that renders everything, writes nothing, lists what it would create, updates the CLI tests, and opens a PR.

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 what the command writes before it promises not to. In a tool laid out like cookiecutter/cookiecutter (2.7.1, click>=7.0,<9.0.0), cookiecutter/cli.py is one @click.command() with a template argument, an extra_context argument of nargs=-1, and sixteen options from --no-input and -o/--output-dir to --accept-hooks and --keep-project-on-failure, every one forwarded as a keyword to cookiecutter() in cookiecutter/main.py. That function resolves the template, builds the context, writes a replay file through dump(), and calls generate_files() in cookiecutter/generate.py, which is where the disk changes happen: render_and_create_dir makes the project directory, run_hook_from_repo_dir runs pre_gen_project and post_gen_project, os.walk over the template copies _copy_without_render directories with shutil.copytree, and generate_file renders each file with Jinja and writes it with open(outfile, 'w'), or copies a binary with shutil.copyfile, then shutil.copymode.

The flag has to render and not write, because the point of a dry run is to see the rendered names and catch a variable the context lacks without a directory to clean up. The agent threads dry_run: bool = False from main() through cookiecutter() to generate_files(). In the dry path, generate_files computes the rendered project directory name without creating it, skips both hooks and says so in its output, walks the template exactly as before so every filename and every file body still goes through Jinja and still raises UndefinedVariableInTemplate on a missing key, and prints one line per path it would create, relative to --output-dir, marking copy-only paths and binaries as copies. cookiecutter() also skips dump(), since a replay file on disk is a write too, and the --overwrite-if-exists and --skip-if-file-exists checks are reported rather than acted on: the output says which files exist already.

The tests are the part that shows the shape of the change. tests/test_cli.py runs the command through a CliRunner fixture and several tests, test_cli_output_dir among them, patch cookiecutter.cli.cookiecutter with mocker and assert_called_once_with listing every keyword argument, so each gains dry_run=False. New tests invoke --dry-run --no-input on tests/fake-repo-pre/, assert the listing names the rendered project directory and its files, and assert the directory does not exist afterwards; one more runs the same template with a variable the context lacks to show the dry run still fails with the context printed. The 22 tests in tests/test_generate_files.py keep passing because the default path is unchanged. docs/cli_options.rst documents the command through sphinx_click, so the new option appears in the reference with no edit.

The agent runs the suite the way the repository does: uv run --group test -- pytest, which pyproject.toml configures with -vvv --cov-report term-missing --cov=cookiecutter, and just lint-check for ruff, whose selected rules include flake8-bugbear and flake8-return and will flag a stray branch. It runs the real command once in its sandbox against tests/fake-repo-pre/ with and without the flag, lists the output directory after each, and quotes both in the pull request.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add a --dry-run flag to the Click command. Read cookiecutter/cli.py, cookiecutter/main.py, cookiecutter/generate.py, cookiecutter/hooks.py, cookiecutter/replay.py, tests/test_cli.py, tests/test_generate_files.py, pyproject.toml and justfile first, and list every place generate_files writes to disk or runs a hook. Thread dry_run from the CLI through cookiecutter() to generate_files(). In a dry run, render every directory name and file body as before so a variable the context lacks still fails, create nothing, run no hooks, write no replay file, and print one line per path that would be created relative to the output directory, marking copies and files that already exist. Update the CliRunner tests whose mocks assert every keyword, add tests that prove the listing and that nothing was written, run pytest and just lint-check, run the command with and without the flag against tests/fake-repo-pre and list the output directory after each, and open a pull request quoting the test summary and both listings.",
  "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 cookiecutter/cli.py, cookiecutter/main.py and cookiecutter/generate.py, updates the mock assertions in tests/test_cli.py, and adds the dry-run tests. Its description lists each write and hook call the agent found in generate_files, shows the listing a dry run prints for tests/fake-repo-pre/ beside the directory listing after a real run, and quotes the pytest summary with its coverage table and the ruff result.

The run's record keeps both command runs and the test output, so a reviewer can see the flag print the same paths the real run created and leave the output directory empty.

Before merging, a reviewer decides whether a dry run should also render the hooks' names in its listing or stay silent about them, and whether the listing should be machine-readable with a --dry-run that writes JSON when combined with a future flag, which the pull request names as a follow-up rather than adding.

Run it on every Linear issue labelled cli

An automation in the Project with a linear trigger runs this prompt when an issue gets the cli label, with the issue's text added after the prompt, so a ticket that asks for a dry run on one subcommand drives one run and one pull request. The automation runs as the member who last changed it, and its max_runs_per_hour caps a burst of labels.

A team that maintains several Click tools starts one run per repository from a script, POST /o/{org}/sessions with this input and the repository in resources, and a request_id that is a UUID v5 of the repository's full name so a retried call returns the run already started. Each run reads that tool's own command and write paths, so a tool with subcommands gets a group-level flag and a tool that only prints gets a pull request saying there is nothing to dry-run.

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

Why run it on Rush?

A dry-run flag is easy to add badly: skip the whole generate step and the flag never finds the missing variable it exists to find. Getting it right means reading the generator end to end and separating rendering from writing, then proving it by running the real command twice and comparing the directory. The agent does all of that in its own sandbox and keeps the listings.

The same change on many tools runs in parallel, one sandbox and one pull request each, and every pull request carries that tool's own listing and test summary rather than a copy of this one.

Frequently asked questions

Why does a dry run still render every template?

Because the errors people want to catch before generating, a variable the context lacks in a filename or a body, only appear during rendering. The dry path renders everything through the same Jinja environment and only replaces the write and the hook calls, so it fails where a real run would and prints the same paths.

Do the hooks run in a dry run?

No. pre_gen_project and post_gen_project are scripts the template author wrote and can do anything, so the dry run skips both and prints that it did. A template whose post hook moves files will therefore list the pre-hook layout, which the pull request says.

Why do the existing CLI tests change?

Several tests in tests/test_cli.py mock cookiecutter.cli.cookiecutter and assert the exact keyword arguments the command passes, so a new keyword fails them until dry_run=False is added to each assertion. That is the test suite doing its job, and the pull request shows the diff.

Does the replay file get written?

No. cookiecutter() calls dump() to save the context for --replay before generating, and a dry run skips it, because writing a file under the replay directory is the kind of side effect the flag promises not to have.

More Click jobs

The same job on other stacks

More jobs like this: Turn a Linear label into a PR

Keep reading