CLI · read

okf catalog

What's here, in detail.

When to use it

To enumerate a bundle with full metadata: the "what's here, in detail" view, one line of context per concept.
To answer filtered questions without a browser: okf catalog docs/ --tag auth is "what carries the auth tag?", answered on the CLI.
As an agent's substrate for choosing what to read next, after okf index has provided the map and okf stats the size.

How it works

catalog prints every concept with its metadata (type, status, tags, timestamp, in and out link degree, description), grouped by top-level directory. It reproduces the browser server's Catalog panel on the CLI, sharing one data source with okf files, okf tags, okf types, and okf stats: per-concept metadata plus link degree. It is an advisory read and always exits 0.

The view narrows with the same filters the browser offers: --type TYPE, --dir PATH, --tag TAG, combinable. Matching is case-insensitive and exact, and --dir reaches every directory below the one you name. A concept at the bundle root lives in the (root) directory, which --dir also accepts as plain root, no shell quoting needed; since 1.13.0 a real directory named root/ owns that name instead, so it stays reachable. The deprecated --area still works over the first path segment.

Try it

okf catalog docs/ --tag chat

Catalog - docs (3 of 37 concepts)

  features/ (3)
    Chat threads  ·  Feature  ·  ↳9
      How a conversation thread is stored, trimmed, and replayed.
    Source ingestion pipeline  ·  Feature  ·  ↳12
      Turns an uploaded source into chat-ready chunks.
    Streaming responses  ·  Feature  ·  ↳4
      Why responses stream token by token and what the client contract is.

For a machine, okf catalog docs/ --json emits { bundle, count, concepts: [{ id, title, type, description, tags, timestamp, status, backlog_ref, dir, top_dir, links_out, links_in }] } as compact single-line JSON (dir is the full path, top_dir the first-segment rollup renamed from area in 1.12.0). --fields / --except project each concept down to the properties you will read, e.g. --fields id,title,links_in for a ranked reading list.

Pitfalls

Filters are case-insensitive but exact. --type feature matches Feature; --type feat matches nothing. There is no substring or glob matching.
A filter that matches nothing is an empty view, not an error. The exit code stays 0 and count is 0; do not read an empty catalog as a broken bundle.
--fields and --except are mutually exclusive, and an unknown field name is a usage error (exit 2) that lists the valid ones. Both imply --json.
Reserved files never appear. index.md and log.md are structure, not concepts; see okf index for that layer.