@stati/cli

The command-line interface for Stati - a minimal, TypeScript-first static site generator that's fast to learn and even faster to build with.

Run your development server, build for production, and manage your site's cache with simple commands.

Getting Started

The Easy Way (Recommended)

If you're new to Stati, start by creating a new site with our scaffolding tool:

npx create-stati my-site

cd my-site
npm run dev

This creates a complete Stati project with the CLI already configured in your package.json.

For Existing Projects

Add Stati CLI to an existing project:

npm install --save-dev @stati/cli

Then add these scripts to your package.json:

{
  "scripts": {
    "dev": "stati dev",
    "build": "stati build",
    "preview": "stati preview"
  }
}

One-Time Usage

Use npx to run Stati commands without installation:

npx @stati/cli dev
npx @stati/cli build
npx @stati/cli preview

Commands

stati dev - Development Server

Start a development server with live reload and instant feedback:

npm run dev
# or
stati dev [options]

What it does:

• Starts a local development server (default: http://localhost:3000)
• Watches your files for changes and rebuilds automatically
• Compiles TypeScript with source maps (when typescript.enabled is true)
• Live reloads your browser when content or templates change
• Shows build errors in an overlay for quick debugging

Options:

• --port <number> - Server port (default: 3000)
• --host <string> - Host address (default: localhost)
• --open - Open browser automatically
• --config <path> - Path to custom config file

Examples:

# Start on default port
npm run dev

# Start on custom port and open browser
stati dev --port 8080 --open

# Use custom config
stati dev --config ./my-config.js

stati build - Production Build

Build your site for production deployment:

npm run build
# or
stati build [options]

What it does:

• Generates static HTML files from your content and templates
• Optimizes output for production
• Uses smart caching to skip unchanged pages (ISG)
• Creates sitemap and robots.txt (if configured)
• Reports build statistics and performance metrics

Options:

• --force - Force full rebuild (keeps cache but rebuilds all pages)
• --clean - Clean cache before building (fresh start)
• --config <path> - Path to custom config file
• --include-drafts - Include draft pages in the build

Examples:

# Standard production build
npm run build

# Clean build (removes cache first)
stati build --clean

# Force rebuild without clearing cache
stati build --force

# Include draft pages
stati build --include-drafts

stati preview - Preview Production Build

Preview your built site locally before deployment:

npm run preview
# or
stati preview [options]

What it does:

• Serves static files from your dist/ directory
• Tests your production build locally
• No live reload or rebuilding (serves files as-is)
• Perfect for final testing before deployment

Options:

• --port <number> - Server port (default: 4000)
• --open - Open browser automatically
• --config <path> - Path to custom config file

Examples:

# Preview on default port
npm run preview

# Preview on custom port and open browser
stati preview --port 8000 --open

stati invalidate - Cache Management

Selectively clear your site's cache to force rebuilds:

stati invalidate [query]

What it does:

• Removes specific pages from the ISG cache
• Forces them to rebuild on next build
• Supports multiple query types for flexible targeting
• Useful for updating related content together

Query Formats:

• tag:value - Invalidate pages with specific tag
• path:value - Invalidate by path (supports prefixes)
• glob:pattern - Invalidate by glob pattern
• age:duration - Invalidate content younger than specified age
• No query - Clear entire cache

Examples:

# Invalidate all blog posts
stati invalidate "tag:blog"

# Invalidate specific path
stati invalidate "path:/posts"

# Invalidate using glob pattern
stati invalidate "glob:/blog/**"

# Invalidate recent content (younger than 3 months)
stati invalidate "age:3months"

# Invalidate week-old content
stati invalidate "age:1week"

# Multiple criteria (OR logic)
stati invalidate "tag:blog age:1month"

# Clear entire cache
stati invalidate

Age Formats:

• age:30days or age:30day - Content younger than 30 days
• age:2weeks or age:2week - Content younger than 2 weeks
• age:6months or age:6month - Content younger than 6 months
• age:1year or age:1years - Content younger than 1 year

Note: Age calculations use exact calendar arithmetic. Months and years account for varying month lengths and leap years.

Quick Start Guide

Creating Your First Site

1. Create a new site:

   npx create-stati my-site

2. Navigate to your project:

   cd my-site

3. Start developing:

   npm run dev

   Your site will be available at http://localhost:3000

4. Make changes:

   • Edit site/index.md for your homepage content
   • Modify site/layout.eta for your HTML structure
   • Update public/styles.css for styling
   • Configure stati.config.js for site settings

5. Build for production:

   npm run build

   Your static site will be in the dist/ directory

6. Preview production build:

   npm run preview

   Test your production build at http://localhost:4000

Common Workflows

Development Workflow

# Start development server
npm run dev

# Edit your content in site/
# Save files and see changes instantly

# When ready, build for production
npm run build

Deployment Workflow

# Clean build for production
npm run build -- --clean

# Test production build locally
npm run preview

# Deploy dist/ folder to your hosting provider
# (Netlify, Vercel, GitHub Pages, etc.)

Cache Management Workflow

# After updating a template that affects blog posts
stati invalidate "tag:blog"

# Rebuild affected pages
npm run build

# Or do a clean build
npm run build -- --clean

Learn More

• Full Documentation - Complete guides and tutorials
• CLI Reference - Detailed command documentation
• Configuration - All configuration options
• Core Concepts - How Stati works
• Examples - Real-world projects

Requirements

• Node.js >=22
• npm 11.5.1 or higher (or equivalent package manager)

Support & Community

• GitHub Issues - Report bugs or request features
• Discussions - Ask questions, share ideas
• Documentation - Comprehensive guides

MIT © Imre Csige