Work with multiple knowledge bases: okf --root and config

Work with multiple knowledge bases

One binary, any number of catalogues, chosen per call.

Search terms covered: multiple knowledge bases CLI, okf --root, catalogue config, Obsidian vault CLI. Output below comes from okf 0.2.5 against two throwaway catalogues, a and b; b is a copy of a without the recipes and kc-gov bundles.

Set it up

okf picks the catalogue in this order:

flowchart TD
    A[okf command] --> G{--global?}
    G -- yes --> C[root from ~/.config/okf/config.toml]
    G -- no --> R{--root?}
    R -- yes --> D[that path]
    R -- no --> W[nearest catalogue above the working directory]
    W -- none found --> C

--root <path> uses that catalogue.
Otherwise okf walks up from the working directory and uses the nearest catalogue.
Otherwise it reads root from ~/.config/okf/config.toml.
--global skips steps 1 and 2 and uses the config root.

root = "~/knowledge"

Details and the .okf.toml marker: Configuration.

Work through it

Run the same command against two roots:

_ctx: Curated, ordered reading lists per topic — one file per ctx slug, managed by `okf ctx`.
handbook: Welcome to the handbook.
kc-gov:
recipes:

_ctx: Curated, ordered reading lists per topic — one file per ctx slug, managed by `okf ctx`.
handbook: Welcome to the handbook.

Inside a catalogue you need no flag. From a/handbook/ops, okf index prints the catalogue a. With root = "<path to b>" in the config, okf --global index run from inside a prints the catalogue b.

Catalogue-wide commands such as find, list, check and tags span all bundles of one root. Narrow to one bundle with --where "path ~ handbook/". See Where filter.

What you get

One command set across every catalogue: a private one, project ones and shared bundles. Agents use the same selection: the MCP tools take root and use_global, see Agent onboarding.

Limits

--root and --global go before the command and exclude each other:
okf --global --root b index
```
ERROR: --global and --root exclude each other
[exit 2]
```
--global without a configured root exits 3.
One call uses one root. To search two catalogues, make two calls.

Work with multiple knowledge bases: okf --root and config