cargo-x402 0.3.1

Scaffold x402 projects from templates.
Documentation

Author: 👋 Hi, I'm CryptoPatrick! I create tools and frameworks for the Rust ecosystem. If you have questions or want to connect, reach out on X/Twitter.

🛎 Status

  • v1.0.0 - Production-ready release
  • 208+ tests passing across all platforms
  • 5 official templates included and maintained
  • Multi-platform support - macOS, Linux, Windows
  • Fully open-source and community-driven

🤔 What is cargo-x402

cargo-x402 is a template scaffolding tool that helps you create production-ready Rust projects in seconds. It automatically discovers templates from GitHub repositories tagged with x402-template and provides an interactive CLI for creating projects with custom parameters.

Instead of manually setting up boilerplate code, copying files, and configuring projects, cargo-x402 handles it all instantly—and it's customizable for your needs.

Use Cases

  • Rapid Prototyping: Start API projects in seconds with batteries included
  • Standardized Architecture: Enforce consistent project structure across teams
  • Best Practices: Include production-grade patterns (logging, observability, database)
  • Full-Stack Development: Scaffold complete applications (frontend + backend)
  • CLI Tools: Create command-line utilities with proper argument parsing
  • Microservices: Deploy production-ready services with observability built-in

How It Works

1. List templates          cargo-x402 list
2. Choose template         Interactive selection
3. Enter project details   Project name, author, options
4. Done!                   Full project ready to develop

📷 Features

Core Capabilities

  • Template Discovery: Automatic discovery from GitHub via x402-template topic
  • Interactive CLI: User-friendly terminal interface with colored output
  • Smart Caching: 1-hour cache with manual refresh option
  • Parameter Handling: Support for string, boolean, and enum parameters
  • Schema Validation: Comprehensive validation of template configuration
  • Liquid Templating: Safe variable substitution with conditionals and loops

Template System

  • x402.toml Schema: Declarative template configuration
  • File Rules: Include/exclude patterns for flexible file management
  • Version Constraints: Specify minimum Rust and cargo-x402 versions
  • Parameter Validation: Regex patterns and enum options for user input
  • Metadata Support: Template name, description, authors, and tags
  • GitHub Integration: Seamless discovery and download from GitHub

Developer Experience

  • Zero Configuration: Works out of the box
  • Progress Indicators: Visual feedback for all operations
  • Helpful Error Messages: Clear guidance when something goes wrong
  • Smart Defaults: Sensible defaults reduce the number of prompts
  • Git Integration: Automatic git repository initialization
  • Template Examples: 5 official templates to get started

🚙 Quick Start

Installation

Install from crates.io:

cargo install cargo-x402

Or build from source:

git clone https://github.com/xForth/cargo-x402.git
cd cargo-x402
cargo install --path .

Your First Project (30 seconds)

Option 1: Interactive Mode

# Start interactive menu
cargo-x402

# Follow prompts to:
# 1. Browse available templates
# 2. Select template
# 3. Enter project name and options
# 4. Confirm and create

Option 2: Direct Command

# Create project directly
cargo-x402 create --template xForth/x402-template-basic-api --name my-api

# Skips template selection and uses defaults

Option 3: List Templates First

# See all available templates
cargo-x402 list

# Show templates matching tags
cargo-x402 list --tags rust,api

What You Get

After running cargo-x402 create, you'll have:

my-awesome-api/
├── src/
│   └── main.rs              # Ready-to-run code
├── Cargo.toml               # Configured dependencies
├── README.md                # Project documentation
├── .gitignore               # Git configuration
├── .env.example             # Environment template
├── Dockerfile               # Container support
└── .git/                    # Initialized git repo

Everything is ready to build and run:

cd my-awesome-api
cargo build
cargo run

📦 Templates

Official Templates (v0.2.0)

1. Basic Axum API

Production-ready REST API with Axum framework

Features:

  • Health check endpoints
  • Request/response handling
  • Structured logging
  • Error handling

Use for: Quick API prototypes, microservices, REST backends

2. Axum + PostgreSQL

Full-featured API with database support

Features:

  • SQLx with Postgres
  • Database migrations
  • Connection pooling
  • CRUD operations

Use for: Data-driven applications, persistent storage requirements

3. Full-Stack (Axum + React)

Complete web application with backend and frontend

Features:

  • Axum REST API backend
  • React 18 frontend with TypeScript
  • Vite build system
  • CORS configuration
  • Docker Compose setup

Use for: Web applications, SPA + API combos, full-stack projects

4. Microservice with Observability

Production-grade microservice with tracing and metrics

Features:

  • Jaeger distributed tracing
  • Prometheus metrics
  • Structured logging
  • JSON output
  • Health checks

Use for: Cloud deployments, observability needs, production services

5. CLI Tool

Professional command-line tool template

Features:

  • Clap argument parsing
  • Colored output
  • Progress indicators
  • File operations
  • Error handling

Use for: CLI utilities, scripts, command-line tools

Create Your Own Template

See TEMPLATE_AUTHOR_GUIDE.md for:

  • Template structure and format
  • Parameter configuration
  • Publishing on GitHub
  • Best practices

📚 Documentation

For Users

  • QUICKSTART.md - Get started in 10 minutes
    • Installation methods
    • Your first project
    • Common customizations
    • FAQs and troubleshooting

For Template Authors

  • TEMPLATE_AUTHOR_GUIDE.md - Create custom templates
    • Complete template structure guide
    • x402.toml manifest specification
    • Liquid templating syntax and examples
    • Parameter validation and file handling
    • Publishing and GitHub discovery
    • Best practices and troubleshooting

For Developers

🗺️ Roadmap

v1.0.0 ✅ (Current - Production Ready)

  • Stable public API
  • 5 official maintained templates
  • Comprehensive test coverage (208+ tests)
  • Full documentation and guides
  • Multi-platform support (macOS, Linux, Windows)

v1.1.0 (Q1 2025)

  • Enhanced template caching and offline mode
  • Template repository metadata indexing
  • Improved parameter validation with custom validators
  • Template dependency resolution

v1.2.0 (Q2 2025)

  • Local template support (non-GitHub templates)
  • Custom template hooks (pre/post generation)
  • Private repository template support
  • Performance profiling and optimization

v2.0.0 (Q3-Q4 2025)

  • Official template marketplace/registry
  • IDE integrations (VS Code, IntelliJ)
  • Template signing and verification
  • Advanced dependency management

🖊 Author

CryptoPatrick - Rust ecosystem tools & frameworks

🐣 Support

Star ⭐ this project if you find it useful!

Report Issues

Get Help

🤝 Contributing

Found a bug? Want a feature? Have a template idea?

Contributions are welcome! Please see CONTRIBUTING.md for:

  • Code style and standards
  • Testing requirements
  • Submitting PRs
  • Development setup

Ways to Contribute

  1. Report Bugs - Found an issue? Open a GitHub issue
  2. Suggest Features - Have an idea? Share it in discussions
  3. Create Templates - Build and publish templates to GitHub
  4. Improve Docs - Help improve guides and documentation
  5. Submit Code - Fix bugs or implement features

🗄 License

This project is licensed under the MIT License. See LICENSE for details.