shtab(1)

NAME
shtab - Automagic shell tab completion for Python CLI applications

SYNOPSIS
shtab [OPTIONS] PARSER

DESCRIPTION
shtab automatically generates shell tab completion scripts for Python CLI applications. It processes an argparse.ArgumentParser object (or a function returning one) to generate a tab completion script for your shell.

The generated completion scripts support bash, zsh, and tcsh shells.

OPTIONS

parser
    Importable parser (or function returning parser) in the format module.parser_object or module.function_returning_parser.

-s, --shell=SHELL
    Target shell for completion script. Supported shells: bash, zsh, tcsh. Default: bash.

-o, --output=FILE
    Output file path. Use - for stdout (default).

--prefix=PREFIX
    Prepend this prefix to generated functions to avoid naming clashes.

--preamble=TEXT
    Prepend this text to the generated script.

--prog=PROGRAM
    Custom program name (overrides the parser's prog attribute).

-u, --error-unimportable
    Raise errors if the specified parser is not found in $PYTHONPATH. By default, import errors are silently ignored.

--verbose
    Enable debug logging.

--print-own-completion=SHELL
    Print shtab's own completion script for the specified shell.

--version
    Display version information and exit.

USAGE

There are two ways of using shtab:

  CLI Usage
Use shtab's own CLI interface for external applications. This may not require any code modifications. 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. 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 (note the underscore prefix):

    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:

    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)

AUTHOR
shtab was written by the tqdm team.