CLI · read

okf tags

What themes dominate, and where.

When to use it

To find the thematic clusters in a bundle: the tags with the highest counts are the themes the bundle keeps returning to.
To curate the tag vocabulary. --by type or --by dir shows where each tag lives, which separates connective tags from scattered one-offs.
To answer scoped questions: okf tags docs/ --dir billing --json is "which tags does the billing directory use?".

How it works

tags prints every tag with the concepts that carry it, ordered by count descending. It reproduces the browser server's Tags panel on the CLI, over the same data source as okf catalog and the other read views. Advisory read, always exit 0.

--by type or --by dir regroups the list per concept dimension with within-group counts; a tag spanning several groups appears in each. --by dir cuts by the whole directory path (the deprecated --by area saw only the first segment). That regrouped view is the substrate for tag curation: a tag confined to one group at count 1 is scattered, one recurring across groups is connective. The curation model covers the judgment side.

The view narrows with --type TYPE and --dir PATH (there is no --tag here; the tag dimension is the output). Matching is case-insensitive and exact, --dir reaches every directory below the one you name, and it accepts root for the bundle root (a real root/ directory, where one exists, owns the name instead since 1.13.0). The deprecated --area still works over the first path segment.

Try it

okf tags docs/

Tags - docs (24 distinct)

  chat       6   Chat threads, Source ingestion pipeline, Streaming responses, Chat mo…
  sources    5   Source ingestion pipeline, Importing sources, Source dedupe, Source s…
  graph      5   Graph model, Graph layout, Link suggestions, Entry editor, Exporting …
  editor     4   Entry editor, Entry history, Link suggestions, Troubleshooting

For a machine, okf tags docs/ --json emits { bundle, count, tags: [{ tag, count, concepts: [id, …] }] }, and okf tags docs/ --by dir --json emits { bundle, count, by, groups: [{ dir, count, tags: […] }] } (the group key matches the dimension), both as compact single-line JSON.

Pitfalls

tags cannot filter by tag. Each read view takes the filters orthogonal to itself; here that means --type and --dir only. To ask "what carries tag X?", flip the question to okf catalog --tag X.
--by counts are within-group. A tag carried by concepts in three directories appears three times, once per group, each with that group's count. Do not sum the groups and expect the flat view's totals.
Filters are case-insensitive and exact, and a filter that matches nothing is an empty view with exit 0, not an error.