CLI

Hwaro provides commands for creating, building, and serving your site.

Global flags

These flags work with every top-level command and control how the CLI writes to the terminal. They are especially useful for scripts, CI logs, and AI agents that want clean output.

Colors are also disabled automatically when stdout is not a TTY (for example when piping to cat, redirecting to a file, or running inside most CI systems). Set NO_COLOR=1 to force-disable color everywhere; no extra flag is needed.

# Silent build for scripts and CI — only warnings/errors surface.
hwaro build --quiet

# Plain ASCII (no ANSI escapes) even when stdout is a TTY.
NO_COLOR=1 hwaro doctor

Error taxonomy

Classified failure paths emit a stable error code plus a matching process exit code so scripts, CI, and agents can branch reliably without parsing human messages.

In text mode the error line is prefixed with the code:

Error [HWARO_E_USAGE]: missing <path> argument

Under --json (or --quiet) the classified error is emitted as a structured payload on stdout:

{
  "status": "error",
  "error": {
    "code": "HWARO_E_USAGE",
    "category": "usage",
    "message": "missing <path> argument",
    "hint": "Usage: hwaro new <path> [options] — run 'hwaro new --help' for details."
  }
}

Unclassified failures keep the legacy Error: <message> format and exit code 1, so this is a strictly additive contract.

Commands

init

Create a new site:

hwaro init my-site
hwaro init my-site --scaffold blog
hwaro init my-site --scaffold docs
hwaro init my-site --scaffold book

You can also use a remote scaffold from a GitHub repository:

# GitHub shorthand
hwaro init my-site --scaffold github:user/repo
hwaro init my-site --scaffold github:user/repo/docs

# Full URL
hwaro init my-site --scaffold https://github.com/user/repo
hwaro init my-site --scaffold https://github.com/user/repo/tree/main/docs

Remote scaffolds fetch config.toml, templates/, static/, and content structure from the repository. Content files keep only front matter (metadata) so you can see the expected page structure without the original body text. Set GITHUB_TOKEN environment variable to avoid API rate limits.

Options:

new

Create a new content file:

hwaro new content/about.md
hwaro new content/blog/my-post.md
hwaro new -t "My Post Title"
hwaro new posts/my-post.md -a posts
hwaro new my-post.md --section blog --draft --tags "go,web" --date 2026-03-22

Creates a Markdown file with front matter template. Supports archetypes for customizable templates.

Options:

Archetypes:

Archetypes are template files in archetypes/ directory that define default front matter for new content:

• archetypes/default.md - Default template for all content
• archetypes/posts.md - Used for hwaro new posts/...
• archetypes/tools/develop.md - Used for hwaro new tools/develop/...

Archetype files support placeholders: {{ title }}, {{ date }}, {{ draft }}, {{ tags }}

Example archetype (archetypes/posts.md):

---
title: "{{ title }}"
date: {{ date }}
draft: false
tags: []
---

# {{ title }}

Archetype matching priority:

1. Explicit -a flag (e.g., -a posts uses archetypes/posts.md)
2. Path-based matching (e.g., posts/hello.md checks archetypes/posts.md)
3. Nested paths try parent archetypes (e.g., tools/dev/x.md tries tools/dev.md, then tools.md)
4. Falls back to archetypes/default.md
5. Uses built-in template if no archetype found

build

Build the site to public/:

hwaro build
hwaro build --drafts
hwaro build --minify
hwaro build -i /path/to/my-site
hwaro build -i /path/to/my-site -o ./dist

Options:

About --stream / --memory-limit (Streaming Build):

For sites with thousands of pages, loading all rendered HTML into memory at once can cause high memory usage. Streaming build processes pages in batches during the Render phase, releasing rendered HTML after each batch is written to disk.

• --stream enables streaming with a default batch size of 50 pages.
• --memory-limit SIZE enables streaming and calculates the batch size automatically based on the given limit (heuristic: ~50KB per page). Accepts G, M, K suffixes (e.g. 2G, 512M, 256K).
• You can also set the HWARO_MEMORYLIMIT environment variable as a fallback. The CLI flag overrides the env var.

