# Migrate a Click CLI to Typer

Yes. An agent rewrites a Click command as a typed Typer app, keeps every flag and exit code, ports the tests to Typer's runner and opens a pull request.

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

## What the agent does

The agent reads the whole command surface first, because the migration is only correct if that surface comes out the other side unchanged. In a Click tool like simonw/files-to-prompt, `files_to_prompt/cli.py` holds one function decorated with `@click.command()`: a variadic `paths` argument typed `click.Path(exists=True)`, ten options including `-e/--extension` and `--ignore` with `multiple=True`, `-o/--output` typed `click.Path(writable=True)`, a `--null` flag whose short form is `-0`, and `@click.version_option()`. The docstring uses Click's `\b` marker to keep its example blocks from being rewrapped. Warnings go to stderr through `click.echo(click.style(..., fg="red"), err=True)` and a missing path raises `click.BadArgumentUsage`. `pyproject.toml` depends on `click` alone, declares `requires-python = ">=3.8"` and points the `files-to-prompt` script at `files_to_prompt.cli:cli`; `tests/test_files_to_prompt.py` drives all fourteen tests through `click.testing.CliRunner`.

Before writing code it checks what Typer needs, and that decides two things up front. The current Typer release on PyPI requires Python 3.10 or later, while this package claims 3.8 and its workflows test 3.9 through 3.13, so the agent raises `requires-python`, drops 3.9 from the matrix in `.github/workflows/test.yml` and `publish.yml`, and says so at the top of the pull request as the one breaking change. That release also no longer installs Click as a dependency; it carries its own copy internally. A leftover `raise click.BadArgumentUsage(...)` inside a Typer command is therefore not caught as a usage error and surfaces as an unhandled exception with exit code 1. Every `click.` reference has to go: `typer.echo`, `typer.style` and `typer.BadParameter` replace them, and `click` leaves `pyproject.toml`.

The rewrite itself is a translation into annotations. Each option becomes a parameter with `Annotated[..., typer.Option(...)]` carrying the same flag names and help text, the two `multiple=True` options become `list[str]`, and the path types become `pathlib.Path` or a `typer.Argument` with `exists=True`. One line breaks silently if translated word for word: `process_path` filters with `f.endswith(extensions)`, which works because Click hands a tuple, and Typer hands a list, which `str.endswith` rejects with a `TypeError`. The agent converts to a tuple at the boundary. Typer has no version decorator, so `--version` becomes an eager option whose callback prints `importlib.metadata.version("files-to-prompt")` and exits. The app is created with `add_completion=False`, since Typer otherwise adds `--install-completion` and `--show-completion` to a tool that never had them, and the entry point in `pyproject.toml` and `__main__.py` is repointed at it.

Tests are ported, not rewritten. The import becomes `typer.testing.CliRunner`, and the one test that constructs `CliRunner(mix_stderr=False)` loses that argument, which Typer's runner does not accept; its result already exposes `stderr` separately. The assertions stay as they are, including the stdin cases that pass `input=`. Before the change the agent saves `files-to-prompt --help` and the output of a few real invocations over the repository itself, in default, `--cxml` and `--markdown` form; afterwards it diffs them. The data output must be byte-identical. The help text will differ, since Typer draws it with Rich, and the pull request shows both versions side by side. It installs with `pip install -e '.[test]'` and runs `pytest` on each Python version the new floor allows that the sandbox can provide.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Migrate this command-line tool from Click to Typer without changing its behaviour. Read pyproject.toml, files_to_prompt/cli.py, files_to_prompt/__main__.py, tests/test_files_to_prompt.py, README.md and both workflows under .github/workflows first. Before editing, install the package, run pytest, and save the output of --help, --version and three real invocations (default, --cxml, --markdown) for comparison. Check the Python versions the current Typer release supports against requires-python and the CI matrix, and raise the floor if needed, stating it as a breaking change. Rewrite the command as a Typer app with Annotated parameters: same flag names and short forms (including -0 for --null and -e for --extension), same help strings, list[str] for the repeatable options, an eager --version callback using importlib.metadata, and add_completion=False. Remove every use of click, including click.echo, click.style and click.BadArgumentUsage, and remove click from the dependencies. Watch for code that relies on Click passing tuples, such as str.endswith. Port the tests to typer.testing.CliRunner with their assertions unchanged. Run pytest, then diff the saved outputs: data output must be identical, and the help text difference goes in the pull request. Update the README's development and options sections if anything in them changed, 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 that rewrites `files_to_prompt/cli.py`, repoints `__main__.py` and the console script, swaps `click` for `typer` in `pyproject.toml`, raises `requires-python`, trims the Python matrix in both workflows and changes the runner import and one constructor call in the tests. The description opens with the Python floor change, then gives a table of every flag before and after, the `pytest` output, the before and after `--help` text, and the result of the byte comparison on the three saved invocations. The repository's own `Test` workflow runs on the pull request across the remaining Python versions.

A reviewer checks the flag table against the README's options list, since that list is the tool's public contract. They run the new build against a script of their own that pipes paths in with `-0`, because stdin handling is where a runner-based test and a real shell differ most. They decide whether the new dependency weight is acceptable: Typer brings Rich and shellingham with it, where Click came alone. And they look at exit codes for bad input, which the pull request lists, because wrappers and CI scripts match on them.

## Run it on every terminal hand-off

A maintainer who wants typed parameters but not an afternoon of decorator translation sends this body from the terminal with the repository in `resources` and carries on with other work. A team with a shelf of small Click tools can send one request per repository; each run reads its own command and its own tests, so a tool with subcommand groups gets `add_typer` and a tool with a single command, like this one, does not. Runs beyond the API key's concurrency limit are accepted and wait as `queued` until a slot frees.

Give each start a `request_id`, a UUID, so a retry returns the run already started. When the turn ends, `GET /o/{org}/sessions/{id}` carries the pull request, and a follow-up message to the same session can ask for a short form on the version option, or for shell completion to be switched on now that Typer provides it, with the saved before-and-after outputs still on the parked sandbox's disk.

## Why run it on Rush?

The risk in a framework swap is the behaviour nobody wrote a test for: an exit code, a short flag, the exact bytes on stdout that another program parses. The agent has a sandbox where it can install the old version, capture real output, install the new one and diff, and the run keeps both captures and the diff. That is evidence a reviewer can check in a minute, and it is tedious enough that people skip it when doing the port by hand.

The dependency facts also need checking at the time of the change, not from memory. Which Python versions Typer supports and whether Click still comes with it have both changed across releases, and each decides part of this diff. The run resolves the packages fresh, records what it installed, and writes the pull request from that.

## Frequently asked questions

### Will my users have to change how they call the tool?

No flag is renamed or removed, and the request makes the data output byte-identical. Two things do change: `--help` is formatted by Rich, and the minimum Python version rises to what Typer supports. Both are stated at the top of the pull request.

### Why remove Click completely instead of mixing the two?

Recent Typer releases bundle their own copy of Click's internals and do not install the `click` package. An exception class imported from `click` is then a different class from the one Typer catches, so a usage error becomes a crash. Using Typer's own `echo`, `style` and exceptions keeps one framework in the process.

### Do the existing tests carry over?

Yes, with two mechanical edits. The runner import changes to `typer.testing.CliRunner`, and `mix_stderr=False` is removed because that runner separates stderr already. Every assertion is left as written, which is what makes the passing suite meaningful.

### What if I need to keep Python 3.9?

Say so in the prompt. The agent then looks for the newest Typer release whose metadata still allows 3.9, pins the dependency below the release that dropped it, and notes in the pull request what that pin costs. That is a decision for the maintainer, so the default request raises the floor and flags it.

## More Click jobs

- [Upgrade a Click CLI to Click 8.2 and Later](https://getrush.ai/run/upgrade-click/click/)
- [Add a Config File to a Click CLI](https://getrush.ai/run/add-config-file/click/)
- [Add a --dry-run Flag to a Click CLI](https://getrush.ai/run/add-dry-run-flag/click/)

## More jobs like this: Hand off a long task

- [Migrate a Node.js App from CommonJS to ESM](https://getrush.ai/run/migrate-commonjs-to-esm/nodejs/)
- [Migrate a Create React App Project to Vite](https://getrush.ai/run/migrate-create-react-app-to-vite/create-react-app/)
- [Replace dotenv With Node's --env-file Flag in an Express App](https://getrush.ai/run/migrate-dotenv-to-env-file/dotenv/)

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