🦀 Rust CLI Template

🚀 A modern, feature-rich Rust CLI application template with best practices baked in.

Use As GitHub Template

Click Use this template on GitHub, or generate directly with cargo-generate:

✨ Features

This template provides everything you need to build a professional Rust CLI application:

• 🔧 Layered Configuration - Flexible configuration management with config-rs
• 🎯 Command Line Parsing - Powerful argument parsing and shell completions with clap
• 📁 XDG Directory Support - Cross-platform directory handling with directories
• 📊 Structured Logging - Comprehensive logging and tracing with tracing
• 🎨 Beautiful Error Handling - User-friendly error messages with miette
• ⚡ Async Runtime - High-performance async support with graceful shutdown using tokio
• 🤖 GitHub Automation - Built-in CI, security audit, and Dependabot workflows
• 🧰 Task Runner - just recipes for build, test, lint, docs, and publishing
• ✍️ Editor Defaults - Preconfigured VS Code and .editorconfig defaults

📦 Quick Start

Prerequisites

First, install cargo-generate:

cargo install cargo-generate

Usage

Generate into a new subfolder:

cargo generate --git https://github.com/hiranp/rust-cli-template.git

Generate in the current directory:

cargo generate --init --git https://github.com/hiranp/rust-cli-template.git

🏗️ Project Structure

your-cli-app/
├── src/
│   ├── main.rs          # Application entry point
│   ├── cli.rs           # Command line interface definition
│   ├── config.rs        # Configuration management
│   ├── log.rs           # Logging setup
│   └── commands/        # Command implementations
│       ├── mod.rs
│       ├── command1.rs
│       ├── command2.rs
│       └── completion.rs
├── config/
│   └── config.toml      # Default configuration
├── build.rs             # Build script for completions
└── Cargo.toml          # Project dependencies

🚀 What You Get

• Modern Rust: Uses Rust 2024 edition with latest best practices
• Shell Completions: Auto-generated completions for bash, zsh, fish, and PowerShell
• Configuration Files: TOML-based configuration with environment variable support
• Structured Commands: Clean command structure with subcommands support
• Graceful Shutdown: Proper signal handling and resource cleanup
• Cross-platform: Works on Windows, macOS, and Linux

🛠️ Development

After generating your project:

# Build the project
cargo build

# Run with debug logging
RUST_LOG=debug cargo run

# Generate shell completions
cargo run -- completion bash > completions.bash

# Run tests
cargo test

# Check code quality
cargo clippy
cargo fmt

Using just (recommended):

# Install once
cargo install just

# Run local CI checks
just check

# Build release binaries
just release

# Publish after checks
just publish

📝 Configuration

The template includes a layered configuration system:

1. Default values in config/config.toml
2. Environment variables (prefixed with your app name)
3. Command line arguments (highest priority)

Example configuration structure:

[app]
name = "my-cli-app"
version = "0.1.0"

[logging]
level = "info"
file = "app.log"

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

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

🙏 Acknowledgments

• Built with ❤️ using the amazing Rust ecosystem
• Inspired by modern CLI best practices
• Thanks to all the crate maintainers for their excellent work