# Shell completion support

- **Pattern:** `ab-000661` (`cli-quality.config-distribution.shell-completions`)
- **Severity:** info
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-000661
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-000661)

## Why it matters

Shell completions turn `mytool dep<TAB>` into `mytool deploy` and `mytool deploy --en<TAB>` into `mytool deploy --environment`. Power users depend on them; new users discover commands through them. A CLI with twelve subcommands and no completion support forces users to consult `--help` for every invocation. Completion scripts are cheap to generate (one line in cobra, one crate in clap, built into oclif) and disproportionately improve daily use.

## Severity rationale

Info because completions are a usability enhancement, not a correctness or availability concern.

## Remediation

Add a `completions` subcommand that emits bash/zsh/fish scripts to stdout, and document the install one-liner in README. For cobra in `cmd/completion.go`:

```go
var completionCmd = &cobra.Command{
    Use: "completion [bash|zsh|fish]",
    RunE: func(cmd *cobra.Command, args []string) error {
        return rootCmd.GenBashCompletion(os.Stdout)
    },
}
```

Users install with `mytool completion bash > /etc/bash_completion.d/mytool`.

## Detection

- **ID:** `shell-completions`
- **Severity:** `info`
- **What to look for:** List all completion script generation capabilities. check for shell completion generation or documentation. In commander, check for `program.enablePositionalOptions()` or completion plugins. In oclif, completions are built-in. In cobra, check for `GenBashCompletion` / `GenZshCompletion` / `GenFishCompletion` methods. In clap, check for `generate` function from `clap_complete`. Look for a `completions` or `completion` subcommand, or documentation about shell completion setup.
- **Pass criteria:** The CLI provides shell completion scripts via a subcommand (`mytool completions bash`), a `--completions` flag, or has completion setup documented. At least bash and zsh are supported — at least 1 shell completion script (bash, zsh, or fish) should be generated or provided. Report: "X shell completion scripts available."
- **Fail criteria:** No shell completion support and no documentation about completion setup.
- **Skip (N/A) when:** The CLI has 2 or fewer commands with no complex options — completion adds little value. All checks skip when no CLI entry point is detected.
- **Detail on fail:** `"No shell completion support found — no 'completions' subcommand, no completion generation, and no documentation for completion setup"`
- **Remediation:** Shell completions dramatically improve the user experience for CLIs with many commands:

  ```ts
  // Node.js — tabtab or omelette for completions
  // Or with oclif, completions are built in:
  // mytool autocomplete bash

  // cobra (Go) — built-in completion generation
  var completionCmd = &cobra.Command{
      Use:   "completion [bash|zsh|fish|powershell]",
      Short: "Generate shell completion scripts",
      RunE: func(cmd *cobra.Command, args []string) error {
          switch args[0] {
          case "bash":
              return rootCmd.GenBashCompletion(os.Stdout)
          case "zsh":
              return rootCmd.GenZshCompletion(os.Stdout)
          }
          return nil
      },
  }
  ```

  ```rust
  // clap (Rust) — clap_complete crate
  use clap_complete::{generate, shells::Bash};
  generate(Bash, &mut cli, "mytool", &mut io::stdout());
  ```

Taxons: user-experience

HTML version: https://auditbuffet.com/patterns/ab-000661