silicon

A Python CLI hello world template with best practices for packaging, testing, and CI/CD.

✨ Features

• Modern CLI: Built with Typer for a clean command-line interface
• Well-Structured: Source layout with src/ directory and proper packaging
• Comprehensive Testing: pytest with coverage requirements and parallel execution
• CI/CD Ready: GitHub Actions workflows for testing, versioning, and releases
• Multi-Platform: PyPI, Homebrew, and pre-built binary distribution

💖 Support

Love this tool? Your support means the world! ❤️

Currency	Address	QR
₿ BTC	bc1qwn7ea6s8wqx66hl5rr2supk4kv7qtcxnlqcqfk
Ξ ETH	0x7cdB1861AC1B4385521a6e16dF198e7bc43fDE5f
ɱ XMR	463fMSWyDrk9DVQ8QCiAir8TQd4h3aRAiDGA8CKKjknGaip7cnHGmS7bQmxSiS2aYtE9tT31Zf7dSbK1wyVARNgA9pkzVxX
◈ BNB	0x7cdB1861AC1B4385521a6e16dF198e7bc43fDE5f

📦 Installation

Homebrew (macOS/Linux)

brew tap alkalescent/tap
brew install silicon

PyPI (Recommended)

uv pip install silicon

After installation, use either the command directly or as a Python module:

# Direct command
silicon --help

# As Python module (if direct command not in PATH)
uv run python -m silicon --help

From Source

Clone the repository and install in development mode:

git clone https://github.com/alkalescent/silicon.git
cd silicon
make install DEV=1  # Install with dev dependencies

Pre-built Binaries

Download from GitHub Releases:

Variant	Description	Startup	Format
Portable	Single file, no installation needed	~10 sec	silicon-{os}-portable
Fast	Optimized for speed	~1 sec	silicon-{os}-fast.tar.gz

Note: In the filenames and commands, replace {os} with your operating system (e.g., linux, macos). The examples below use linux. For Windows, you may need to use a tool like 7-Zip to extract .tar.gz archives.

For Portable, download and run directly:

chmod +x silicon-linux-portable
./silicon-linux-portable --help

For Fast, extract the archive and run from within:

tar -xzf silicon-linux-fast.tar.gz
./cli.dist/silicon --help

Build from Source

Build your own binaries using Nuitka:

git clone https://github.com/alkalescent/silicon.git
cd silicon

# Build portable (single file, slower startup)
MODE=onefile make build

# Build fast (directory, faster startup)
MODE=standalone make build

🚀 Usage

The CLI provides simple hello and goodbye commands.

Hello Command

Say hello to someone:

silicon hello                    # Hello, World!
silicon hello --name Developer   # Hello, Developer!
silicon hello -n "Your Name"     # Hello, Your Name!

Goodbye Command

Say goodbye to someone:

silicon goodbye                  # Goodbye, World!
silicon goodbye --name Developer # Goodbye, Developer!
silicon goodbye -n "Your Name"   # Goodbye, Your Name!

Version

Check the installed version:

silicon version    # v1.0.0
silicon --version  # v1.0.0
silicon -v         # v1.0.0

🧪 Testing

Run the test suite:

make test

Run with coverage reporting (requires 90% coverage):

make cov

Run smoke tests:

make smoke

🏗️ Architecture

The CLI consists of the following modules:

• tools.py: Core utility classes

  • Greeter class: Simple greeting functionality

• cli.py: Command-line interface using Typer

  • hello: Say hello to someone
  • goodbye: Say goodbye to someone
  • version: Display version

• test_tools.py / test_cli.py: Comprehensive test suites

📖 Using as a Template

1. Fork or clone this repository
2. Replace silicon with your project name in:
   • pyproject.toml (name, scripts, URLs)
   • src/silicon/ directory name
   • Imports in source files
   • README.md
3. Add your own functionality in tools.py and cli.py
4. Update tests accordingly

📚 Dependencies

• typer: Modern CLI framework

📄 License

MIT License - see LICENSE for details.