Tools & Completion

Hwaro includes utility tools for content management and shell completion scripts for a better CLI experience.

Tool Commands

The hwaro tool command provides utility subcommands for working with content files.

convert — Frontmatter Converter

Convert frontmatter between YAML and TOML formats across your content files.

# Convert all frontmatter to YAML
hwaro tool convert toYAML

# Convert all frontmatter to TOML
hwaro tool convert toTOML

# Convert only in a specific directory
hwaro tool convert toYAML -c posts

Options:

Flag	Description
-c, --content DIR	Limit conversion to a specific content directory
-h, --help	Show help

Example — TOML to YAML:

Before:

+++
title = "My Post"
date = "2024-01-15"
tags = ["crystal", "tutorial"]
+++

Content here.

After hwaro tool convert toYAML:

---
title: "My Post"
date: "2024-01-15"
tags:
  - crystal
  - tutorial
---

Content here.

list — Content Lister

List content files filtered by status.

# List all content files
hwaro tool list all

# List only draft files
hwaro tool list drafts

# List only published files
hwaro tool list published

# List files in a specific directory
hwaro tool list all -c posts

Options:

Flag	Description
-c, --content DIR	Limit listing to a specific content directory
-h, --help	Show help

Filters:

Filter	Description
all	Show all content files
drafts	Show only files with `draft = true`
published	Show only files with `draft = false` or no draft field

check — Dead Link Checker

Check for broken external links in your content files.

hwaro tool check

This command:

Scans all Markdown files in the content/ directory
Finds external URLs (http/https links)
Sends concurrent HEAD requests to each URL
Reports broken or unreachable links

Example output:

Checking links in content/...
Found 42 external links in 15 files

✓ https://example.com (200)
✓ https://crystal-lang.org (200)
✗ https://old-site.com/page (404)
✗ https://broken-link.invalid (Connection refused)

Results: 40 OK, 2 broken

Shell Completion

Hwaro can generate completion scripts for your shell, providing tab completion for commands, subcommands, and flags.

Supported Shells

Shell	Command
Bash	`hwaro completion bash`
Zsh	`hwaro completion zsh`
Fish	`hwaro completion fish`

Installation

Bash

Add to your ~/.bashrc:

eval "$(hwaro completion bash)"

Or save to a file:

hwaro completion bash > /etc/bash_completion.d/hwaro

Zsh

Add to your ~/.zshrc:

eval "$(hwaro completion zsh)"

Or save to your fpath:

hwaro completion zsh > ~/.zsh/completions/_hwaro

Fish

Add to your ~/.config/fish/config.fish:

hwaro completion fish | source

Or save to the completions directory:

hwaro completion fish > ~/.config/fish/completions/hwaro.fish

What Gets Completed

The completion scripts provide tab completion for:

Commands: hwaro <TAB> → init, build, serve, new, deploy, tool, completion
Subcommands: hwaro tool <TAB> → convert, list, check
Flags: hwaro build <TAB> → --output-dir, --drafts, --minify, etc.
Positional arguments: hwaro completion <TAB> → bash, zsh, fish
Positional choices: hwaro tool convert <TAB> → toYAML, toTOML

Automatic Updates

Completion scripts are generated dynamically from command metadata. When you update Hwaro to a new version with new commands or flags, regenerating the completion script will automatically include them.

# Regenerate after updating hwaro
eval "$(hwaro completion bash)"