● meerkat · knows
meerkat — CLI & integrations
The full mk command surface, plus how to expose the knowledge base to agents over MCP and to web tools over HTTP.
The CLI
Every subcommand works under both meerkat and mk. Page IDs are slash-paths from the wiki root without the .md extension (e.g. concepts/Rate-Limiting).
| Command | Description | Example |
|---|---|---|
search | Full-text BM25 search over the served wiki. | mk search "rate limiting" --limit 20 |
show | Print a single wiki page (raw markdown). | mk show concepts/Rate-Limiting |
list | List pages, filtered by prefix/category/status/owner/type. | mk list --prefix systems/backend/ |
mcp serve | Run the MCP server over stdio. | mk mcp serve |
http serve | Run the HTTP/OpenAPI server with bearer auth. | mk http serve --port 4004 |
ingest | Plan (and with --execute, run) ingestion. | mk ingest --source policies --execute |
ingest sources | Print the ingestion source registry. | mk ingest sources --json |
update | Check for / install meerkat updates. | mk update --check |
version | Print version info and content provenance. | mk version --json |
Global flags
These apply to every subcommand and select which knowledge base is served. They are resolved once, before the subcommand runs.
| Flag | Effect |
|---|---|
--kb-dir string | Serve content from a directory in the content-repo layout. Wins over everything else. |
--content-source string | Path to a content-source.yaml. A nonexistent path is a hard error. |
Search flags
| Flag | Effect |
|---|---|
--limit int | Max hits (default 10, server-clamped to 100). |
--body | Print the full body of each hit. |
--json | Machine-readable output. |
mk search "exact phrase" # phrase match
mk search +cache -queue # must / must-not
mk search title:eviction # field-targetedList filters
Filters compose with AND, and are applied to frontmatter after loading — they are not query terms.
| Flag | Effect |
|---|---|
--prefix string | Page IDs starting with this prefix. |
--category string | Frontmatter category. |
--status string | Frontmatter status. Free string — meerkat and OKF vocabularies both pass through untranslated. |
--owner string | Frontmatter owner. |
--type string | Frontmatter type — OKF's concept-kind field, e.g. "BigQuery Table". |
show --json carries trust metadata
mk show <id> --json returns trust_tier and stale as top-level siblings of front — not fields inside it. Both are computed on read, never stored. See OKF bundles.
OpenCode (MCP over stdio)
Register meerkat as a local MCP server and your agent gains three tools on every prompt — mk_search, mk_show, and mk_list.
{
"mcp": {
"meerkat": {
"type": "local",
"command": ["mk", "mcp", "serve"],
"enabled": true
}
}
}Search, then show
The recommended agent pattern is mk_search first (the snippet triages which page), then mk_show on the winner — it keeps the context window lean.
| Tool | Parameters | Returns |
|---|---|---|
mk_search | query (required), limit | id, title, category, status, score, snippet |
mk_show | id (required) | id, path, title, body, front, trust_tier, stale |
mk_list | prefix, category, status, owner, type | id, title, category, status, owner, type, source |
All three are annotated read-only, idempotent, and closed-world, so a harness can call them without a confirmation prompt.
OpenWebUI (HTTP / OpenAPI)
Serve the knowledge base over HTTP with a bearer token, then point OpenWebUI at the OpenAPI schema. The default bind is loopback.
export MEERKAT_API_KEY=$(openssl rand -hex 32)
mk http serve --port 4004 # binds 127.0.0.1 by default
curl -sS http://127.0.0.1:4004/healthz| Method | Path | Auth |
|---|---|---|
| POST | /search | Bearer |
| POST | /show | Bearer |
| POST | /list | Bearer |
| GET | /openapi.json | none |
| GET | /healthz | none |
| GET | / | none |
Auth is deny-by-default: anything not explicitly public requires the bearer token, so an unmatched path returns 401 rather than 404. The server refuses to start without a key (no anonymous mode); the key is compared in constant time. /healthz and /openapi.json are exempt so probes and tool registration work without it.
Put a reverse proxy in front of it
meerkat serves plain HTTP and terminates no TLS of its own. To reach it from another host, front it with a reverse proxy that terminates TLS rather than binding it to 0.0.0.0 directly.
POST /list accepts the same type filter as the CLI, and POST /show returns trust_tier and stale alongside the page. POST /search is unchanged.
Environment variables
| Variable | Effect |
|---|---|
MEERKAT_KB_DIR | Content directory to serve (the --kb-dir flag wins over it). |
MEERKAT_CONTENT_SOURCE | Path to a content-source.yaml (the --content-source flag wins over it). |
MEERKAT_API_KEY | Bearer token for mk http serve (env wins over --api-key). |
MEERKAT_NO_UPDATE_CHECK=1 | Silence the post-run "newer release available" check. |
Authoritative reference, generated from the component repos. Spot something stale? Tell us.