# Add Shell Completion to a Textual App's CLI

Yes. An agent turns on Click completion for a Textual app's command, makes file arguments complete paths, adds a flag that prints the script, and opens a PR.

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

## What the agent does

The agent reads the command line before it touches it, because completion in Click depends on how each parameter is declared. In an app like Textualize/toolong, `pyproject.toml` is a Poetry project whose only script is `tl = "toolong.cli:run"`, with `click`, `textual` and `typing-extensions` as dependencies and `textual-dev` for development, and no tests directory. `src/toolong/cli.py` declares `run` as a single `@click.command()` with `@click.version_option`, an argument `files` with `metavar="FILE1 FILE2"` and `nargs=-1` and no type, a `-m/--merge` flag and a `-o/--output-merge` option whose metavar is `PATH`. When no files are given on a terminal it prints the help; when stdin is a pipe it copies the input to a temporary file and relaunches `sys.argv[0]` on that path with `TEXTUAL_ALLOW_SIGNALS=1`, which the agent notes because any new type on `files` must accept that path. `src/toolong/log_file.py` opens each path with `open(self.path, "rb", buffering=0)` and picks gzip or bz2 by extension, so a directory was never a valid argument. The README says to install with `pipx install toolong` or `pip install toolong`, which matters: Click's completion only works for a program installed as an entry point.

Click's documentation says completion covers command names, option names after a dash, `Choice` values and `File` and `Path` parameters, and that an untyped argument completes nothing. So the agent gives `files` the type `click.Path(exists=True, dir_okay=False)`, which the temporary-file relaunch satisfies and which also turns a mistyped filename into a Click usage error instead of a traceback from `open`, and gives `--output-merge` the type `click.Path(dir_okay=False, writable=True)` so a path completes there too. Then it adds a `--completion` option taking `bash`, `zsh`, `fish` or `powershell` through `click.Choice`, whose callback builds the script with `click.shell_completion.get_completion_class(shell)(run, {}, "tl", "_TL_COMPLETE").source()`, prints it and exits, the same text the `_TL_COMPLETE=bash_source tl` form produces, so a reader never has to remember the variable. The README gains a section with the one-line setup per shell from Click's documentation, in the saved-script form that avoids running `tl` on every shell start, and the Fish form that writes to `~/.config/fish/completions/tl.fish`.

Tests come with it, since the repository has none and the behaviour is easy to pin. The agent adds `pytest` to the dev group with `poetry add --group dev pytest` and writes `tests/test_cli.py`: `CliRunner().invoke(run, ["--completion", "bash"])` exits 0 and the output contains `_TL_COMPLETE`; `click.shell_completion.BashComplete(run, {}, "tl", "_TL_COMPLETE").get_completions([], "")` returns one item whose `type` is `file`, which is how Click hands path matching to the shell for the `files` argument; the same call with `["--output-merge"]` returns a `file` item; and `get_completions([], "-")` lists `--merge`, `--output-merge`, `--completion`, `--version` and `--help`. A last test passes a path that does not exist and checks the usage error names `FILE1 FILE2`.

Then it proves it in a shell. The agent installs the package into a virtual environment with `pip install -e .`, so `tl` exists on the path, runs `tl --completion bash` into a file, sources it in a fresh `bash` with a scratch directory of `.log` and `.log.gz` files, and drives completion through `compgen`-style invocations of the generated function to show the filenames come back, then repeats the check in `zsh` with the zsh script. It runs `tl --version` and `tl` with no arguments to confirm the help still prints, and `printf 'a\nb\n' | tl` to confirm the piped path still relaunches with the temporary file under the new type.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add shell completion to this Textual app's command line. Read pyproject.toml, the cli module, the module that opens log files, the README's install section and any existing tests first. Give the file argument and the output path option Click Path types so they complete filenames, keeping the piped-stdin path that relaunches the command on a temporary file working. Add a --completion option with a Choice of bash, zsh, fish and powershell that prints Click's completion script for the installed command name, and document the per-shell setup in the README in the saved-script form. Add pytest to the dev dependencies and write tests for the script output, the completion items of the file argument and option, and the option names. Install the package into a virtual environment, generate the bash and zsh scripts, source each in a fresh shell over a directory of sample log files and show the completions, and open a pull request linked to the issue with the commands and their output.",
  "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

