# 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 Rush](https://cloud.getrush.ai/run/add-dry-run-flag/click/). Opens 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`

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

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

- [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/)
- [Migrate a Click CLI to Typer](https://getrush.ai/run/migrate-click-to-typer/click/)

## The same job on other stacks

- [Add a --dry-run Flag to a Cobra CLI](https://getrush.ai/run/add-dry-run-flag/cobra/)

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

- [Add a Durable Object to a Cloudflare Worker](https://getrush.ai/run/add-durable-objects/cloudflare-workers/)
- [Enable DynamoDB Point-in-Time Recovery in an AWS CDK Stack from a Linear Issue](https://getrush.ai/run/add-dynamodb-point-in-time-recovery/aws-cdk/)

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