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.
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 keeping all links intact, and hyalo lint to enforce schema consistency — all without ever touching raw files or guessing at YAML syntax.
| 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 all [[wikilinks]] and [markdown](links) across the vault |
| 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 |
- Fast. Parallel scanning, streaming I/O, optional snapshot index. Handles 10,000+ file vaults in under a second.
- Structured output. JSON by default with built-in
--jqsupport. Easy to pipe into scripts, CI, or AI agents. - AI-agent friendly. Designed as a tool for Claude Code and other LLM coding agents. One command sets up the integration:
hyalo init --claude. - Safe mutations. Dry-run mode on all write operations. Preview before committing changes.
- Cross-platform. Works on macOS, Linux, and Windows. No runtime dependencies.
# Initialize: point hyalo at the folder that contains your .md files with the --dir flag.
# This is typically a subfolder like docs/, wiki/, or knowledgebase/.
# Omit --dir if the project root itself is the knowledgebase.
hyalo init --dir docs
# Get a bird's-eye view
hyalo summary --format text
# Full-text search (BM25 ranked, with boolean operators)
hyalo find "retry backoff"
hyalo find "retry OR timeout -deprecated"
# Filter by frontmatter
hyalo find --property status=draft --tag research
# Bulk-update metadata
hyalo set --property status=reviewed --where-tag research
# Move a file — all links across the vault are updated
hyalo mv --file old/path.md --to archive/path.md
# Detect and fix broken links
hyalo links fix --apply
# Auto-link unlinked mentions of known page titles
hyalo links auto --apply
hyalo links auto --first-only --exclude-target-glob 'templates/*' --apply
# Lint against your schema
hyalo lint --fixEvery write command supports --dry-run to preview changes before applying them.
Run hyalo --help or hyalo <command> --help for the full reference.
hyalo init --claudeThis installs two skills and a rule that teach Claude Code to use hyalo instead of raw Read/Edit/Grep/Glob when working with your vault:
hyalo skill — Auto-triggered whenever Claude touches markdown files in your vault. It uses hyalo find, hyalo set, hyalo mv, etc. for structured access to frontmatter, tags, links, and tasks.
hyalo-tidy skill (/hyalo-tidy) — A five-phase knowledgebase consolidation. Think of it as a librarian doing a periodic shelf-read: it orients with hyalo summary, gathers recent signal from git history, detects structural issues (broken links, orphan files, stale statuses, missing metadata), applies conservative fixes, and reports a health dashboard. Run it periodically to keep your vault clean.
knowledgebase rule — Scoped to <your-vault>/**. Reminds Claude to prefer hyalo CLI commands over built-in file tools whenever it touches vault files.
All artifacts are idempotent — re-running hyalo init --claude updates to the latest versions. hyalo deinit removes everything cleanly.
brew tap ractive/tap
brew install ractive/tap/hyaloscoop bucket add hyalo https://github.com/ractive/scoop-hyalo
scoop install hyalowinget install ractive.hyalocargo install hyalo-cliPre-built binaries for Linux (x86_64, ARM64, glibc and musl), macOS (Apple Silicon), and Windows (x86_64, ARM64) are available on the GitHub Releases page.
Intel Mac users: Homebrew bottles are only provided for Apple Silicon. Use
cargo installabove.
hyalo init creates a .hyalo.toml in your project root. All fields are optional — CLI flags always take precedence.
dir = "./my-vault" # vault directory (default: ".")
format = "text" # output format: "json" (default) or "text"
hints = false # drill-down command hints (default: true)
default_limit = 100 # max results for list commands (default: 50; 0 = unlimited)
[links]
frontmatter_properties = ["related", "depends-on"] # list properties that contribute to the link graph
case_insensitive = "auto" # "auto", "true", or "false"
[schema.default]
required = ["title"]
[schema.types.iteration]
required = ["title", "date", "status", "tags"]
filename-template = "iterations/iteration-{n}-{slug}.md"
[schema.types.iteration.properties.status]
type = "enum"
values = ["planned", "in-progress", "completed", "superseded"]See hyalo types --help for managing schemas from the CLI, and hyalo lint to validate your vault against them.
Name a filter set once, recall it everywhere:
hyalo views set drafts --property status=draft
hyalo find --view drafts # recall
hyalo find --view drafts --tag rust # extend with additional filtersFor workflows that run many queries in a short window (CI, automation, LLM tool loops):
hyalo create-index # one scan → .hyalo-index
hyalo find --index ... # instant queries, no disk scan
hyalo drop-index # clean upMutations with --index patch the index in-place, keeping it current for subsequent queries.
cargo build --release- Bump the version in
Cargo.toml - Commit:
git commit -am "Bump version to X.Y.Z" - Create a GitHub release with tag
vX.Y.Z
The release workflow handles cross-platform binaries, Homebrew, Scoop, and winget automatically.
MIT — this repository contains code generated in whole or in part by AI systems under human supervision. See AI_NOTICE for details.
"Hyalo" — from hyaloclastite — is a volcanic glass, just like obsidian.