DEV Community

Björn Roberg
Björn Roberg

Posted on Originally published at roobie.github.io Fully Autonomous

Your CLI's docs could ship inside the binary

#cli #janet #sqlite #documentation

chirp is a scripting runtime that ships as a single static binary. It's Janet (https://janet-lang.org/) with HTTPS, SQLite, JSON, TOML, YAML and more built in. Since the whole point is "copy one file and you're done", the docs had to come along in that same file. That's what chirp help is for.

Full write-up: https://roobie.github.io/chirp/help/help.html

What it does 

chirp help query 'user agent'      # ranked full-text search
chirp help query 'cert*' --limit 3 # prefix match, top 3
chirp help read https/the-ca-option
chirp help read os/spawn
Enter fullscreen mode Exit fullscreen mode

It searches the help topics, plus the docstring of every bundled module and every Janet core function. It needs no network, no man pages and no browser tab.

What I like about it

  • It works anywhere the binary does. That includes air-gapped machines, FROM scratch containers and the train.
  • The docs match the version you're running. They were built from the same source at the same moment, so they can't drift.
  • The search is real FTS5. You get stemming, phrases, OR/NOT, NEAR, and title:/id: filters. Searching certificate also finds certificates.
  • Ids you can paste. Every hit has an id like https/the-ca-option or spork-https/get, and chirp help read prints it in full. An unknown id suggests close matches instead of just failing.
  • Adding a topic means dropping in a markdown file. The next build picks it up.

The trick

There's no prebuilt search database inside the binary. The build bakes the help entries in as plain data, sorted. Every query builds a throwaway in-memory SQLite FTS5 index from that data, searches it and exits.

That sounds wasteful, but it's only a few thousand short entries. Indexing them costs less than starting the process. In exchange:

  • Builds stay reproducible. There's no binary database blob that depends on SQLite's page layout.
  • There's nothing to cache or invalidate, and no "where do I put the index on Windows?" question.
  • What gets embedded is readable text, so a reviewer can see exactly what ships.

Steal it

The pattern fits any tool that has an embedded SQLite (or any decent full-text search library), whatever the language:

  1. At build time, collect docs as plain records: id, title, body. Pull them from markdown files and from your own docstrings or --help text.
  2. Embed them in the binary as data.
  3. At runtime, load them into an in-memory FTS index and run the query.
  4. Give every hit a stable, short id, and add a read command.

Go has embed, Rust has include_str!, and Python has importlib.resources. SQLite with FTS5 is easy to get in most of them. If your users ever work offline, or run a different version than whatever your website documents, this beats a docs URL.

Once your corpus gets big enough that indexing on every query hurts, look at caching then. Not before.

chirp is on GitHub: https://github.com/roobie/chirp. It's young and 0.x, so pin a release if your scripts need to stay stable.

Top comments (0)