The pull request changes `src/toolong/cli.py`, `pyproject.toml` and `poetry.lock`, and adds `tests/test_cli.py` and a README section. Its description quotes the pytest run, the bash and zsh completion output over the sample directory, the unchanged help text, and the piped-stdin check.

A reviewer checks whether `exists=True` is too strict for a workflow that opens a log before it is written, which the pull request raises as a question with `exists=False` as the one-word alternative, and whether the README should also show the PowerShell form. After merging, a user who installed with pipx runs one command per shell and gets filenames after `tl`.

## Run it on every Linear issue labelled cli

An automation in the Project that holds the app takes a `linear` trigger on `linear.issue.labeled` with the label `cli`. Its runs are read-only, so the saved prompt asks for a plan: the run reads the command, lists the parameters that would gain types and the shells it would document, and posts that as a comment on the issue, where a maintainer can say whether the file argument may name a file that does not exist yet. A handler on the team's own server then starts the run that writes the pull request, sending this body with the issue's URL added to `resources` and a `request_id` that is a UUID v5 of the issue id, so a retried start returns the run already started.

A team that ships several terminal apps sends one request per repository, each with its own `resources` entry; an app whose entry point is a `click.Group` gets a `completion` subcommand instead of an option, because that is where its users look.

## Why run it on Rush?

Completion is cheap to add and easy to get subtly wrong: an argument without a type completes nothing, a type that is too strict breaks the piped-stdin path the app relies on, and a script generated under the wrong program name never loads. The agent reads the entry point and the relaunch code, installs the package the way users do, and exercises the generated scripts in real shells in its own sandbox, keeping every command and its output in the run's record.

It also leaves tests behind in a repository that had none, so the next change to the command line keeps the completion honest. Several terminal apps get the same treatment at once, each with the setup lines for its own command name.

## Frequently asked questions

### Why add a --completion flag when Click already has the environment variable?

Both produce the same script; the flag is discoverable in `--help` and spares users the `_TL_COMPLETE=bash_source tl` spelling. The agent builds it with Click's own `get_completion_class`, so there is no second implementation to keep in step.

### Does completion work when the app is run with python -m?

No. Click's documentation says completion needs the program installed as an entry point and invoked by its name, which is how `pipx install toolong` sets it up. The README section says so, and the tests exercise the script through `CliRunner` rather than the shell for that reason.

### Will the Path type break reading from a pipe?

No. The piped path writes stdin to a temporary file and relaunches the command on that file's name, which exists, so `click.Path(exists=True)` accepts it; the agent runs that case and quotes it. A directory was never a valid argument because the file opener reads bytes from the path.

### What about Windows users?

Click generates a PowerShell script too, and the `--completion` choice includes it, but the agent tests bash and zsh in the sandbox and says so; the README shows the PowerShell profile line from Click's documentation without claiming it was run.

## More Textual jobs

- [Add Snapshot Tests to a Textual App](https://getrush.ai/run/add-snapshot-tests/textual/)
- [Add mypy Type Checking to a Textual App](https://getrush.ai/run/add-type-checking/textual/)
- [Migrate a Textual App From Poetry to uv](https://getrush.ai/run/migrate-to-uv/textual/)

## The same job on other stacks

- [Add Shell Completion to a Click CLI](https://getrush.ai/run/add-shell-completion/click/)
- [Add Shell Completion to a Go CLI from a Linear Issue](https://getrush.ai/run/add-shell-completion/go-cli/)
- [Add Shell Completions to a Rust CLI](https://getrush.ai/run/add-shell-completion/rust-cli/)

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