Shell Completions & Man Pages

Generate shell completions and man pages directly from your clap definitions so docs never drift.

Recipe

# Generate bash completions at build time
cargo add clap_complete --features generator

use clap::{CommandFactory, Parser};
use clap_complete::{generate, shells::Bash};
use std::io;
 
#[derive(Parser)]
#[command(name = "mytool")]
struct Cli {}
 
fn main() {
    let mut cmd = Cli::command();
    generate(Bash, &mut cmd, "mytool", &mut io::stdout());
}

When to reach for this: Any CLI your users install locally and expect to tab-complete like native system tools.

Working Example

// build.rs
use clap::CommandFactory;
use std::{env, fs, path::PathBuf};
 
fn main() {
    let out = PathBuf::from(env::var("OUT_DIR").unwrap());
    let mut cmd = mytool::Cli::command();
    for (shell, path) in [
        (clap_complete::Shell::Bash, out.join("mytool.bash")),
        (clap_complete::Shell::Zsh, out.join("_mytool")),
        (clap_complete::Shell::Fish, out.join("mytool.fish")),
    ] {
        let mut file = fs::File::create(&path).unwrap();
        clap_complete::generate(shell, &mut cmd, "mytool", &mut file);
    }
    println!("cargo:rerun-if-changed=src/lib.rs");
}

# Install bash completion (example)
sudo cp target/debug/build/mytool-*/out/mytool.bash \
  /etc/bash_completion.d/mytool

What this demonstrates:

• build.rs regenerates completions on every CLI change
• Supports bash, zsh, fish, powershell, and elvish
• Single source of truth: the Parser derive
• Pack completions in release archives

Deep Dive

Man Pages with clap_mangen

use clap_mangen::Man;
 
let man = Man::new(Cli::command());
man.render(&mut std::io::stdout())?;

Install to share/man/man1/mytool.1 in your packaging pipeline.

Distribution Checklist

Runtime vs Build-time Generation

• Build-time - Ship completions in release tarball (recommended)
• Runtime - mytool completions bash subcommand prints script for eval

Gotchas

• Stale completions after flag changes - Users tab-complete old flags. Fix: Regenerate in CI and bundle with releases.
• Binary rename - Completion script hardcodes the name. Fix: Pass the install name to generate().
• Subcommand aliases missing - Only defined subcommands complete. Fix: Add visible_alias in clap.
• Man page without section - Man expects section 1 for user commands. Fix: Use man 1 mytool in docs.
• Nushell / custom shells - Not all shells supported. Fix: Document manual install for unsupported shells.

Alternatives

FAQs

Related

• clap - source definitions
• Packaging & Distribution - ship with releases
• CLI Best Practices - discoverability
• CLI Basics - --help fundamentals

Stack versions: This page was written for Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, and Polars 0.46+.

cGJxcnRodnFyZi52YnxwdHZiMTI0fDIwMjYwNw==