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 --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 -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 -i /path/to/my-site
hwaro serve -i /path/to/my-site -p 8080

Options:

The server watches for file changes and rebuilds automatically.

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 check                # Check for dead external links

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

# 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

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

Global Options