All jobs

Add Shell Completions to a Rust CLI

Yes. An agent reads your clap command definition, adds a --completions flag through clap_complete for five shells, attaches the scripts to releases 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 the command before generating anything from it. In a CLI like XAMPPRocky/tokei the whole interface is built in src/cli.rs with clap 4's builder: Cli::from_args constructs clap::Command::new("tokei") with nineteen arguments and calls .get_matches() on it in the same expression. Some arguments carry a fixed value list through value_parser([...]), such as --sort and --rsort over files, lines, blanks, code and comments, --streaming over simple and json, and --num-format over commas, dots, plain and underscores; --output instead parses through Format::from_str, whose accepted names depend on the cbor, yaml and json cargo features, so a completion script cannot know them from the builder alone; --types takes comma-separated language names; and the positional input takes paths. Cargo.toml puts clap behind the cli feature with the cargo, string and wrap_help features on, and nothing named clap_complete appears anywhere. The README's installation section lists a dozen package managers, from cargo install through Homebrew, winget and scoop, and several of those packagers want completion files to install.

The change is small and shaped by how the command is built. The agent splits the builder out into a Cli::command() function that returns the clap::Command, so the same definition can be matched once and generated from once, and adds clap_complete 4 as a dependency behind the same cli feature. A --completions <SHELL> flag with value_parser!(Shell) joins the other arguments, and from_args checks it first: when it is set, the code builds the command again, calls clap_complete::generate(shell, &mut cmd, "tokei", &mut io::stdout()) and exits, before any counting happens. Clap lists the five shells in the flag's help, and tokei --completions bash prints a script that completes every long and short option, --completions fish prints one complete line per option with the fixed value lists attached, and --completions zsh emits the same lists as candidates, so --sort offers its five column names in all three shells. For --output, whose values come from a parser function, the agent adds the names from Format::all_feature_names as possible values so they complete too, with the existing error for a format compiled out left in place.

Shipping the scripts is the part package maintainers ask for. The agent adds a completions/ step to the release workflow in .github/workflows/mean_bean_deploy.yml, which today uploads one binary per target through ci/build.bash: after the Linux build it runs the freshly built binary once per shell and attaches tokei.bash, _tokei, tokei.fish, _tokei.ps1 and tokei.elv to the same release, so Homebrew, Debian and Arch packagers can fetch them from the release rather than build the tool to produce them. The README's installation section gets a short paragraph showing tokei --completions zsh > ~/.zfunc/_tokei and the fish equivalent, since a user who installed with cargo install has no packager to do it for them.

To check it, the agent builds with cargo build, runs each of the five generators and reads the output for the flags it knows the command has, then sources the bash script in a bash subshell and the zsh script in zsh with compinit and presses tab after tokei --so and tokei --sort to see the option and then its five values offered, recording the terminal output. It runs cargo test, which drives the accuracy tests over the tests/data language samples, to show the counting code is untouched, and cargo build --all-features as ci/test.bash does, since the new flag must compile with every format feature on.

Start it with one API call

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

{
  "agent": "claude",
  "input": "Add shell completions to this Rust CLI. Read Cargo.toml for the clap version and features and the module that builds the clap command, and note which arguments have fixed value lists and which parse through a function. If the command is built and matched in one expression, split the builder into a function so it can be built twice. Add clap_complete at the matching major version behind the same feature as clap, add a --completions flag that takes a shell name, and print the generated script for that shell to stdout and exit before any other work. Give possible values to any argument whose accepted names come from a parser function so they complete too. Add a release workflow step that generates the five scripts from the built binary and attaches them to the release, and a README paragraph showing how a user installs one by hand. Build, generate each script and check it names the command's options, source the bash and zsh scripts and record a tab completion of an option and of a value, run the test suite and the all-features build, and open a pull request 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 Cargo.toml, Cargo.lock, the CLI module, the release workflow and the README. Its description shows the new flag in --help with its five possible values, the first lines of the generated bash script, the fish line for --sort with its five candidates, the recorded tab completions from bash and zsh, and the cargo test and all-features build output.

A reviewer checks that the builder split changed no argument, which the unchanged --help output shows, and that the release step attaches the scripts under names their packagers expect. After merging, the next tagged release carries the five files, and a user on any shell gets the command's options and the fixed value lists with one line in their shell profile.

Run it on every Rust CLI in the terminal

A developer who has just typed the tool's flags from memory sends this body from their own machine with the repository in resources and reads the pull request from the console when the webhook on their API key reports the run. A team with several Rust CLIs sends one request per repository, each with a request_id that is a UUID v5 of the repository's full name, so a script run twice returns the runs already started rather than a second set of pull requests.

Each run reads its own command definition: a CLI built with clap's derive macros gets the flag on its Parser struct and CommandFactory::command() instead of a builder split, and one that already generates scripts in build.rs gets only the release step and the README paragraph.

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

Why run it on Rush?

The generator is one function call, and the work around it is reading the command: which values are fixed and which come from a parser, where the builder and the matcher are fused, which cargo feature the CLI lives behind, where releases are assembled. The agent reads all of that, builds the tool in its own sandbox, generates each script and presses tab in real shells, with every command and its output kept in the run's record, so the pull request shows a completion happening rather than a script that should work.

It also fits the project's own release path rather than a generic one: the scripts come from the binary the release workflow already builds, they land on the release the packagers already read, and the README tells the cargo install user what to do. Several CLIs with several argument styles get several pull requests, each generating from its own definition.

Frequently asked questions

Will the completions know my option's values?

For any argument with a fixed value list in the command definition, yes, in bash, zsh and fish alike. An argument whose values come from a parser function gets no candidates unless they are declared, so the agent adds the known names as possible values where the code makes them knowable, and says in the pull request where it could not.

Why a flag rather than a build-time script?

A flag on the binary means the script always matches the installed version and a packager can generate it without a Rust toolchain, which is what Homebrew and Debian packaging does. The release step attaches the five scripts for those who want files, so both routes are covered.

Does it change how the command parses?

No. Splitting the builder into a function changes nothing about the arguments, and the --help output before and after is identical apart from the new flag, which the pull request shows. The test suite runs to confirm the tool's behaviour is untouched.

What about dynamic completion of file paths or language names?

Paths complete through each shell's default file completion. Values that only the running tool knows, such as a language list, would need clap_complete's dynamic completion, which is still marked unstable, so the agent keeps to the static scripts and names that option in the pull request.

More Rust CLI jobs

The same job on other stacks

Keep reading