CLI Reference

The taxus binary provides five subcommands for building and managing static sites.

Global Usage

taxus <SUBCOMMAND> [OPTIONS]

taxus build

Build the static site from Markdown content and templates.

taxus build [OPTIONS]

Options:
  -d, --dir <PATH>         Root directory (must contain site.toml) [default: .]
  -v, --verbose            Print detailed progress for each build stage
  -q, --quiet              Suppress all output except errors
      --include-drafts     Include pages marked draft = true
      --dry-run            Simulate without writing files
      --clean              Remove output directory before building
  -o, --output <PATH>      Override the output directory from site.toml
  -h, --help               Print help

Examples

# Build from current directory
taxus build

# Build with verbose output
taxus build --verbose

# Build from a specific directory
taxus build --dir ./my-site

# Build including drafts
taxus build --include-drafts

# Dry run (validate without writing)
taxus build --dry-run

# Clean and rebuild
taxus build --clean

# Override output directory
taxus build --output /tmp/preview

Build Pipeline Stages

1. Discover routes from content/
2. Load Tera templates from templates/
3. Parse Markdown + frontmatter
4. Copy co-located assets
5. Render pages with templates
6. Generate robots.txt
7. Generate sitemap.xml
8. Generate 404.html
9. Build and render taxonomy pages
10. Generate feeds (RSS/Atom)
11. Process assets (SCSS, static files)
12. Generate search index
13. Write WASM client
14. Write output files

taxus clean

Remove all generated files from the output directory.

taxus clean [OPTIONS]

Options:
  -d, --dir <PATH>   Root directory (must contain site.toml) [default: .]
  -h, --help         Print help

Examples

# Clean current site
taxus clean

# Clean a site in a different directory
taxus clean --dir ./my-site

taxus init

Initialize a new site with a default directory structure.

taxus init [OPTIONS] [PATH]

Arguments:
  [PATH]               Directory to initialize [default: .]

Options:
  -n, --name <NAME>       Site name used in templates and site.toml
  -u, --base-url <URL>    Base URL (must start with http:// or https://)
  -f, --force             Initialize even if directory is not empty
      --no-islands        Disable WASM islands hydration (enabled by default)
  -h, --help              Print help

Files Created

Examples

# Initialize in current directory
taxus init

# Initialize in a new directory
taxus init my-site

# Initialize with custom options
taxus init my-site --name "My Blog" --base-url "https://myblog.com"

# Initialize a plain site without islands
taxus init my-site --no-islands

# Force initialization in non-empty directory
taxus init my-site --force

taxus routes

List all routes that would be discovered from the content directory without building.

taxus routes [OPTIONS]

Options:
  -d, --dir <PATH>   Root directory (must contain site.toml) [default: .]
  -h, --help         Print help

Example Output

Routes for "My Site"
────────────────────────────────────────────────────
  [section]  /          →  _index.md            →  index.html
  [page]     /about/    →  about.md             →  about/index.html
  [section]  /blog/     →  blog/_index.md       →  blog/index.html
  [page]     /blog/post/ → blog/post.md         →  blog/post/index.html
────────────────────────────────────────────────────
  Total: 4 routes (2 pages, 2 sections)

Examples

# List routes for current site
taxus routes

# List routes for a specific site
taxus routes --dir ./my-site

taxus serve

Start a development server with live reload.

taxus serve [OPTIONS] [DIR]

Arguments:
  [DIR]               Root directory (must contain site.toml) [default: .]

Options:
  -p, --port <PORT>   Port to listen on [default: 3000]
  -v, --verbose       Print detailed progress for each build stage
  -q, --quiet         Suppress all output except errors
  -o, --open          Open browser automatically
  -h, --help          Print help

The serve command performs an initial build automatically, then watches for file changes.

Examples

# Start on default port
taxus serve

# Start with custom port
taxus serve --port 8080

# Start and open browser
taxus serve --open

# Serve from specific directory
taxus serve ./my-site

# Combined options
taxus serve ./my-site --port 8080 --open --verbose

Error Hints

When a command fails, the CLI prints an actionable hint alongside the error:

Logging

Control log output with CLI flags or the RUST_LOG environment variable:

# Default: info level (build progress)
taxus build

# Verbose: debug level (detailed stages)
taxus build --verbose

# Quiet: errors only
taxus build --quiet

# Custom via RUST_LOG
RUST_LOG=debug taxus build
RUST_LOG=taxus_lib=trace taxus build

Log levels: