All jobs

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

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

The use case this job follows, with its automation and trigger: Hand off a long task.

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

More jobs like this: Hand off a long task

Keep reading