{"id":2283,"library":"shtab","title":"Automagic shell tab completion for Python CLI applications","description":"shtab is a Python library that automatically generates shell tab completion scripts for command-line interface (CLI) applications. It processes an `argparse.ArgumentParser` object to produce completion scripts for `bash`, `zsh`, and `tcsh`. It aims for speed and correctness, avoiding the side-effects and performance issues of alternatives like `argcomplete` and `pyzshcomplete`. As of version 1.8.0, it is actively maintained by Iterative AI, with its development often driven by the needs of projects like DVC, but designed for general-purpose use.","status":"active","version":"1.8.0","language":"en","source_language":"en","source_url":"https://github.com/iterative/shtab","tags":["cli","shell","completion","autocomplete","argparse","bash","zsh","tcsh"],"install":[{"cmd":"pip install shtab","lang":"bash","label":"PyPI"},{"cmd":"conda install -c conda-forge shtab","lang":"bash","label":"Conda"}],"dependencies":[{"reason":"Requires Python 3.9 or newer.","package":"python","optional":false}],"imports":[{"note":"While 'from shtab import complete' might work, the documentation and common usage patterns often show `import shtab` and then `shtab.complete()` or `shtab.add_argument()` on the parser directly, especially when integrating with an existing application's parser.","wrong":"from shtab import complete","symbol":"complete","correct":"import shtab; shtab.complete(...)"},{"note":"Used to add a completion argument directly to an argparse parser for library usage.","symbol":"add_argument","correct":"import shtab; shtab.add_argument(parser, ...)"}],"quickstart":{"code":"import argparse\nimport shtab\nimport os\n\ndef get_main_parser():\n    parser = argparse.ArgumentParser(prog='mycli', description='A simple CLI tool')\n    parser.add_argument('--auth-key', type=str, default=os.environ.get('MYCLI_AUTH_KEY', ''), help='Authentication key')\n    parser.add_argument('--output', '-o', choices=['json', 'yaml', 'text'], default='text', help='Output format')\n    parser.add_argument('command', choices=['status', 'run', 'config'], help='Command to execute')\n    return parser\n\nif __name__ == '__main__':\n    parser = get_main_parser()\n    \n    # Integrate shtab for completion. This creates a hidden argument like --print-completion\n    shtab.add_argument(parser, shells=['bash', 'zsh', 'tcsh'])\n    \n    args = parser.parse_args()\n\n    # Example of how a user would generate and install completion:\n    # mycli --print-completion bash > ~/.bashrc.d/mycli.bash-completion\n    # source ~/.bashrc.d/mycli.bash-completion\n    \n    print(f\"Running command: {args.command}\")\n    if args.auth_key:\n        print(\"Auth key provided.\")\n    else:\n        print(\"No auth key provided.\")\n    print(f\"Output format: {args.output}\")","lang":"python","description":"This quickstart demonstrates how to integrate `shtab` into an `argparse`-based CLI application. By calling `shtab.add_argument(parser)`, a hidden argument (e.g., `--print-completion`) is added to your parser, allowing users to generate completion scripts for their shell. Users would then run `python your_script.py --print-completion bash` to get the script and install it according to their shell's instructions (e.g., sourcing it in their `.bashrc`). The example includes common argparse features like choices and environment variable defaults."},"warnings":[{"fix":"Refer to `shtab` documentation for OS-specific installation steps for bash-completion or zsh completion. Ensure your shell config (`.bashrc`, `.zshrc`) properly sources completion files and that the generated script is in the correct location. Verify `shtab` and your application are in `PATH` and `PYTHONPATH` if necessary.","message":"Shell environment setup is crucial. Users must ensure their shell (e.g., bash, zsh) is configured to source completion scripts, and the `shtab`-generated script is placed in a directory where the shell looks for completions (e.g., `~/.bashrc.d/`, `$fpath` for zsh). In addition, both `shtab` and the application it's completing must be accessible/importable from the environment where the completion script is generated and used.","severity":"gotcha","affected_versions":"All versions"},{"fix":"When using `shtab` from the CLI, add the `--error-unimportable` flag to get explicit error messages if the parser cannot be imported. Always ensure `argparse.ArgumentParser(prog=\"YOUR_CLI_NAME\")` matches the name users will type, or use `shtab --prog=YOUR_CLI_NAME ...` to override it.","message":"By default, `shtab` may silently fail if it cannot import the requested application's parser object. This can lead to confusion if completion isn't working as expected without any error messages. Additionally, the `prog` argument of `argparse.ArgumentParser` must accurately reflect the executable's name for correct completion, especially when using `options.entry_points.console_scripts` or direct script execution.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}