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

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

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 }}

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:

When enabled, Hwaro tracks file modification times in a .hwaro_cache.json file at the project root. On subsequent builds, only files that have changed since the last build are re-processed. The cache uses millisecond-precision mtime comparison and also verifies that the output file still exists. Use hwaro build --cache to enable, or set cache = true in [build] config.

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:

tool

Utility tools for content management:

hwaro tool convert toYAML       # Convert frontmatter to YAML
hwaro tool convert toTOML       # Convert frontmatter to TOML
hwaro tool list all             # List all content files
hwaro tool list drafts          # List draft files
hwaro tool list published       # List published files
hwaro tool deadlink             # Check for dead external links
hwaro tool doctor               # Diagnose config and content issues

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

# 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