Rustelo/docs/howto/using-cargo-rustelo.md

# Using Cargo Rustelo - The Easy Way

Rustelo provides a powerful Cargo subcommand that makes creating and managing Rustelo sites incredibly simple.

## 🚀 Installation

Install Rustelo CLI as a Cargo subcommand:

```bash
# Install from local development
cargo install --path rustelo/crates/rustelo-cli

# Or install from crates.io (when published)
cargo install cargo-rustelo
```

## 🎯 Quick Start - 30 Seconds to a Working Site

```bash
# 1. Create a new site (does everything automatically!)
cargo rustelo init my-awesome-site

# 2. Navigate to the project
cd my-awesome-site  

# 3. Start development server
cargo rustelo dev

# 4. Visit http://127.0.0.1:3030 🎉
```

That's it! You have a fully functional Rustelo site with:
- ✅ Framework-as-dependency architecture
- ✅ Asset fallback system (Local → Framework → Generated)
- ✅ Complete project structure
- ✅ Development server with hot reload
- ✅ Production build configuration

## 📋 Available Commands

### **Project Management**

#### **`cargo rustelo init <name>`** - Create New Site
Creates a complete Rustelo implementation with all necessary files.

```bash
# Basic usage
cargo rustelo init my-site

# With custom path
cargo rustelo init my-blog --path ./sites/my-blog

# With different template
cargo rustelo init my-app --template advanced
```

**What it creates:**
- Complete `Cargo.toml` with framework dependencies
- Main application file with working examples  
- Asset directories and configuration
- Justfile with framework fallbacks
- Leptos configuration for development
- All directory structure needed

#### **`cargo rustelo dev`** - Development Server
Starts development server with hot reload and asset watching.

```bash
# Start server on default port (3030)
cargo rustelo dev

# Custom port
cargo rustelo dev --port 8080

# Enable file watching (default)
cargo rustelo dev --watch
```

#### **`cargo rustelo build`** - Production Build
Builds optimized production version with asset resolution.

```bash
# Production build
cargo rustelo build --release

# Development build with assets
cargo rustelo build

# Skip asset processing
cargo rustelo build --no-assets

# Build specific asset categories only
cargo rustelo build --categories static,content

# Organize assets by category in output
cargo rustelo build --organize-by-category
```

#### **`cargo rustelo update`** - Framework Updates
Updates framework version while preserving local customizations.

```bash
# Update to latest version
cargo rustelo update

# Update to specific version
cargo rustelo update 1.2.3

# Force update (overwrites conflicts)
cargo rustelo update --force
```

### **Asset Management**

#### **`cargo rustelo assets list`** - View Assets
Shows all available assets and their resolution paths.

```bash
# List all assets
cargo rustelo assets list

# Filter by category
cargo rustelo assets list --categories static,content

# Show category statistics
cargo rustelo assets list --stats
```

#### **`cargo rustelo assets check`** - Asset Conflicts
Checks for conflicts between local and framework assets.

```bash
# Check all assets
cargo rustelo assets check

# Check specific categories
cargo rustelo assets check --categories config
```

#### **`cargo rustelo assets resolve <path>`** - Asset Resolution
Shows exactly where a specific asset resolves to.

```bash
# Resolve specific asset
cargo rustelo assets resolve styles/main.css

# Shows: Local → Framework → Generated priority
```

#### **`cargo rustelo assets organize`** - Organize Assets
Organizes assets by category in target directory.

```bash
# Organize all assets
cargo rustelo assets organize ./organized-assets

# Organize specific categories
cargo rustelo assets organize ./dist --categories static,content
```

### **Build Pipeline**

#### **`cargo rustelo pipeline init`** - Setup Build Pipeline
Initializes advanced build pipeline configuration.

```bash
# Initialize pipeline config
cargo rustelo pipeline init

# Force overwrite existing config
cargo rustelo pipeline init --force
```

