completion-script-generator

Generates shell completion scripts for CLI tools. Parses command structure from help output, commander/yargs configs, or manual specification. Produces completions for bash, zsh, and fish that follow each shell's conventions.

Jump to install

Repository: curiositech/windags-skills
Last source activity: March 31, 2026 at 04:41
Detected SKILL.md language: English
Stars: 10
Forks: 2

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

Back to search Back to installation

name	completion-script-generator
license	Apache-2.0
description	Generates shell completion scripts for CLI tools. Parses command structure from help output, commander/yargs configs, or manual specification. Produces completions for bash, zsh, and fish that follow each shell's conventions.
category	Backend & Infrastructure
tags	["cli","completion","bash","zsh","fish","shell"]
allowed-tools	["Read","Bash(*)","Glob","Grep","Write","Edit"]
pairs-with	[{"skill":"beautiful-cli-design","reason":"Completions are a core part of CLI UX — a beautiful CLI without completions is half-finished"},{"skill":"daemon-development","reason":"Long-running daemon CLIs benefit most from completions since users interact frequently"},{"skill":"devtool-documentation","reason":"Completions serve as executable documentation of available commands and flags"}]

Completion Script Generator

Generate shell completion scripts that make CLIs feel native. Parses existing command structure from source code, help output, or manual specification, then produces idiomatic completions for bash, zsh, and fish. Handles subcommands, flags with arguments, mutually exclusive options, file completions, and dynamic completions that query the tool at runtime.

When to Use

Use for:

Adding tab completion to a CLI built with commander, yargs, clap, cobra, or argparse
Generating completions from --help output when source code is unavailable
Creating zsh completions with descriptions (the gold standard of shell completion UX)
Implementing dynamic completions that call the CLI to list valid values at runtime
Porting completions between shells (e.g., bash completions exist, need zsh and fish)
Adding completions to a CLI as part of the install/setup experience

Do NOT use for:

Building the CLI itself (use beautiful-cli-design)
General shell scripting (this is specifically about completion registration)
IDE/editor autocompletion (different system entirely)
Prompt customization (use shell config skills)

Core Capabilities

1. Command Structure Extraction

Before generating completions, you need the command tree. Three extraction methods, from most to least reliable:

Method A: Parse Source Code (Best)

For Node.js CLIs using commander:

# Extract commands and options from commander program
grep -rn '\.command(' src/cli.ts | while read -r line; do
  cmd=$(echo "$line" | grep -oP "\.command\(['\"]([^'\"]+)" | sed "s/.*['\"]//")
  echo "COMMAND: $cmd"
done

grep -rn '\.option(' src/cli.ts | while read -r line; do
  flag=$(echo  | grep -oP  | sed )
  desc=$(  | grep -oP  |  -1)

# Extract from yargs .command() and .option() calls
grep -rn '\.command(' src/ --include="*.ts" --include="*.js" | \
  grep -oP "command\(['\"]([^'\"]+)" | sed "s/command(['\"]//;s/['\"]$//"

# Capture help for main command and all subcommands
CLI="wg"
$CLI --help 2>&1 > /tmp/cli-help-main.txt

# Extract subcommands from help output
grep -E "^\s+\w+" /tmp/cli-help-main.txt | awk '{print $1}' | while read -r subcmd; do
  $CLI "$subcmd" --help 2>&1 > "/tmp/cli-help-$subcmd.txt" 2>/dev/null
done

# Extract flags
grep -oP '\-\-[\w-]+' /tmp/cli-help-main.txt | sort -u

# Define as a simple DSL
cat > /tmp/cli-spec.txt << 'SPEC'
command: execute
  --dag <file>        DAG definition file
  --topology <type>   Topology type (dag|swarm|team|blackboard)
  --dry-run           Show plan without executing
  --verbose           Enable verbose output

command: skill
  subcommand: search
    --query <text>    Search query
    --category <cat>  Filter by category
    --limit <n>       Max results (default: 10)
  subcommand: show
    <skill-id>        Skill identifier

command: history
  --limit <n>         Number of entries
  --format <fmt>      Output format (json|table|text)
SPEC

#!/bin/bash
# Completion for 'wg' CLI

