hyalo
A command-line tool for folders of markdown files with front matter.
Many people keep notes, documentation or a knowledge base as a folder of
.md files, for example an Obsidian vault. Each file starts
with YAML front matter: a title, tags, a status. With hundreds of files,
grep and editing by hand reach their limits. hyalo works with the
structure that is already there: front matter, tags,
[[wikilinks]], markdown links and task checkboxes. You
search and change it from the terminal. AI agents such as Claude Code and
Codex use the same commands to keep a knowledge base in order.
What it does
- Search: full-text search ranked by relevance, regular expressions, and filters on front matter, tags, sections and tasks.
- Change: set, remove or append properties and tags, in one file or in hundreds at once.
- Move: rename or move files. hyalo rewrites the supported links to them and reports the cases it cannot handle.
- Fix links: find broken links and repair them.
- Check: lint the front matter against the schemas you define, and fix wrong defaults, typos and date formats.
- Overview: counts of properties, tags and tasks, files nothing links to, and the state of the links.
Many commands that change files can show a preview first (--dry-run).
The output is short text in a terminal and JSON in a pipe. hyalo runs on
macOS, Linux and Windows and needs nothing else installed.
hyalo init --claude sets up Claude Code to use it.
Install
With Homebrew on a Mac with Apple silicon or on Linux. The first line is needed once with Homebrew 6 or newer, which asks you to trust formulae from other taps:
brew trust --formula ractive/tap/hyalo
brew install ractive/tap/hyaloOn Windows with Scoop:
scoop bucket add ractive https://github.com/ractive/scoop-bucket
scoop install hyaloWith Rust's cargo, for example on an Intel Mac. This installs the hyalo command:
cargo install hyalo-cliThe README also lists apt, dnf, the AUR, winget and npm. Ready-made binaries for Linux, macOS on Apple silicon and Windows are on the releases page. In GitHub Actions, the setup-hyalo action installs hyalo, so a workflow can lint a knowledge base on every push.
Example
hyalo find --property status=draft --tag research
This lists the files whose front matter says status: draft
and that have the tag research. hyalo summary
gives an overview of a folder first, and hyalo --help lists
all commands. The settings are explained in the
configuration guide.
Source and licence
hyalo is written in Rust and is open source under the MIT licence. The source is on GitHub. The code was written in whole or in part by AI systems under my supervision (see AI_NOTICE). The name comes from hyaloclastite, a volcanic glass, like obsidian.