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

The numbers match the [n/15] lines in the build log. Each stage is described in Architecture.

Discover routes: build the Site Tree from content/ and derive the routes from it
Load Tera templates from templates/
Process content: render Markdown to HTML, resolve @/ links
Process hero images (responsive variants, WebP conversion, srcset)
Copy co-located assets
Render pages with templates
Generate robots.txt
Generate sitemap.xml
Generate 404.html
Build and render taxonomy pages
Generate feeds (RSS/Atom)
Process assets (SCSS, static files)
Generate search index
Write WASM client
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

File	Description
`site.toml`	Site configuration
`content/_index.md`	Home page content
`templates/base.html`	Base HTML layout
`templates/page.html`	Single-page template
`templates/section.html`	Section/listing template
`templates/tags.html`	Tag listing page
`templates/tags_term.html`	Individual tag page
`templates/categories.html`	Category listing page
`templates/categories_term.html`	Individual category page
`templates/series.html`	Series listing page
`templates/series_term.html`	Individual series page
`templates/404.html`	Not-found page
`styles/main.scss`	Starter stylesheet
`styles/_highlight-dark.scss`, `styles/_highlight-light.scss`	Code highlighting theme partials
`static/scripts.js`	Placeholder scripts file
`static/favicon.png`	Placeholder favicon

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 are listed sorted by URL path, with the content file and the output file in the next two columns. This is the product site in the repository, get-taxus-org/:

Routes for "Taxus"
─────────────────────────────────────────────────────
  [section]  /                             _index.md                       index.html
  [section]  /appearance/                  appearance/_index.md            appearance/index.html
  [section]  /authoring/                   authoring/_index.md             authoring/index.html
  [section]  /blog/                        blog/_index.md                  blog/index.html
  [page   ]  /blog/project-launch/         blog/2026-04-03-project-launch.md  blog/project-launch/index.html
  ...
  [section]  /structure/                   structure/_index.md             structure/index.html
─────────────────────────────────────────────────────
  Total: 11 routes (5 pages, 6 sections)

The URL paths are the served addresses, derived from the Site Tree: the date prefix on the post's file name is not in its URL. See Identity.

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]

Options:
  -d, --dir <PATH>        Root directory (must contain site.toml) [default: .]
      --host <ADDR>       IP address to bind to [default: 127.0.0.1]
  -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
      --include-drafts    Include draft pages in every rebuild
  -h, --help              Print help

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

By default the server listens on 127.0.0.1 only, so nothing on your network can reach it. Pass --host 0.0.0.0 (or :: for IPv6) to expose it — for example, to test the site on a phone. See Development Server for details.

Examples

# Start on default port
taxus serve

# Start with custom port
taxus serve --port 8080

# Expose on the local network (e.g. to test on a phone)
taxus serve --host 0.0.0.0

# Start and open browser
taxus serve --open

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

# Preview drafts (rebuilds include them until restarted)
taxus serve --dir ./my-site --include-drafts

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

Error Hints

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

Error	Hint
`site.toml` not found	Run `taxus init` or use `--dir`
No content found	Add `.md` files to `content/`, start with `content/_index.md`
Template not found	Check that `templates/` contains `base.html` and `page.html`

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:

Level	Description
`error`	Build failures only
`warn`	Warnings and errors
`info`	Build progress (default)
`debug`	Detailed stage information
`trace`	Verbose internal diagnostics

Taxus Documentation