_wg_completions() {
    local cur prev opts commands
    COMPREPLY=()
    cur="${COMP_WORDS[COMP_CWORD]}"
    prev="${COMP_WORDS[COMP_CWORD-1]}"

    # Top-level commands
    commands="execute skill history config"

    # Global options
    global_opts="--help --version --verbose --quiet"

    # If completing the first argument, suggest commands
    if [ "$COMP_CWORD" -eq 1 ]; then
        COMPREPLY=( $(compgen -W "$commands $global_opts" -- "$cur") )
        return 0
    fi

    # Subcommand-specific completions
    local subcmd="${COMP_WORDS[1]}"
    case "$subcmd" in
        execute)
            case "$prev" in
                --dag)
                    # Complete with .yaml and .json files
                    COMPREPLY=( $(compgen -f -X '!*.@(yaml|yml|json)' -- "$cur") )
                    return 0
                    ;;
                --topology)
                    COMPREPLY=( $(compgen -W "dag swarm team blackboard team-builder recurring workflow" -- "$cur") )
                    return 0
                    ;;
            esac
            opts="--dag --topology --dry-run --verbose --target-project"
            COMPREPLY=( $(compgen -W "$opts" -- "$cur") )
            ;;
        skill)
            if [ "$COMP_CWORD" -eq 2 ]; then
                COMPREPLY=( $(compgen -W "search show list" -- "$cur") )
            elif [ "${COMP_WORDS[2]}" = "search" ]; then
                case "$prev" in
                    --category)
                        # Dynamic: query the CLI for categories
                        local categories
                        categories=$(wg skill categories 2>/dev/null)
                        COMPREPLY=( $(compgen -W "$categories" -- "$cur") )
                        return 0
                        ;;
                esac
                COMPREPLY=( $(compgen -W "--query --category --limit --format" -- "$cur") )
            fi
            ;;
        history)
            case "$prev" in
                --format)
                    COMPREPLY=( $(compgen -W "json table text" -- "$cur") )
                    return 0
                    ;;
            esac
            COMPREPLY=( $(compgen -W "--limit --format" -- "$cur") )
            ;;
    esac

    return 0
}

complete -F _wg_completions wg

# Option 1: Source in .bashrc
echo 'source /path/to/wg-completion.bash' >> ~/.bashrc

# Option 2: Install to system completions directory
sudo cp wg-completion.bash /etc/bash_completion.d/wg

# Option 3: CLI self-install
wg completion bash > ~/.local/share/bash-completion/completions/wg

#compdef wg

# Completion for 'wg' CLI

_wg() {
    local -a commands
    commands=(
        'execute:Execute a DAG or topology'
        'skill:Search and manage skills'
        'history:View execution history'
        'config:Manage configuration'
    )

    _arguments -C \
        '(-h --help)'{-h,--help}'[Show help]' \
        '(-v --version)'{-v,--version}'[Show version]' \
        '--verbose[Enable verbose output]' \
        '--quiet[Suppress non-essential output]' \
        '1: :->command' \
        '*:: :->args'

    case $state in
        command)
            _describe -t commands 'wg commands' commands
            ;;
        args)
            case $words[1] in
                execute)
                    _wg_execute
                    ;;
                skill)
                    _wg_skill
                    ;;
                history)
                    _wg_history
                    ;;
            esac
            ;;
    esac
}

_wg_execute() {
    _arguments \
        '--dag[DAG definition file]:file:_files -g "*.{yaml,yml,json}"' \
        '--topology[Topology type]:topology:(dag swarm team blackboard team-builder recurring workflow)' \
        '--dry-run[Show execution plan without running]' \
        '--verbose[Enable verbose output]' \
        '--target-project[Target project directory]:directory:_directories' \
        '--env-file[Environment file]:file:_files -g "*.env*"'
}

_wg_skill() {
    local -a skill_commands
    skill_commands=(
        'search:Search skills by query'
        'show:Show skill details'
        'list:List all available skills'
    )

    _arguments -C \
        '1: :->skill_command' \
        '*:: :->skill_args'

    case $state in
        skill_command)
            _describe -t skill_commands 'skill commands' skill_commands
            ;;
        skill_args)
            case $words[1] in
                search)
                    _arguments \
                        '--query[Search query]:query:' \
                        '--category[Filter by category]:category:_wg_categories' \
                        '--limit[Max results]:count:' \
                        '--format[Output format]:format:(json table text)'
                    ;;
                show)
                    _arguments \
                        '1:skill:_wg_skill_ids'
                    ;;
            esac
            ;;
    esac
}

# Dynamic completion: query CLI for skill IDs
_wg_skill_ids() {
    local -a skills
    skills=(${(f)"$(wg skill list --format=completion 2>/dev/null)"})
    _describe -t skills 'skills' skills
}

# Dynamic completion: query CLI for categories
_wg_categories() {
    local -a categories
    categories=(${(f)"$(wg skill categories 2>/dev/null)"})
    _describe -t categories 'categories' categories
}

_wg_history() {
    _arguments \
        '--limit[Number of entries]:count:' \
        '--format[Output format]:format:(json table text)'
}

_wg "$@"

# Option 1: Place in fpath directory
cp _wg ~/.zsh/completions/_wg
# Ensure fpath includes this directory in .zshrc:
# fpath=(~/.zsh/completions $fpath)

# Option 2: CLI self-install
wg completion zsh > "${fpath[1]}/_wg"

# After installing, rebuild completion cache
rm -f ~/.zcompdump && compinit

# Completion for 'wg' CLI

# Disable file completion by default
complete -c wg -f

# Top-level commands
complete -c wg -n __fish_use_subcommand -a execute -d 'Execute a DAG or topology'
complete -c wg -n __fish_use_subcommand -a skill -d 'Search and manage skills'
complete -c wg -n __fish_use_subcommand -a history -d 'View execution history'
complete -c wg -n __fish_use_subcommand -a config -d 'Manage configuration'

# Global options
complete -c wg -l help -s h -d 'Show help'
complete -c wg -l version -s v -d 'Show version'
complete -c wg -l verbose -d 'Enable verbose output'
complete -c wg -l quiet -d 'Suppress non-essential output'

