shellcomp

shellcomp is a deployment layer for shell completions in Rust CLI projects.

It does not generate completion scripts. It installs, wires, detects, and removes them in a way that is predictable, idempotent, and structured for callers.

What It Handles

• Default install paths for Bash, Zsh, and Fish
• write-if-changed completion file writes
• Managed ~/.bashrc fallback wiring when Bash has no system loader
• Managed ~/.zshrc wiring for fpath and compinit
• Native Fish completion directory installs
• Symmetric uninstall cleanup
• Structured reports that callers can render however they want

Supported Shells

• Bash
• Zsh
• Fish

Shell::Elvish, Shell::Powershell, and Shell::Other(_) are reserved for future expansion and currently return UnsupportedShell.

Add The Dependency

Until the crate is published, depend on a local checkout or a git revision:

[dependencies]
shellcomp = { path = "../shellcomp-rs" }

Once published, replace the path dependency with a version:

[dependencies]
shellcomp = "0.1.0"

Enable clap integration if you want the library to render completions from clap::CommandFactory directly:

[dependencies]
shellcomp = { version = "0.1.0", features = ["clap"] }
clap = { version = "4.6.0", features = ["derive"] }

Install A Prebuilt Completion Script

use shellcomp::{InstallRequest, Shell, install};

fn install_bash_completion(script: &[u8]) -> shellcomp::Result<()> {
    let report = install(InstallRequest {
        shell: Shell::Bash,
        program_name: "my-cli",
        script,
        path_override: None,
    })?;

    println!("{report:#?}");
    Ok(())
}

Integrate With clap

use clap::Parser;
use shellcomp::{InstallRequest, Shell, install, render_clap_completion};

#[derive(Parser)]
struct Cli {
    #[arg(long)]
    verbose: bool,
}

fn install_zsh_completion() -> Result<(), Box<dyn std::error::Error>> {
    let script = render_clap_completion::<Cli>(Shell::Zsh, "my-cli")?;
    let report = install(InstallRequest {
        shell: Shell::Zsh,
        program_name: "my-cli",
        script: &script,
        path_override: None,
    })?;

    println!("{report:#?}");
    Ok(())
}

The examples above install into managed shell locations. Use path_override during local testing if you do not want to touch your real shell profile yet.

Uninstall

use shellcomp::{Shell, UninstallRequest, uninstall};

fn remove_fish_completion() -> shellcomp::Result<()> {
    let report = uninstall(UninstallRequest {
        shell: Shell::Fish,
        program_name: "my-cli",
        path_override: None,
    })?;

    println!("{report:#?}");
    Ok(())
}

Custom Paths

When path_override is set, shellcomp writes only to the requested path and reports ActivationMode::Manual. This keeps the library from guessing additional shell wiring when the caller chose a custom location.

use std::path::PathBuf;

use shellcomp::{InstallRequest, Shell, install};

fn install_to_custom_path(script: &[u8]) -> shellcomp::Result<()> {
    let report = install(InstallRequest {
        shell: Shell::Bash,
        program_name: "my-cli",
        script,
        path_override: Some(PathBuf::from("/tmp/my-cli.bash")),
    })?;

    assert_eq!(report.activation.mode, shellcomp::ActivationMode::Manual);
    Ok(())
}