# Building Python Clis

> Builds command-line interfaces for Python libraries using Click or Typer. Includes command groups, argument handling, progress bars, shell completion, and CLI testing with CliRunner. Use when adding CLI functionality to a library or building standalone command-line tools.

- **Type:** Skill
- **Install:** `agentstack add skill-wdm0006-python-skills-cli-development`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [wdm0006](https://agentstack.voostack.com/s/wdm0006)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [wdm0006](https://github.com/wdm0006)
- **Source:** https://github.com/wdm0006/python-skills/tree/main/skills/cli-development

## Install

```sh
agentstack add skill-wdm0006-python-skills-cli-development
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Python CLI Development

## Framework Selection

**Click** (Recommended): Mature, extensive features
**Typer**: Modern, type-hint focused
**argparse**: Zero dependencies, standard library

## Click Quick Start

```python
import click

@click.group()
@click.version_option(version='1.0.0')
def cli():
    """My CLI tool."""
    pass

@cli.command()
@click.argument('input_file', type=click.Path(exists=True))
@click.option('--output', '-o', default='-', help='Output file')
@click.option('--verbose', '-v', is_flag=True)
def process(input_file, output, verbose):
    """Process an input file."""
    if verbose:
        click.echo(f"Processing {input_file}")
    # ...

if __name__ == '__main__':
    cli()
```

## Entry Point (pyproject.toml)

```toml
[project.scripts]
mycli = "my_package.cli:cli"

[project.optional-dependencies]
cli = ["click>=8.0"]
```

## Common Patterns

```python
# File I/O with stdin/stdout support
@click.argument('input', type=click.File('r'), default='-')
@click.argument('output', type=click.File('w'), default='-')

# Progress bar
with click.progressbar(items, label='Processing') as bar:
    for item in bar:
        process(item)

# Colored output
click.secho("Success!", fg='green', bold=True)
click.secho("Error!", fg='red', err=True)

# Error handling
if not valid:
    raise click.BadParameter(f'Invalid value: {value}')
```

## Testing with CliRunner

```python
from click.testing import CliRunner
from mypackage.cli import cli

def test_process():
    runner = CliRunner()
    result = runner.invoke(cli, ['process', 'input.txt'])
    assert result.exit_code == 0
    assert 'expected output' in result.output

def test_stdin():
    runner = CliRunner()
    result = runner.invoke(cli, ['process', '-'], input='test data\n')
    assert result.exit_code == 0
```

## Shell Completion

```bash
# Generate completion scripts
_MYCLI_COMPLETE=bash_source mycli > ~/.mycli-complete.bash
_MYCLI_COMPLETE=zsh_source mycli > ~/.mycli-complete.zsh
```

For detailed patterns, see:
- **[CLICK_PATTERNS.md](CLICK_PATTERNS.md)** - Advanced Click usage
- **[TYPER_GUIDE.md](TYPER_GUIDE.md)** - Typer alternative

## CLI Checklist

```
Setup:
- [ ] Entry point in pyproject.toml
- [ ] --help works for all commands
- [ ] --version displays version

UX:
- [ ] Errors go to stderr with non-zero exit
- [ ] Helpful error messages
- [ ] stdin/stdout support where appropriate

Testing:
- [ ] Tests for all commands
- [ ] Test error cases
- [ ] Test stdin processing
```

## Learn More

This skill is based on the [Guide to Developing High-Quality Python Libraries](https://mcginniscommawill.com/guides/python-library-development/) by [Will McGinnis](https://mcginniscommawill.com/). See these posts for related coverage:

- [Makefiles for Python Development](https://mcginniscommawill.com/posts/2025-04-08-makefiles-for-python/)
- [pyproject.toml Explained](https://mcginniscommawill.com/posts/2025-01-26-pyproject-toml-explained/)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [wdm0006](https://github.com/wdm0006)
- **Source:** [wdm0006/python-skills](https://github.com/wdm0006/python-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-wdm0006-python-skills-cli-development
- Seller: https://agentstack.voostack.com/s/wdm0006
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.