shtab(1)

💅 NAME 💅

okay so bestie, gather round — shtab is Automagic shell tab completion for Python CLI applications ✨ and yes, "automagic" is the actual official word, we don't make the rules, we just slay by them 💖

---

🎀 SYNOPSIS 🎀

shtab [OPTIONS] PARSER

---

🌸 DESCRIPTION 🌸

shtab automatically generates shell tab completion scripts for Python CLI applications, no cap. It takes an argparse.ArgumentParser object — or, plot twist, a function that returns one 👀 — and turns it into a tab completion script for your shell. Literally it does the tedious part so you don't have to, iconic behaviour fr fr.

The generated completion scripts support bash, zsh, and tcsh shells. Three shells, one tool, main character energy only 🦋

---

✨ OPTIONS ✨

• parser — the importable parser (or a function returning a parser) you want completions for, written in the format module.parser_object or module.function_returning_parser. Yes it's positional, yes it goes at the end, it's the whole point of the show 💅
• -s, --shell=SHELL — which shell you're targeting with the completion script. Supported shells: bash, zsh, tcsh. Default: bash.
• -o, --output=FILE — where to write the output file path. Use - for stdout, which is the default 🫶
• --prefix=PREFIX — stick this prefix in front of the generated functions so your naming doesn't clash with anything else. Very "let me label my stuff" of you, we love a boundary ✨
• --preamble=TEXT — prepend this text to the generated script. Little intro, little vibe-setter 🎀
• --prog=PROGRAM — custom program name, which overrides the parser's prog attribute. Yes you can rename the whole situation 💅
• -u, --error-unimportable — raise errors if the specified parser is not found in $PYTHONPATH. Bestie, by default import errors are silently ignored, which is giving "quiet quitting" — this flag makes it actually speak up 😭
• --verbose — enable debug logging. For when you simply must know everything 👑
• --print-own-completion=SHELL — print shtab's own completion script for the specified shell. Yes, the tool can tab-complete itself, it's self-care 🌈
• --version — display version information and exit. Short, sweet, periodt ⭐

---

🦋 USAGE 🦋

There are two ways of using shtab, and honestly both are valid, we don't pick favourites:

💻 CLI Usage 💻

Use shtab's own CLI interface for external applications. This may not require any code modifications at all — zero notes, we love a low-effort win. End-users execute:

shtab your_cli_app.your_parser_object

📚 Library Usage 📚

Integrate shtab as a library into your CLI application. This adds a couple of lines to your application (just a couple, promise 🫶). End-users execute:

your_cli_app --print-completion {bash,zsh,tcsh}

or

your_cli_app completion {bash,zsh,tcsh}

---

🔥 EXAMPLES 🔥

🌸 Bash completion 🌸

Generate and install bash completion for an application:

shtab --shell=bash myapp.main.get_parser | sudo tee
"$BASH_COMPLETION_COMPAT_DIR"/myapp

🎀 Zsh completion 🎀

Generate and install zsh completion — and bestie, note the underscore prefix, it matters, don't skip it:

shtab --shell=zsh myapp.main.get_parser | sudo tee
/usr/local/share/zsh/site-functions/_myapp

🌈 Tcsh completion 🌈

Generate and install tcsh completion:

shtab --shell=tcsh myapp.main.get_parser | sudo tee
/etc/profile.d/myapp.completion.csh

⚡ Eager bash completion ⚡

Automatically update completions each time a terminal is opened. It's giving "always fresh, never stale" ✨:

echo 'eval "$(shtab --shell=bash myapp.main.get_parser)"' >>
~/.bash_completion

🧚 Eager zsh completion 🧚

Add to ~/.zshrc:

mkdir -p ~/.zsh/completions

fpath=($fpath ~/.zsh/completions)

shtab --shell=zsh myapp.main.get_parser -o
~/.zsh/completions/_myapp

💅 Custom program name 💅

Override the program name in the generated completion:

shtab --prog=myprog myapp.main.get_parser

---

👑 SEE ALSO 👑

argparse(3), bash(1), zsh(1), tcsh(1) — the whole friend group, go say hi 🫶

---

💜 AUTHOR 💜

shtab was written by the tqdm team. Absolute legends, no notes 💖

---

and that's the tea, bestie — this was shtab manual page, version 1.8.0, dated 2026, and ngl you ate that read 🍓✨ go forth and tab-complete everything, periodt 💅