The build output is identical — streaming only affects memory usage during the build.

About --minify:

The minify flag shrinks generated files while keeping them visually identical to the un-minified output:

• HTML: Removes comments (preserves conditional comments, SSI directives, <!-- more -->), strips trailing whitespace, collapses intra-tag whitespace (runs between attributes shrink to one space, quoted attribute values stay untouched), and collapses inter-tag whitespace by neighbour classification. If either neighbour is a block-level element the whitespace is stripped entirely (browsers collapse whitespace at the start, end, or between block siblings anyway); only when both neighbours are inline is a single space kept so the visible gap of <a>x</a> <a>y</a> is preserved.
• JSON: Removes whitespace and newlines for compact output.
• XML: Removes whitespace between tags for smaller file sizes.

Whitespace-sensitive elements — <pre>, <code>, <textarea>, <script>, <style>, <svg>, <math>, <noscript> — are extracted before any whitespace pass and restored verbatim, so their contents are never touched.

For more aggressive output shrinking (attribute quoting, entity collapsing, etc.) post-process public/ with a dedicated tool such as html-minifier-terser or minify-html.

About --cache (Incremental Build):

When enabled, Hwaro tracks file modification times and content checksums in a .hwaro_cache.json file at the project root. On subsequent builds, only files that have changed since the last build are re-rendered. The cache also tracks template and config checksums — if templates or config.toml change, all entries are automatically invalidated and every page is rebuilt.

Use --full together with --cache to force a clean rebuild while still saving the cache for the next run:

hwaro build --cache --full

See Incremental Build for details.

About -i, --input:

When specified, Hwaro changes its working directory to the given path before building. This lets you build a site located in another directory without cd-ing into it first.

