Command-Line Auto-Completion

October 28, 2025 · View on GitHub

StructKit provides intelligent auto-completion for commands, options, and structure names using static completion scripts generated by shtab. This approach is reliable across shells and doesn’t require runtime hooks or markers.

!!! tip "Structure Name Completion" StructKit completes structure names when using structkit generate, showing available structures from both built-in and custom paths.

Quick Setup

Ask structkit to print the exact commands for your shell:

# Auto-detect current shell and print install steps
structkit completion install

# Or specify explicitly
structkit completion install zsh
structkit completion install bash
structkit completion install fish

You can also generate completion files manually with shtab as shown below.

Manual Installation

1) Install shtab

pip install shtab

2) Generate and install completion for your shell

  • Zsh

    mkdir -p ~/.zfunc
structkit --print-completion zsh > ~/.zfunc/_struct
# ensure in ~/.zshrc
fpath=(~/.zfunc $fpath)
autoload -U compinit && compinit
exec zsh

  • Bash

    mkdir -p ~/.local/share/bash-completion/completions
structkit --print-completion bash > ~/.local/share/bash-completion/completions/struct
source ~/.bashrc

  • Fish

    mkdir -p ~/.config/fish/completions
structkit --print-completion fish > ~/.config/fish/completions/struct.fish
fish -c 'source ~/.config/fish/completions/struct.fish'

Usage

After installing the completion, use Tab to complete commands/options:

Command Completion

structkit <Tab>
# Shows: generate, generate-schema, validate, info, list

Structure Name Completion ✨

# Complete structure names - shows all available structures!
structkit generate <Tab>
# Shows: ansible-playbook, docker-files, github/workflows/codeql, project/nodejs, etc.

# Partial completion works too
structkit generate git<Tab>
# Shows: git-hooks, github/workflows/codeql, github/templates, etc.

# Works with nested structures
structkit generate github/<Tab>
# Shows: github/workflows/codeql, github/templates, github/prompts/generic, etc.

Custom Structure Paths

# Completion works with custom structure paths
structkit generate --structures-path /custom/path <Tab>
# Shows structures from both custom path and built-in structures

Option Completion

structkit generate --<Tab>
# Shows: --log, --dry-run, --backup, --file-strategy, --structures-path, etc.

structkit generate --log <Tab>
# Shows: DEBUG, INFO, WARNING, ERROR, CRITICAL

Advanced Configuration

Per-Project Completion

If you only want completion for a specific project/venv, generate the completion from the project’s venv and place it under your user completion directory (examples above). No runtime eval is needed.

Custom Completion

You can create custom completion functions for specific use cases:

# Custom completion for structure names
_struct_structures() {
    local structures=$(structkit list --names-only 2>/dev/null)
    COMPREPLY=($(compgen -W "$structures" -- "${COMP_WORDS[COMP_CWORD]}"))
}

# Register custom completion
complete -F _struct_structures struct-generate

Troubleshooting

Completion Not Working

  1. Verify shtab is installed in the environment you’re using:

    python -c "import shtab; print('OK')"

  2. Confirm the completion file exists in the expected location and is readable.

  3. Ensure your shell is configured to load completions:

    • zsh: fpath includes ~/.zfunc and compinit is run.
    • bash: bash-completion is installed and sourced (on some distros).
    • fish: the file is in ~/.config/fish/completions/.

  4. Restart your shell (or run exec zsh/source ~/.bashrc).

Debug Completion

For shell-specific debugging, check that the generated file contains the structkit completion function and is in the correct directory for your shell.

Platform-Specific Notes

macOS

On macOS, you may need to install bash-completion (for bash) or ensure zsh’s compinit is configured:

# Using Homebrew
brew install bash-completion
# bash profile
[[ -r "/usr/local/etc/profile.d/bash_completion.sh" ]] && . "/usr/local/etc/profile.d/bash_completion.sh"

Windows

For Windows users using Git Bash or WSL, follow the same steps as Linux. PowerShell is not covered by shtab; use bash/zsh/fish.

Docker

When running StructKit in Docker, completion won't work directly. However, you can create a wrapper script:

#!/bin/bash
# struct-wrapper.sh
docker run --rm -v $(pwd):/workdir ghcr.io/httpdss/structkit:main "$@"

Then set up completion for the wrapper:

eval "$(register-python-argcomplete struct-wrapper.sh)"

Benefits of Auto-Completion

  • Faster typing: Quickly complete command names and options
  • Discoverability: See available commands and options
  • Accuracy: Reduce typos and errors
  • Productivity: Spend less time looking up command syntax

Supported Completions

StructKit provides intelligent completion for:

  • Commands: generate, validate, list, info, generate-schema
  • Options: --log, --dry-run, --backup, --file-strategy, --structures-path, etc.
  • Structure names: All 47+ available built-in and custom structures
    • Built-in structures: ansible-playbook, docker-files, helm-chart, etc.
    • Nested structures: github/workflows/codeql, project/nodejs, terraform/apps/generic, etc.
    • Custom structures: From --structures-path directories
  • File paths: Local files and directories
  • Enum values: Log levels (DEBUG, INFO, etc.), file strategies (overwrite, skip, etc.)

How Structure Completion Works

The structure name completion feature:

  1. Dynamically discovers all available structure files (.yaml files)
  2. Scans multiple locations:
    • Built-in structures in structkit/contribs/
    • Custom structures from --structures-path if specified
  3. Returns clean names without .yaml extensions
  4. Supports nested directories like github/workflows/codeql
  5. Updates automatically when new structures are added

Example Session

# Command completion
$ structkit <Tab>
generate        generate-schema info           list           validate

# Structure name completion (NEW!)
$ structkit generate <Tab>
ansible-playbook     configs/codeowners    github/workflows/codeql  project/nodejs
chef-cookbook        docker-files          helm-chart               terraform/apps/generic
ci-cd-pipelines      git-hooks            kubernetes-manifests      vagrant-files

# Partial completion
$ structkit generate proj<Tab>
project/custom-structures  project/go      project/nodejs  project/ruby
project/generic           project/java    project/python  project/rust

# Nested structure completion
$ structkit generate github/<Tab>
github/chatmodes/plan       github/prompts/react-form    github/workflows/codeql
github/instructions/generic github/prompts/security-api  github/workflows/labeler
github/prompts/generic      github/workflows/pre-commit  github/workflows/stale

# Option completion
$ structkit generate --<Tab>
--backup        --dry-run       --file-strategy --log
--log-file      --mappings-file --structures-path --vars

# Enum value completion
$ structkit generate --log <Tab>
DEBUG    ERROR    INFO     WARNING  CRITICAL

$ structkit generate --file-strategy <Tab>
append    backup    overwrite    rename    skip

This makes working with StructKit much more efficient and user-friendly!