Auto‑Generate Shell Completion Scripts for Any CLI with YAML and clap‑rs

For command‑line tools that are more than trivial, providing auto‑completion is essential; otherwise developers struggle to discover sub‑commands and options. This guide shows a fast, language‑agnostic method: describe the CLI with a YAML schema and automatically generate completion scripts for various shells.

1. Importance of Command‑Line Hints

Complex CLIs like aliyun-cli expose many sub‑commands. Without completion, users must consult documentation or manually type --help. Adding descriptive hints makes selection of sub‑commands and parameters much easier.

2. Generating Hints

Many languages have argument parsers (Java: args4j, picocli; Node.js: commander.js; Python: argparse; Rust: clap‑rs). Among them, clap‑rs produces the most helpful completions, including descriptions, file and directory suggestions, and enum value hints, while remaining simple to use.

3. clap‑rs YAML Specification

clap‑rs defines a CLI via a YAML file that lists commands, sub‑commands, and arguments. Below is a demo YAML for an Alibaba Cloud tool:

name: aliyun2
version: "0.1.0"
about: "cli for Alibaba Cloud"
args:
  - version:
      short: v
      long: version
      takes_value: false
      about: Display version
subcommands:
  - oss:
      about: 对象存储
      subcommands:
        - cat:
            about: cat文本文件
            args:
              - file:
                  takes_value: true
                  required: true
                  about: 文件名称
        - ls:
            about: list文件
  - ecs:
      about: 云服务器
      subcommands:
        - SendFile:
            about: send file
        - AddTags:
            about: add tags

This defines two top‑level sub‑commands ( oss and ecs), each with their own nested commands and parameters.

4. Generating Completion Scripts

Using clap‑rs’s API, the YAML can be turned into shell‑specific completion scripts, as illustrated in the following screenshot:

The resulting completions include descriptive hints, making the CLI feel professional.

5. Writing YAML for Any Language

Regardless of whether the tool is written in Java, Python, Node.js, or Rust, developers first create a YAML spec, then use their preferred parser to implement the logic. To avoid manual errors, a JSON Schema is provided for validation.

6. The cli‑completion Tool

The Rust‑based cli-completion reads the YAML and emits completion scripts for bash, zsh, fish, and PowerShell. Example for zsh:

$ cli-completion --zsh commands/aliyun2.yaml > /usr/local/share/zsh/site-functions/_aliyun2
$ autoload -U compinit && compinit

And for Oh‑My‑Zsh:

$ mkdir ~/.oh-my-zsh/custom/plugins/aliyun2
$ cli-completion --zsh aliyun2.yaml > ~/.oh-my-zsh/custom/plugins/aliyun2/_aliyun2

After installation, any CLI can obtain completions automatically.

7. Deploying cli‑completion as FaaS

Because cli‑completion is written in Rust, it can be compiled to WebAssembly and deployed on Cloudflare Workers. A simple curl request sends a YAML file and receives the generated zsh script:

curl -H 'Content-Type: application/x-yaml' --data-binary "@cli.yaml" https://cli-completion.linux-china.workers.dev/completion/zsh

This serverless approach offers fast cold‑start times and low cost.

8. Summary

When building a CLI, first author a YAML description of commands and arguments, validate it with the provided JSON Schema, then generate shell completions with cli-completion. The process is language‑agnostic, improves developer experience, and can be automated via FaaS for on‑demand script generation.

Key CLI Parsers by Language

Java: Picocli, JCommander, JOpt, kotlinx-cli, JLine, args4j

Node.js: Commander.js, clap.js, minimist, yargs

Deno: yargs

Python: argparse, docopt, cli‑args, clap

Golang: argparse, flaggy

Rust: clap‑rs, pico‑args, paw

Ruby: cmdparse, commander, GLI

C++: gflags, cli, docopt.cpp