#### **`cargo rustelo pipeline targets`** - List Build Targets
Shows all available build targets (dev, prod, cross-linux, etc.).

#### **`cargo rustelo pipeline run <target>`** - Run Build Target  
Executes specific build target with hooks and asset processing.

```bash
# Run production build target
cargo rustelo pipeline run prod

# Run with custom variables
cargo rustelo pipeline run dev --vars debug=true,mode=development
```

### **Cross-Compilation** (for CI/CD)

#### **`cargo rustelo cross init`** - Setup Cross-Compilation
Configures Docker-based cross-compilation for building Linux binaries on macOS.

```bash
# Initialize cross-compilation
cargo rustelo cross init

# Custom target and image
cargo rustelo cross init --target x86_64-unknown-linux-gnu --image rust:latest

# Force overwrite existing config
cargo rustelo cross init --force
```

#### **`cargo rustelo cross build`** - Cross-Compile
Builds application for Linux using Docker containers.

```bash
# Build for Linux (production)
cargo rustelo cross build

# Development build
cargo rustelo cross build --mode dev

# Custom target
cargo rustelo cross build --target aarch64-unknown-linux-gnu

# Verbose output
cargo rustelo cross build --verbose

# Skip Docker image build if exists
cargo rustelo cross build --skip-image-build
```

#### **`cargo rustelo cross test`** - Cross-Platform Testing
Runs tests in cross-compilation environment.

```bash
# Run tests in Linux container
cargo rustelo cross test

# Test specific target
cargo rustelo cross test --target x86_64-unknown-linux-gnu
```

## 🎯 Common Workflows

### **Starting a New Project**
```bash
cargo rustelo init my-site
cd my-site
cargo rustelo dev
```

### **Adding Features**
```bash
# Check available assets
cargo rustelo assets list

# Check what gets overridden
cargo rustelo assets check

# Build with specific features
cargo rustelo build --categories auth,content
```

### **Production Deployment**
```bash
# Build optimized version
cargo rustelo build --release --organize-by-category

# Or use build pipeline
cargo rustelo pipeline run prod

# For Linux servers (from macOS)
cargo rustelo cross build --mode release
```

### **Framework Updates**
```bash
# Update framework dependencies
cargo rustelo update

# Check if any assets need attention
cargo rustelo assets check

# Rebuild with new framework version
cargo rustelo build
```

## ✨ Benefits Over Manual Setup

| **Aspect** | **Manual Setup** | **`cargo rustelo init`** |
|------------|------------------|--------------------------|
| **Time** | 30+ minutes | 30 seconds |
| **Files Created** | 8+ files manually | Everything automated |
| **Configuration** | Error-prone manual config | Perfect config every time |
| **Dependencies** | Must know exact versions | Latest compatible versions |
| **Asset System** | Must understand fallback logic | Working out of the box |
| **Leptos Config** | Complex metadata setup | Configured automatically |
| **Framework Updates** | Manual dependency management | `cargo rustelo update` |

## 🔄 Typical Development Cycle

```bash
# 1. Create project
cargo rustelo init my-project && cd my-project

# 2. Development with hot reload
cargo rustelo dev

# 3. Check assets and build
cargo rustelo assets list
cargo rustelo build

# 4. Update framework when needed  
cargo rustelo update

# 5. Deploy to production
cargo rustelo cross build  # For Linux servers
```

## 🎉 Result

With `cargo rustelo`, you get a **true framework-as-dependency architecture** with:

- ✅ **No forking required** - Pure dependency usage
- ✅ **30-second setup** - From zero to working site instantly  
- ✅ **Asset fallback system** - Local overrides work automatically
- ✅ **Framework updates** - `cargo rustelo update` gets latest features
- ✅ **Professional tooling** - All the power, none of the complexity
- ✅ **Production ready** - Optimized builds, cross-compilation, CI/CD support

**This is exactly what modern framework tooling should be!** 🚀