Spicy CLI

A modern Python command-line interface with multiple commands.

Features

• Multiple commands with subcommands
• Rich terminal output with colors and formatting
• Configuration management
• Detailed help text for all commands
• Type annotations and validation
• Automatic shell completion
• Comprehensive CI/CD with GitHub Actions
• Pre-commit hooks for code quality

Installation

For regular use, install with pipx:

pipx install spicy-cli

For development:

git clone https://github.com/darkflib/spicy-cli.git
cd spicy-cli
uv venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv sync

Install pre-commit hooks:

uv run pre-commit install

On Windows with Microsoft Store Python, you might encounter issues with pre-commit. Use our helper script:

.\scripts\fix_precommit_windows.bat

See CONTRIBUTING.md for more detailed development setup instructions.

Usage

Show help:

spicy --help

Show version:

spicy --version
# or
spicy version

Command 1

Run command 1:

spicy command1 run "Your Name"
spicy command1 run --formal --count 3 "Your Name"

Check status:

spicy command1 status
spicy command1 status --verbose

Command 2

Process files:

spicy command2 process file1.txt file2.txt
spicy command2 process --output result.txt --force file1.txt file2.txt file3.invalid

List items:

spicy command2 list
spicy command2 list --limit 5 --all

Configuration

Show current configuration:

spicy config show

Change a setting:

spicy config set timeout 60
spicy config set debug true

Reset to defaults:

spicy config reset

Plugins

List available plugins:

spicy plugin list

Create a new plugin template:

spicy plugin create "My Plugin" -o my_plugin.py

Install a plugin:

spicy plugin install my_plugin.py

Uninstall a plugin:

spicy plugin uninstall my-plugin

Example Plugin: Weather

The project includes an example weather plugin in the examples directory:

# Install the example plugin
spicy plugin install examples/weather_plugin.py

# Get current weather
spicy weather current "London, UK"
spicy weather current "New York" --fahrenheit

# Get forecast
spicy weather forecast "Tokyo" --days 5

Development

Development Scripts

The project includes convenient scripts for common development tasks:

# On Unix/Linux/Mac:
./scripts/run.sh lint     # Run all linting tools
./scripts/run.sh format   # Format code with black and isort
./scripts/run.sh test     # Run tests with coverage
./scripts/run.sh clean    # Clean build artifacts
./scripts/run.sh build    # Build the package
./scripts/run.sh install  # Install in development mode
./scripts/run.sh run      # Run the CLI (e.g. './scripts/run.sh run --help')
./scripts/run.sh help     # Show help

# On Windows:
scripts\run.bat lint
scripts\run.bat format
# etc.

These scripts automatically create and use a virtual environment with uv.

Testing

Run tests with pytest:

pytest

Run tests with coverage:

pytest --cov=spicy_cli

Formatting and Type Checking

Format code with black:

black .

Sort imports:

isort .

Type check with mypy:

mypy .

Lint with ruff:

ruff check .

Lint with pylint (with 120 char line length):

pylint src/ tests/

Development

Quick Start

# Clone the repository
git clone https://github.com/darkflib/spicy-cli.git
cd spicy-cli

# Set up development environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

# Install pre-commit hooks
make pre-commit-install

Available Make Commands

This project includes a Makefile with common development tasks:

make help              # Show all available commands
make dev               # Install development dependencies
make test              # Run tests
make test-all          # Run tests with full coverage reports
make lint              # Run all linting tools
make format            # Format code with black and isort
make type-check        # Run mypy type checking
make security          # Run security checks (safety, bandit)
make ci                # Run all CI checks locally
make clean             # Clean build artifacts
make build             # Build the package
make pre-commit        # Run pre-commit on all files

Windows Alternative

On Windows, you can use the provided batch script instead of make:

dev.bat help           # Show all available commands
dev.bat dev            # Install development dependencies
dev.bat test           # Run tests
dev.bat lint           # Run all linting tools
dev.bat ci             # Run all CI checks locally

CI/CD

This project uses GitHub Actions for continuous integration and deployment:

• CI Workflow (ci.yml): Runs tests, linting, and type checking on multiple Python versions and operating systems
• Release Workflow (release.yml): Automatically publishes to PyPI when a release is created
• Code Quality Workflow (code-quality.yml): Runs security scans, dependency reviews, and automated dependency updates
• Documentation Workflow (docs.yml): Builds and deploys documentation (if present)

All workflows use uv for fast, reliable dependency management.

Pre-commit Hooks

Pre-commit hooks are configured to run:

• black for code formatting
• isort for import sorting
• ruff for linting and auto-fixes
• mypy for type checking
• pylint for additional code quality checks

Install them with:

make pre-commit-install

Docker

To run Spicy CLI in a Docker container, you can use the provided Dockerfile. This allows you to run the CLI without needing to install Python or its dependencies on your local machine.

Build and Run

To build and run the Docker container, you can use Docker Compose. The provided docker-compose.yml file sets up the environment for you.

Build and run with Docker compose:

docker-compose up --build

Run a specific command:

docker-compose run spicy-cli command1 run "Docker User"

Build and Run for multiarch support

docker buildx build --platform linux/amd64,linux/arm64 -t spicy-cli:latest --push .
docker run --rm -it spicy-cli:latest

License

MIT