# execute subcommand
complete -c wg -n '__fish_seen_subcommand_from execute' -l dag -r -F -d 'DAG definition file'
complete -c wg -n '__fish_seen_subcommand_from execute' -l topology -r -xa 'dag swarm team blackboard team-builder recurring workflow' -d 'Topology type'
complete -c wg -n '__fish_seen_subcommand_from execute' -l dry-run -d 'Show plan without executing'
complete -c wg -n '__fish_seen_subcommand_from execute' -l target-project -r -xa '(__fish_complete_directories)' -d 'Target project directory'

# skill subcommand
complete -c wg -n '__fish_seen_subcommand_from skill; and not __fish_seen_subcommand_from search show list' -a search -d 'Search skills'
complete -c wg -n '__fish_seen_subcommand_from skill; and not __fish_seen_subcommand_from search show list' -a show -d 'Show skill details'
complete -c wg -n '__fish_seen_subcommand_from skill; and not __fish_seen_subcommand_from search show list' -a list -d 'List all skills'

# skill search options
complete -c wg -n '__fish_seen_subcommand_from skill; and __fish_seen_subcommand_from search' -l query -r -d 'Search query'
complete -c wg -n '__fish_seen_subcommand_from skill; and __fish_seen_subcommand_from search' -l category -r -xa '(wg skill categories 2>/dev/null)' -d 'Category filter'
complete -c wg -n '__fish_seen_subcommand_from skill; and __fish_seen_subcommand_from search' -l limit -r -d 'Max results'
complete -c wg -n '__fish_seen_subcommand_from skill; and __fish_seen_subcommand_from search' -l format -r -xa 'json table text' -d 'Output format'

# skill show - dynamic skill ID completion
complete -c wg -n '__fish_seen_subcommand_from skill; and __fish_seen_subcommand_from show' -xa '(wg skill list --format=completion 2>/dev/null)'

# history subcommand
complete -c wg -n '__fish_seen_subcommand_from history' -l limit -r -d 'Number of entries'
complete -c wg -n '__fish_seen_subcommand_from history' -l format -r -xa 'json table text' -d 'Output format'

# Fish completions auto-load from this directory
cp wg.fish ~/.config/fish/completions/wg.fish

# Or CLI self-install
wg completion fish > ~/.config/fish/completions/wg.fish

// In your CLI's completion command handler
import { writeFileSync } from 'fs';
import { join } from 'path';
import { homedir } from 'os';
import { execSync } from 'child_process';

function installCompletions(shell: 'bash' | 'zsh' | 'fish'): void {
  const script = generateCompletionScript(shell);

  switch (shell) {
    case 'bash': {
      const dir = join(homedir(), '.local/share/bash-completion/completions');
      execSync(`mkdir -p "${dir}"`);
      writeFileSync(join(dir, 'wg'), script);
      console.log(`Bash completions installed. Restart your shell or run: source ${join(dir, 'wg')}`);
      break;
    }
    case 'zsh': {
      const dir = join(homedir(), '.zsh/completions');
      execSync(`mkdir -p "${dir}"`);
      writeFileSync(join(dir, '_wg'), script);
      console.log(`Zsh completions installed. Run: rm -f ~/.zcompdump && compinit`);
      break;
    }
    case 'fish': {
      const dir = join(homedir(), '.config/fish/completions');
      execSync(`mkdir -p "${dir}"`);
      writeFileSync(join(dir, 'wg.fish'), script);
      console.log(`Fish completions installed. Available immediately.`);
      break;
    }
  }
}

# Detect current shell
case "$SHELL" in
  */bash) shell="bash" ;;
  */zsh)  shell="zsh" ;;
  */fish) shell="fish" ;;
  *)      echo "Unknown shell: $SHELL"; exit 1 ;;
esac

Approach	When to Use	Tradeoff
Static	Fixed option lists, enum values	Fast, no runtime dependency
Dynamic	Skill IDs, project names, resource lists	Slower, always current
Cached dynamic	Large lists that change slowly	Best of both, stale risk

# Test in isolated bash session
bash --norc --noprofile -c 'source ./wg-completion.bash && complete -p wg'

# Test in isolated zsh session
zsh -f -c 'fpath=(. $fpath); autoload -Uz compinit; compinit; source ./_wg'

# In the completion function, use cache
_wg_projects() {
    local cache_file="${XDG_CACHE_HOME:-$HOME/.cache}/wg/projects.txt"
    if [ -f "$cache_file" ] && [ $(( $(date +%s) - $(stat -f%m "$cache_file" 2>/dev/null || stat -c%Y "$cache_file") )) -lt 3600 ]; then
        # Cache is fresh (< 1 hour)
        COMPREPLY=( $(compgen -W "$(cat "$cache_file")" -- "$cur") )
    else
        # Cache stale, regenerate
        local projects=$(wg project list --format=names 2>/dev/null)
        mkdir -p "$(dirname "$cache_file")"
        echo "$projects" > "$cache_file"
        COMPREPLY=( $(compgen -W "$projects" -- "$cur") )
    fi
}