Command-Line Auto-Completion¶
STRUCT 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.
Structure Name Completion
STRUCT completes structure names when using struct generate
, showing available structures from both built-in and custom paths.
Quick Setup¶
Ask struct to print the exact commands for your shell:
# Auto-detect current shell and print install steps
struct completion install
# Or specify explicitly
struct completion install zsh
struct completion install bash
struct completion install fish
You can also generate completion files manually with shtab as shown below.
Manual Installation¶
1) Install shtab¶
2) Generate and install completion for your shell¶
- Zsh
mkdir -p ~/.zfunc
struct --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
struct --print-completion bash > ~/.local/share/bash-completion/completions/struct
source ~/.bashrc
- Fish
mkdir -p ~/.config/fish/completions
struct --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¶
Structure Name Completion ✨¶
# Complete structure names - shows all available structures!
struct generate <Tab>
# Shows: ansible-playbook, docker-files, github/workflows/codeql, project/nodejs, etc.
# Partial completion works too
struct generate git<Tab>
# Shows: git-hooks, github/workflows/codeql, github/templates, etc.
# Works with nested structures
struct generate github/<Tab>
# Shows: github/workflows/codeql, github/templates, github/prompts/generic, etc.
Custom Structure Paths¶
# Completion works with custom structure paths
struct generate --structures-path /custom/path <Tab>
# Shows structures from both custom path and built-in structures
Option Completion¶
struct generate --<Tab>
# Shows: --log, --dry-run, --backup, --file-strategy, --structures-path, etc.
struct 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=$(struct 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¶
- Verify shtab is installed in the environment you’re using:
-
Confirm the completion file exists in the expected location and is readable.
-
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/.
-
Restart your shell (or run
exec zsh
/source ~/.bashrc
).
Debug Completion¶
For shell-specific debugging, check that the generated file contains the struct 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 STRUCT in Docker, completion won't work directly. However, you can create a wrapper script:
Then set up completion for the wrapper:
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¶
STRUCT 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:
- Dynamically discovers all available structure files (
.yaml
files) - Scans multiple locations:
- Built-in structures in
struct_module/contribs/
- Custom structures from
--structures-path
if specified - Returns clean names without
.yaml
extensions - Supports nested directories like
github/workflows/codeql
- Updates automatically when new structures are added
Example Session¶
# Command completion
$ struct <Tab>
generate generate-schema info list validate
# Structure name completion (NEW!)
$ struct 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
$ struct generate proj<Tab>
project/custom-structures project/go project/nodejs project/ruby
project/generic project/java project/python project/rust
# Nested structure completion
$ struct 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
$ struct generate --<Tab>
--backup --dry-run --file-strategy --log
--log-file --mappings-file --structures-path --vars
# Enum value completion
$ struct generate --log <Tab>
DEBUG ERROR INFO WARNING CRITICAL
$ struct generate --file-strategy <Tab>
append backup overwrite rename skip
This makes working with STRUCT much more efficient and user-friendly!