Shell Completions
Relevant source files
The following files were used as context for generating this wiki page:
The Shell Completions module in Numan provides a mechanism to generate native completion scripts for various command-line shells. This feature enhances user experience by providing tab-completion for Numan's subcommands and arguments, directly derived from the application's CLI definition.
The system supports major shells including Bash, Fish, Zsh, PowerShell, and Nushell. It utilizes the clap_complete and clap_complete_nushell ecosystems to ensure that the generated completions stay in sync with the current version of the CLI. Unlike package-specific completion payloads which are currently install-only, Numan's own completions are fully integrated and available via the completions subcommand.
Sources: src/cmd/completions.rs:1-25, README.md:126-135, AGENTS.md:55-56
Architecture and Logic
The completion system is built as a subcommand within the Numan CLI. It leverages the Cli struct (derived via clap) to generate the command hierarchy and then applies shell-specific logic to format the output.
Generation Process
The generation flow starts when a user executes numan completions <shell>. The application captures the requested shell type and passes it to a generation function that utilizes buffer-based script creation.
The diagram shows the flow from user input to the final script output on stdout and instructions on stderr.
Sources: src/cmd/completions.rs:27-33, src/cmd/completions.rs:72-88
Key Components
| Component | Description | Source |
|---|---|---|
CompletionShell | Enum defining supported shells: Bash, Fish, Zsh, PowerShell, Nushell. | src/cmd/completions.rs:17-25 |
generate_script | Core logic that maps the shell enum to the appropriate generator. | src/cmd/completions.rs:72-88 |
install_hint | Provides shell-specific installation instructions to the user. | src/cmd/completions.rs:41-67 |
make_powershell_profile_safe | Post-processor for PowerShell scripts to ensure $PROFILE compatibility. | src/cmd/completions.rs:95-127 |
Shell-Specific Implementations
Nushell Integration
For Nushell, the system generates an extern command module. Numan provides specific aliases (supporting both nushell and nu) and suggests a vendor-autoload path for installation. This allows the completions to be automatically loaded upon shell startup if placed in the correct data directory.
Sources: src/cmd/completions.rs:24-25, tests/completions_test.rs:41-55, CHANGELOG.md:103-104
PowerShell Compatibility
Native clap_complete output for PowerShell includes using namespace directives. These directives must appear at the top of a script, which prevents users from simply appending the completion output to an existing $PROFILE. Numan performs a rewrite of the generated script to use fully-qualified names (e.g., [System.Management.Automation.Language.StringConstantExpressionAst]), making the script "profile-safe."
This sequence illustrates the specific post-processing required for PowerShell to prevent ParserErrors in user profiles.
Sources: src/cmd/completions.rs:95-127, CHANGELOG.md:121-123
Installation and Deployment
Numan follows a convention of printing the script to stdout and instructions to stderr. This allows users to redirect the output to a file without including the human-readable instructions in the completion script itself.
Installation Commands by Shell
| Shell | Recommended Installation Method |
|---|---|
| Bash | Redirect to ~/.local/share/bash-completion/completions/numan |
| Zsh | Redirect to ~/.zfunc/_numan |
| Fish | Redirect to ~/.config/fish/completions/numan.fish |
| PowerShell | Append to $PROFILE using Add-Content |
| Nushell | Save to ($nu.data-dir)/vendor/autoload/numan-completions.nu |
Sources: src/cmd/completions.rs:41-67, README.md:141-160
Testing and Verification
The completion system is verified through integration tests that check for the presence of core Numan commands (e.g., init, install, activate, nupm) in the generated output across all supported shells.
#[test]
fn bash_completions_include_core_commands() {
let script = generate_script(CompletionShell::Bash).expect("generate bash");
for needle in [
"numan",
"init",
"install",
"activate",
"try",
"completions",
"nupm",
] {
assert!(
script.contains(needle),
"bash completion script missing '{needle}'"
);
}
}
Sources: tests/completions_test.rs:5-20, tests/completions_test.rs:58-71
Conclusion
The Shell Completion system in Numan provides a robust, multi-shell solution for CLI discoverability. By combining automated generation with custom post-processing for PowerShell and specific autoloading strategies for Nushell, it ensures that users can interact with the package manager efficiently across all supported operating systems.