okf files

When to use it

• To see a bundle the way the filesystem does: filenames and titles, folder by folder.
• To map a concept id to its path (or the reverse) before editing, since a concept's path is its id.
• To answer "where do concepts of this kind live?" with a filter: okf files docs/ --type Guide lists just the guides, in place.

How it works

files prints each concept's filename and title, grouped by directory. It reproduces the browser server's Files panel on the CLI, sharing its data source with okf catalog and the other read views: it is the "how it's organized" cut of the same per-concept metadata. Advisory read, always exit 0.

The view narrows with --type TYPE, --dir PATH, and --tag TAG, combinable. 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 files docs/ --type Guide

Files - docs (4 of 37 files)

  guides/
    getting-started.md   Getting started
    importing-sources.md Importing sources
    exporting.md         Exporting a bundle
    troubleshooting.md   Troubleshooting

For a machine, okf files docs/ --json emits { bundle, count, files: [{ path, id, dir, type, title, description }] } as compact single-line JSON. --fields / --except project each entry, e.g. --fields path,title when the paths are all you need.

Pitfalls

• Reserved files are missing on purpose. files lists concepts, and index.md / log.md are structure, not concepts. If the tree looks shorter than ls says, that is why; okf index shows the reserved layer.
• Filters are case-insensitive but exact. --dir guide will not match guides; a filter that matches nothing is an empty view with exit 0, not an error.
• --fields and --except are mutually exclusive, both imply --json, and an unknown field name is a usage error (exit 2) that lists the valid ones.