CLI

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

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 performs conservative optimization on generated files:

• HTML: Removes comments and trailing whitespace, collapses excessive blank lines. Preserves all indentation, newlines, and content structure.
• JSON: Removes whitespace and newlines for compact output.
• XML: Removes whitespace between tags for smaller file sizes.

Code blocks (<pre>, <code>) and script/style content are always preserved intact.

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:

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

Options:

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

About --live-reload:

When enabled, the server injects a small WebSocket client script into every HTML response. 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.

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

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

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 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 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 with auto browser refresh
hwaro serve --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