CLI Reference

Gozzi provides a powerful command-line interface for building and serving static sites. All commands support both global and command-specific options.

Global Flags

Available for all commands:

gozzi --help     # Show help information  
gozzi --version  # Show version, build time, and git commit

Commands Overview

❯ gozzi
Usage: gozzi <command> [options]

Commands:
  build    Generate static site
  serve    Start development server with live reload
  help     Show help information
  version  Show version information

Use "gozzi help <command>" for more information about a command

Build Command

Generate your static site from content and templates.

❯ gozzi help build
Usage: gozzi build [options]

Options:
  --config string  Path to config file (default "config.toml")
  --content string Content directory (default "content")
  --clean          Clean output directory before build (removes all files)

Examples

# Basic build with default configuration (incremental)
gozzi build

# Build with custom config file
gozzi build --config config.prod.toml

# Build with custom content directory
gozzi build --content posts

# Clean build (removes all files in output directory)
gozzi build --clean

# Build with both custom config and content
gozzi build --config config.dev.toml --content src/content

Build Process

The build command:

1. Loads configuration from the specified config file
2. Parses content from the content directory (Markdown files)
3. Creates output directory if it doesn't exist (preserves existing files)
4. Processes templates and applies them to content
5. Generates static files in the output directory (overwrites only Gozzi-generated files)
6. Reports build time for performance monitoring

Incremental Builds

By default, Gozzi performs incremental builds that preserve existing files in the output directory. This allows you to:

• Mix Gozzi with other tools (e.g., Python scripts generating search indexes)
• Keep user-generated files in the output directory
• Faster rebuilds by not removing/recreating unchanged files

Benefits:

• ✅ Preserves files like search_index.json generated by external tools
• ✅ Works well with gozzi serve for development
• ✅ No need to worry about losing custom files

Use --clean flag when you want a fresh build:

gozzi build --clean

This is useful for:

• Production deployments
• Removing stale content
• Debugging build issues

Serve Command

Start a development server with live reload functionality.

❯ gozzi help serve
Usage: gozzi serve [options]

Options:
  --config string  Path to config file (default "config.toml")
  --content string Content directory (default "content")
  --port int       Port to listen on (default 1313)

Examples

# Start development server on default port 1313
gozzi serve

# Start on custom port
gozzi serve --port 8080

# Serve with custom configuration
gozzi serve --config config.dev.toml --port 3000

# Serve with custom content directory
gozzi serve --content drafts --port 1314

Development Server Features

The development server provides:

🔄 Live Reload

• Automatically reloads browser when files change
• Uses Server-Sent Events (SSE) for instant updates
• No browser extensions needed

📁 File Watching

• Monitors multiple directories:
  • Content directory (.md files)
  • Templates directory (.html files)
  • Static assets (.css, .js files)
  • Configuration file (config.toml)

⚡ Smart Rebuilding

• Debounced rebuilds (500ms delay) to avoid excessive rebuilds
• Incremental processing for faster rebuild times
• Config hot-reloading without server restart
• Template reloading for instant theme changes

🔧 Development Optimizations

• Serves from output directory with smart caching
• Custom 404 page handling
• Automatic index.html serving for directories
• Live reload script injection into HTML pages

📊 Build Feedback

• Real-time build time reporting
• Error logging for failed builds
• Change detection notifications

Live Reload Details

When you run gozzi serve, the server:

1. Initial Build: Parses content and generates the site
2. File Watching: Monitors file system changes using fsnotify
3. Change Detection: Detects relevant file changes (.md, .html, .css, .js, config.toml)
4. Smart Rebuilding: Debounces changes and rebuilds incrementally
5. Browser Notification: Sends reload signal via /livereload endpoint
6. Auto Refresh: Browser automatically refreshes to show changes

The live reload script is automatically injected into HTML pages:

(new EventSource('/livereload')).onmessage = () => location.reload()

Help Command

Get detailed help for any command.

# General help
gozzi help

# Command-specific help
gozzi help build
gozzi help serve

# Alternative syntax (equivalent)
gozzi build --help
gozzi serve --help

Version Command

Display version information with build details.

❯ gozzi version
gozzi version 0.2.1
Build time:   2024-10-28T10:30:45Z
Git commit:   abc123def

Version Output

• Version number: Semantic versioning (e.g., 0.2.1)
• Build time: UTC timestamp of when binary was built
• Git commit: Short commit hash for traceability

Advanced Usage Patterns

Development Workflow

# Start development with custom port and config
gozzi serve --config config.dev.toml --port 3000

# In another terminal, watch for specific issues
tail -f logs/gozzi.log

# Build for production
gozzi build --config config.prod.toml

Multi-Environment Setup

# Development
gozzi serve --config config.dev.toml --content drafts

# Staging  
gozzi build --config config.staging.toml

# Production
gozzi build --config config.prod.toml

Content Organization

# Serve different content sections
gozzi serve --content blog --port 1313     # Blog content
gozzi serve --content docs --port 1314     # Documentation
gozzi serve --content notes --port 1315    # Personal notes

Performance Tips

Build Performance

• Content organization: Keep content in logical subdirectories
• Image optimization: Use optimized images to reduce build time
• Template efficiency: Minimize complex template logic

Development Server Performance

• Selective watching: The server only watches relevant file types
• Debounced rebuilds: Prevents excessive rebuilds during rapid changes
• Incremental builds: Only regenerates what changed

Error Handling

Common error scenarios and solutions:

Config File Issues

# Error: config file not found
gozzi build --config missing.toml
# Solution: Check file path and ensure config exists

# Error: invalid TOML syntax  
# Solution: Validate TOML syntax using online validators

Content Directory Issues

# Error: content directory not found
gozzi build --content missing
# Solution: Create directory or check path

# Error: no content files found
# Solution: Add .md files to content directory

Server Port Issues

# Error: port already in use
gozzi serve --port 1313
# Solution: Use different port or kill existing process
lsof -ti:1313 | xargs kill -9

Next Steps

• Configuration Guide - Learn about config options
• Content Structure - Organize your content
• Templates - Customize your site appearance
• HTML Functions - Use template functions