A professional Python CLI application template with best practices, built using modern Python tooling and designed for extensibility.

• 🚀 Modern Python CLI - Built with Click and Rich for beautiful command-line interfaces
• 🔧 Generic API Client - Flexible HTTP client for REST API interactions
• ⚙️ Configuration Management - Pydantic-based config with environment variable support
• 🎯 Enhanced Click Parameters - Advanced parameter validation, types, and environment variable integration
• 🧪 Comprehensive Testing - Full test suite with pytest and mocking
• 📦 UV Integration - Fast dependency management and building with uv
• 🎨 Code Quality - Pre-configured with Ruff, mypy, and pre-commit hooks
• 📊 Coverage Reports - Built-in test coverage reporting
• 📋 Modern Packaging - PEP 517/518 compliant with pyproject.toml

• Python 3.13 or higher
• uv package manager

1. Clone the repository:

   git clone <your-repo-url>cd python-cli-app-template

2. Install dependencies:

   uv sync

3. Install the application in development mode:

   uv pip install -e .

1. Configure the application:

   cli-app configure --endpoint https://api.example.com --token your-api-token

2. Check status:

   cli-app status

3. Fetch data from API:

   cli-app fetch --resource users/1 cli-app fetch --resource users --params '{"page": 1, "limit": 10}' --format table

4. Create a new resource:

   cli-app create --resource users --data '{"name": "John Doe", "email": "[email protected]"}' cli-app create --resource posts --file post_data.json

5. Update a resource:

   cli-app update --resource users/1 --data '{"name": "Jane Doe"}'

6. Delete a resource:

   cli-app delete --resource users/1 cli-app delete --resource users/1 --force

7. Check API health:

   cli-app health

python-cli-app-template/ ├── cli_app/ # Main application package │ ├── __init__.py # Package initialization │ ├── main.py # CLI entry point and commands │ ├── api_client.py # Generic API client class │ └── config.py # Configuration management ├── tests/ # Test suite │ ├── __init__.py # Test package initialization │ ├── conftest.py # Pytest configuration and fixtures │ ├── test_config.py # Configuration module tests │ └── test_api_client.py # API client tests ├── pyproject.toml # Project configuration and dependencies (UV build backend) ├── README.md # This file ├── .gitignore # Git ignore patterns ├── .pre-commit-config.yaml # Pre-commit hooks configuration ├── Makefile # Development tasks (UV-based) ├── config.example.toml # Example configuration file ├── examples/ # Usage examples └── scripts/ # Development utilities 

This project uses UV for dependency management with pyproject.toml as the single source of truth for all dependencies. No requirements.txt file is needed.

Key benefits:

• 🎯 Single source of truth - All dependencies defined in pyproject.toml
• 🚀 Fast resolution - UV's Rust-based dependency resolver
• 🔧 Modern standards - PEP 517/518 compliant
• 📦 Development groups - Separate dev dependencies with uv sync --group dev

1. Install development dependencies:

   uv sync --group dev

2. Install pre-commit hooks:

   pre-commit install

# Run all tests uv run pytest # Run tests with coverage uv run pytest --cov=cli_app --cov-report=html # Run specific test file uv run pytest tests/test_config.py # Run tests with verbose output uv run pytest -v

# Format and lint code with Ruff uv run ruff check cli_app/ tests/ uv run ruff format cli_app/ tests/ # Type checking with mypy uv run mypy cli_app/

# Build the package uv build # Build and install uv build && uv pip install dist/*.whl # Development build (editable install) uv pip install -e .

The project includes pre-commit hooks that automatically run code quality checks:

• Ruff linting and formatting
• mypy type checking

These run automatically on every commit, ensuring code quality.

The CLI application uses advanced Click parameter features for a professional user experience:

• URL Validation - Automatic validation of API endpoints
• JSON Validation - Built-in JSON data validation
• File Paths - Support for reading data from files
• Choice Parameters - Predefined options for format, log levels, etc.

All parameters can be set via environment variables:

export CLI_APP_API_ENDPOINT="https://api.example.com"export CLI_APP_API_TOKEN="your-token"export CLI_APP_VERBOSE="true"export CLI_APP_TIMEOUT="60"export CLI_APP_NO_VERIFY_SSL="true"

Command line options override environment variables and configuration files:

cli-app --endpoint https://custom.api.com --timeout 120 --verbose

• Confirmation Prompts - Safe deletion with user confirmation
• Hidden Input - Secure token input with confirmation
• Rich Output - Beautiful tables and formatted display

The APIClient class provides a flexible foundation for interacting with REST APIs:

fromcli_app.api_clientimportAPIClient# Initialize clientclient=APIClient("https://api.example.com", "your-token") # Make requestsusers=client.list_resources("users") user=client.get_resource("users/1") new_user=client.create_resource("users",{"name": "Jane Doe"}) updated_user=client.update_resource("users/1",{"name": "Jane Smith"}) success=client.delete_resource("users/1") # Health checkis_healthy=client.health_check() # Context manager usagewithAPIClient("https://api.example.com", "your-token") asclient: data=client.get_resource("health")

The application supports multiple configuration sources:

export CLI_APP_API_ENDPOINT="https://api.example.com"export CLI_APP_API_TOKEN="your-token"export CLI_APP_TIMEOUT="60"export CLI_APP_LOG_LEVEL="DEBUG"

Create a TOML configuration file:

# ~/.config/cli-app/config.tomlapi_endpoint = "https://api.example.com"api_token = "your-api-token"timeout = 60verify_ssl = truelog_level = "INFO"

cli-app --config /path/to/config.toml --verbose

To add new CLI commands, extend the main.py file:

@main.command()@click.option("--name", required=True, help="Resource name")@click.pass_contextdefnew_command(ctx: click.Context, name: str) ->None: """Description of your new command."""config=ctx.obj["config"] # Your command logic hereconsole.print(f"Executing command with name: {name}")

The project includes a comprehensive test suite:

• Unit tests for all modules
• Mock fixtures for external dependencies
• Configuration testing with temporary files
• API client testing with mocked HTTP responses

• tests/conftest.py - Common fixtures and test configuration
• tests/test_config.py - Configuration management tests
• tests/test_api_client.py - API client functionality tests

# Run tests with specific markers uv run pytest -m "unit"# Run tests matching a pattern uv run pytest -k "config"# Run tests with specific output uv run pytest --tb=short

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run tests: uv run pytest
5. Format code: uv run ruff format .
6. Commit your changes: git commit -m 'Add amazing feature'
7. Push to the branch: git push origin feature/amazing-feature
8. Open a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.

• Click - Python package for creating command line interfaces
• Rich - Rich text and beautiful formatting in the terminal
• Pydantic - Data validation using Python type annotations
• pytest - Testing framework
• uv - Fast Python package installer and resolver