{
    "slug": "py_cli_tools",
    "term": "CLI Tools with argparse & Click",
    "category": "python",
    "difficulty": "intermediate",
    "short": "Building Python command-line tools — argparse (stdlib) for simple tools, Click (decorator-based) for complex CLIs with subcommands, type coercion, and better help formatting.",
    "long": "argparse (stdlib): define arguments programmatically, automatic --help, type conversion, positional vs optional arguments. Click: decorator-based (@click.command, @click.option, @click.argument), composable subcommand groups, automatic prompting, password hiding, file handling, and better error messages. Typer: Click wrapper with type hints — Python type annotations define CLI arguments. Use argparse for simple scripts, Click/Typer for complex tools distributed as packages. Both generate --help automatically from function docstrings and argument definitions.",
    "aliases": [
        "argparse",
        "Click",
        "Typer",
        "Python CLI",
        "command line"
    ],
    "tags": [
        "python",
        "cli",
        "tooling"
    ],
    "misconception": "sys.argv is sufficient for CLI argument parsing — sys.argv requires manual parsing with no type conversion, validation, or --help generation; argparse/Click handle all of this automatically.",
    "why_it_matters": "A well-built CLI tool with --help, type validation, and informative errors is as important as the tool's functionality — poor CLI UX makes good tools hard to use and hard to script.",
    "common_mistakes": [
        "Parsing sys.argv manually instead of using argparse/Click.",
        "No input validation — argparse type= parameter handles this automatically.",
        "Missing default values — always provide defaults or mark arguments as required explicitly.",
        "No subcommands for multi-action tools — Click's @click.group() organises complex CLIs cleanly."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "py_pathlib",
        "bash_scripting",
        "py_packaging"
    ],
    "prerequisites": [
        "py_type_hints",
        "py_error_handling",
        "bash_scripting"
    ],
    "refs": [
        "https://click.palletsprojects.com/"
    ],
    "bad_code": "# Manual sys.argv parsing — fragile:\nimport sys\nif len(sys.argv) < 3:\n    print('Usage: tool.py input output')\n    sys.exit(1)\ninput_file = sys.argv[1]\noutput_file = sys.argv[2]\n# No type checking, no --help, no --verbose flag support",
    "good_code": "import click\n\n@click.group()\n@click.option('--verbose', '-v', is_flag=True, help='Enable verbose output')\n@click.pass_context\ndef cli(ctx, verbose):\n    ctx.ensure_object(dict)\n    ctx.obj['VERBOSE'] = verbose\n\n@cli.command()\n@click.argument('input', type=click.Path(exists=True))\n@click.argument('output', type=click.Path())\n@click.option('--format', type=click.Choice(['json', 'csv']), default='json')\n@click.pass_context\ndef process(ctx, input, output, format):\n    if ctx.obj['VERBOSE']: click.echo(f'Processing {input} -> {output}')\n    # Auto --help generated from docstring\n\nif __name__ == '__main__': cli()",
    "quick_fix": "Use argparse or Click for CLI argument parsing — they auto-generate help text, validate types, and handle --verbose --quiet flags without custom parsing code",
    "severity": "low",
    "effort": "low",
    "created": "2026-03-16",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/py_cli_tools",
        "html_url": "https://codeclaritylab.com/glossary/py_cli_tools",
        "json_url": "https://codeclaritylab.com/glossary/py_cli_tools.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[CLI Tools with argparse & Click](https://codeclaritylab.com/glossary/py_cli_tools) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/py_cli_tools"
            }
        }
    }
}