hyalo
A structured CLI for markdown knowledgebases — built for humans and AI agents.
If you maintain an Obsidian vault, a Zettelkasten, documentation site, or any folder of .md files with YAML frontmatter, you've probably hit the limits of grep and manual editing. Hyalo gives you a fast, structured way to search, filter, and bulk-edit your markdown files from the command line.
Hyalo does not define how you organize your notes. It works with the structure you already have — frontmatter properties, tags, [[wikilinks]], markdown links, task checkboxes — and gives you powerful tools to query and maintain it at scale.
The LLM Wiki pattern
Andrej Karpathy popularized the idea of an LLM-maintained wiki: instead of asking an LLM the same questions repeatedly, you have it build and maintain a persistent, structured knowledgebase that compounds over time. Every source ingested, every question answered adds to the wiki rather than vanishing with the conversation.
Hyalo is the tooling layer that makes this practical. An LLM agent can use hyalo find to search across thousands of notes by metadata, full-text, or regex. It can use hyalo set to bulk-update frontmatter, hyalo mv to reorganize files while reporting any ambiguous or unsupported link rewrites, and hyalo lint to enforce schema consistency — without guessing at YAML syntax.
What it does
| | | |---|---| | Search | Full-text search with BM25 ranking, regex, frontmatter filters, tag/section/task queries | | Mutate | Set, remove, or append to properties and tags — one file or hundreds at once | | Move | Rename or reorganize files; hyalo rewrites supported links and reports ambiguous or unsupported cases | | Fix links | Detect broken links and auto-repair them with fuzzy matching | | Validate | Lint frontmatter against type schemas, auto-fix defaults, typos, and date formats | | Overview | Property/tag distributions, task counts, orphan files, link health at a glance |
Why hyalo?
- Fast. Parallel scanning, streaming I/O, optional snapshot index. Handles 10,000+ file vaults in under a second.
- Structured output. TTY-aware: compact text for terminals, json when piped — with built-in --jq support. Easy to pipe into scripts, CI, or AI agents.
- AI-agent friendly. Integrates with Claude Code, Codex, and Pi. Set up project workflows with hyalo init --claude, hyalo init --codex, or hyalo init --pi; Codex and Pi also have installable packages.
- Safe mutations. Bulk repairs, moves, generators, and link rewrites provide documented preview modes. Check hyalo <cmd --help for the exact command contract.
- Cross-platform. Works on macOS, Linux, and Windows. No runtime dependencies.
Installation
Homebrew (macOS & Linux)
brew trust --formula ractive/tap/hyalo # Homebrew 6+: third-party taps need one-time trust
brew install ractive/tap/hyaloCovers macOS (Apple Silicon) and Linux (x8664 and ARM64). The Linux binaries are statically linked against musl, so they have no glibc dependency.
Homebrew 6 introduced tap trust: formulae from third-party taps refuse to load until trusted. brew trust --formula scopes the trust to just this formula; brew trust ractive/tap trusts the whole tap instead.
apt (Debian & Ubuntu)
curl -sLf 'https://dl.cloudsmith.io/public/ractive/hyalo/cfg/setup/bash.deb.sh' | sudo bash
sudo apt install hyalo