CLI Commands

Sherwood provides a command-line interface for site generation, development, and validation. All commands use consistent patterns and provide helpful feedback.

Available Commands

generate

Generates a static site from Markdown content.

cargo run --bin generate -- [OPTIONS]

Options:

• --input <DIR>: Source directory containing Markdown files (default: content)
• --output <DIR>: Output directory for generated HTML (default: dist)

Examples:

# Use default directories (content → dist)
cargo run --bin generate

# Custom input/output directories
cargo run --bin generate -- --input src --output build

# Using binary directly if installed
sherwood generate --input content --output dist

Process:

1. Scans input directory for .md files
2. Parses Markdown with frontmatter
3. Extracts titles and metadata
4. Renders HTML using templates
5. Bundles and processes CSS
6. Generates file structure in output directory

dev

Starts development server with live reload functionality.

cargo run --bin dev -- [OPTIONS]

Options:

• --input <DIR>: Source directory containing Markdown files (default: content)
• --output <DIR>: Output directory for generated HTML (default: dist)
• --port <PORT>: Server port (default: 3000)
• --host <HOST>: Server host (default: localhost)

Features:

• Live Reload: Automatically regenerates site when content changes
• File Watching: Monitors input directory for changes
• Development Server: Serves generated files with proper headers
• Error Display: Shows build errors in browser overlay

Examples:

# Default development server (localhost:3000)
cargo run --bin dev

# Custom port and directories
cargo run --bin dev -- --port 8080 --input src --output build

# External access (for mobile testing)
cargo run --bin dev -- --host 0.0.0.0 --port 3000

validate

Validates configuration and content without generating files.

cargo run --bin validate -- [OPTIONS]

Options:

• --input <DIR>: Source directory to validate (default: content)
• --output <DIR>: Output directory for validation checks (default: dist)

Validates:

• ✅ Frontmatter syntax and fields
• ✅ Markdown parsing errors
• ✅ Template file existence
• ✅ CSS configuration validity
• ✅ Directory structure consistency

Examples:

# Validate default content directory
cargo run --bin validate

# Validate custom source
cargo run --bin validate -- --input src/content

Common Usage Patterns

Development Workflow

# 1. Start development server
cargo run --bin dev

# 2. In another terminal, validate changes
cargo run --bin validate

# 3. When ready, generate production build
cargo run --bin generate

Custom Project Structure

# Project with custom directories
cargo run --bin dev -- --input docs --output public

# CI/CD pipeline validation
cargo run --bin validate -- --input docs --output public
cargo run --bin generate -- --input docs --output public

Production Build

# Clean build directory
rm -rf dist/

# Generate production site
cargo run --bin generate

# Optional: Optimize output
find dist -name "*.html" -exec gzip -k {} \;
find dist -name "*.css" -exec gzip -k {} \;

Command Aliases

You can create shell aliases for convenience:

Bash/Zsh:

# Add to ~/.bashrc or ~/.zshrc
alias sherwood='cargo run --bin'
alias sherwood-dev='cargo run --bin dev'
alias sherwood-build='cargo run --bin generate'
alias sherwood-validate='cargo run --bin validate'

Fish Shell:

# Add to ~/.config/fish/config.fish
alias sherwood 'cargo run --bin'
alias sherwood-dev 'cargo run --bin dev'
alias sherwood-build 'cargo run --bin generate'
alias sherwood-validate 'cargo run --bin validate'

Exit Codes

Sherwood returns specific exit codes for automation:

• 0: Success
• 1: General error (parse error, file not found)
• 2: Validation error (invalid configuration)
• 3: Build error (template missing, syntax error)

Using in Scripts:

#!/bin/bash
cargo run --bin validate
case $? in
  0) echo "✅ Validation passed"
     cargo run --bin generate
     ;;
  1) echo "❌ Error occurred"
     exit 1
     ;;
  2) echo "❌ Validation failed"
     exit 1
     ;;
esac

Environment Variables

Sherwood respects several environment variables:

• RUST_LOG: Set logging level (debug, info, warn, error)
• SHERWOOD_INPUT: Default input directory
• SHERWOOD_OUTPUT: Default output directory
• SHERWOOD_PORT: Default server port
• SHERWOOD_HOST: Default server host

Examples:

# Enable debug logging
RUST_LOG=debug cargo run --bin dev

# Set custom defaults
export SHERWOOD_INPUT=src/docs
export SHERWOOD_OUTPUT=public
cargo run --bin generate

Performance Considerations

Build Performance

# Enable release mode for production builds
cargo build --release

# Use binary directly after initial build
./target/release/sherwood generate

# Parallel processing (future feature)
# cargo run --bin generate -- --parallel

Development Performance

# Limit file watching to specific directories (future feature)
# cargo run --bin dev -- --watch-only content

# Exclude certain file patterns (future feature)
# cargo run --bin dev -- --exclude "*.tmp" --exclude "node_modules/*"

Troubleshooting

Common Issues

"No such file or directory"

# Check current directory and files
ls -la
ls content/

# Use explicit paths
cargo run --bin generate -- --input ./content --output ./dist

"Permission denied"

# Check directory permissions
ls -ld content/ dist/

# Fix permissions
chmod 755 content/ dist/
chmod 644 content/*.md

"Frontmatter parse error"

# Validate specific files
cargo run --bin validate -- --input content/problem-file.md

# Check YAML/TOML syntax
# YAML:
python -c "import yaml; yaml.safe_load(open('content/file.md', 'r').read())"

# TOML:
python -c "import toml; toml.load(open('content/file.md', 'r').read())"

Debug Mode

Enable detailed logging for troubleshooting:

# Enable debug logging
RUST_LOG=debug cargo run --bin dev 2>&1 | tee sherwood.log

# Parse-specific file
RUST_LOG=debug cargo run --bin validate -- --input content/specific-file.md

Integration Examples

Makefile Integration

.PHONY: dev build validate clean

dev:
	cargo run --bin dev

build:
	cargo run --bin generate

validate:
	cargo run --bin validate

clean:
	rm -rf dist/

deploy: validate build
	# Deployment commands here

npm Scripts Integration

{
  "scripts": {
    "dev": "cargo run --bin dev",
    "build": "cargo run --bin generate",
    "validate": "cargo run --bin validate",
    "clean": "rm -rf dist/",
    "deploy": "npm run validate && npm run build"
  }
}

GitHub Actions

name: Build Site
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions-rs/toolchain@v1
        with:
          toolchain: stable
      - name: Validate
        run: cargo run --bin validate
      - name: Build
        run: cargo run --bin generate

This CLI reference provides everything needed to effectively use Sherwood's command-line interface for development and production workflows.