• All site sources (config.toml, content/, templates/, static/) are read from the input directory.
• Without -o: The default output directory public/ is created inside the input directory (i.e., the site's own public/ folder). This is the natural behavior — hwaro build -i ../my-site produces ../my-site/public/.
• With -o: The output path is resolved relative to your current directory (not the input directory), so hwaro build -i ../my-site -o ./dist writes output to ./dist in your shell's CWD.
• If -i is omitted, behavior is unchanged — the current directory is used.

serve

Start a development server with live reload (enabled by default):

hwaro serve
hwaro serve --port 8080
hwaro serve --open
hwaro serve --access-log
hwaro serve --no-live-reload
hwaro serve -i /path/to/my-site
hwaro serve -i /path/to/my-site -p 8080

Options:

Fast dev server on large sites: Set [og.auto_image] lazy_generate = true in config.toml to skip bulk OG generation during hwaro serve. Images are created on first request instead. See the Performance in Development section for the full explanation and recommended workflow with --fast-start.

The server watches for file changes and rebuilds automatically. It uses smart rebuild strategies based on what changed:

About live reload:

Live reload is enabled by default. The server injects a small WebSocket client script into every HTML response, and after each successful rebuild, connected browsers automatically refresh the page — no manual reload needed. The client uses exponential backoff (1s–30s) for reconnection, so restarting the server won't break the connection permanently.

Pass --no-live-reload to disable this behaviour (useful for testing production-like delivery locally). The --live-reload flag is kept as a no-op alias for backwards compatibility with existing invocations.

When -i is specified, the server operates as if you had cd-ed into the given directory — watching and serving from that project root.

Custom response headers (--header / [serve.headers]):

Use this to reproduce headers that your production reverse-proxy, CDN, or static hosting sets (security headers, Cache-Control, custom CORS, etc.) so you can test locally before deploying the static output.

[serve.headers]
X-Frame-Options = "SAMEORIGIN"
X-Content-Type-Options = "nosniff"
Referrer-Policy = "strict-origin-when-cross-origin"
# Cache-Control = "public, max-age=3600"

hwaro serve --header "X-Custom: foo" --header "Cache-Control: no-store"

• CLI --header values win over the same key in config.toml.
• Headers are injected on every dev-server response (HTML, assets, 404s, redirects, live-reload injected pages).
• This feature only affects hwaro serve. The files written to public/ are untouched.

deploy

Deploy the generated site to configured targets.

hwaro deploy [target ...]
hwaro deploy --dry-run

Options:

doctor

Diagnose config, template, and structure issues (top-level shortcut):

hwaro doctor               # Diagnose config, template, and structure issues
hwaro doctor --fix         # Add missing config sections to config.toml

Exit codes. doctor returns a classified exit code based on the most severe issue reported, so CI pipelines can gate on it directly:

Warnings (empty base_url, trailing slash, duplicate taxonomy names, etc.) are advisory and never change the exit code.

For content validation, use hwaro tool validate. See doctor for details.

tool

Utility tools for content management:

# Content tools
hwaro tool list all             # List all content files
hwaro tool list drafts          # List draft files
hwaro tool convert to-yaml      # Convert frontmatter to YAML
hwaro tool convert to-toml      # Convert frontmatter to TOML
hwaro tool convert to-json      # Convert frontmatter to JSON
hwaro tool check-links          # Check for dead external links
hwaro tool stats                # Show content statistics
hwaro tool validate             # Validate content frontmatter and markup
hwaro tool unused-assets        # Find unreferenced static files

# Site tools
hwaro tool platform netlify       # Generate Netlify config
hwaro tool platform vercel        # Generate Vercel config
hwaro tool platform cloudflare    # Generate Cloudflare Pages config
hwaro tool platform github-pages  # Generate GitHub Pages deploy workflow
hwaro tool platform gitlab-ci     # Generate GitLab CI config
hwaro tool platform codeberg-pages # Generate Codeberg Pages (Forgejo Actions) workflow
hwaro tool doctor                 # Diagnose config/template/structure issues
hwaro tool import hugo /path      # Import from Hugo
hwaro tool import jekyll /path    # Import from Jekyll
hwaro tool export hugo            # Export to Hugo format
hwaro tool export jekyll          # Export to Jekyll format
hwaro tool agents-md --write      # Write AGENTS.md to file

# JSON output
hwaro tool list all --json
hwaro tool stats --json
hwaro tool validate --json
hwaro tool unused-assets --json
hwaro tool doctor --json
hwaro tool check-links --json

Subcommands:

Common Options:

See Tools & Completion for detailed usage.

completion

Generate shell completion scripts:

hwaro completion bash    # Bash completion script
hwaro completion zsh     # Zsh completion script
hwaro completion fish    # Fish completion script

Installation:

# Bash (add to ~/.bashrc)
eval "$(hwaro completion bash)"

# Zsh (add to ~/.zshrc)
eval "$(hwaro completion zsh)"

# Fish (add to ~/.config/fish/config.fish)
hwaro completion fish | source

See Tools & Completion for detailed installation instructions.

Examples

# Development workflow
hwaro serve --drafts --verbose

# Development with HTTP access log
hwaro serve --access-log

# Development without live reload (production-like serving)
hwaro serve --no-live-reload

# Production build
hwaro build

# Custom output directory
hwaro build -o dist

# Preview on specific port
hwaro serve -p 8000 --open

# Build a site in another directory
hwaro build -i ~/projects/my-blog

# Build a remote project and output to current directory
hwaro build -i ~/projects/my-blog -o ./output

# Incremental build (skip unchanged files)
hwaro build --cache

# Force full rebuild and repopulate cache
hwaro build --cache --full

# Streaming build for large sites
hwaro build --stream
hwaro build --memory-limit 512M

# Streaming build with env var
HWARO_MEMORYLIMIT=1G hwaro build

# Serve a site from another directory
hwaro serve -i ~/projects/my-blog --open

Global Options

See Also

• Configuration — Config options that CLI flags override
• Build Hooks — Pre/post build commands
• Tools & Completion — Utility subcommands