Command reference¶
Command results go to stdout as compact JSON; help and version output are plain text. Diagnostics go to stderr. Exit 0 means success, 1 a failure or failed check, 2 invalid command-line input and 130 cancellation. bf COMMAND --help lists every option.
| Command | Contract |
|---|---|
init PATH [--name NAME] [--no-collect] [--full] |
Create a brain in a new, empty or freshly cloned directory and register it under the directory's name, with collection trust unless --no-collect. It creates projects/, concepts/ and actions/; --full adds the optional folders. |
register [PATH] [--collect] |
Add an existing brain to ~/.config/bf/config.yaml; --collect lets this machine run its sensors. |
search [QUERY] [--since] [--until] [--source] [--type] [--status] [--limit] [--recent] [--changed-since] [--current] |
Search words or an identity, or list by time window or filter. See search. |
read REF |
Read a note, note#section, source:id record or explicit identity. |
update [--dry-run] |
Run due sensors of every trusted brain, then refresh their caches. Dry-run runs nothing. |
collect SENSOR [--since] [--until] [--dry-run] |
Run one sensor now; the window defaults to its lookback. Dry-run shows three samples and writes nothing. |
status [--check] |
Per brain: cache state, notes, records, each source's freshness, last error and log, active projects due for review, and local usage counts. --check exits 1 when a trusted scheduled source is stale, failed, or a file was skipped. |
validate |
Check notes, OKF concept structure, action folders, links, cited records and record partitions; exit 1 on problems. |
eval [--path queries.yaml] |
Run retrieval cases; exit 1 when one fails. |
build |
Explicitly recover interrupted record writes, then rebuild the search cache. Ordinary search refreshes only the cache. |
mcp |
Serve search and read over MCP stdio. |
schema |
Print the JSON Schema of bf.yaml. |
Search items and exact reads identify their brain. Health replies group brains under brains and retain sources for collection coverage, including historical evidence. Update replies report executed sensors per brain; collection entries use sensor. These are execution names: record refs stay source:id and OKF provenance stays sources.
Existing-brain commands accept --brain NAME|PATH; init and register take a path argument instead. Without --brain, commands use BF_BRAIN, then the brain containing the working directory, then every registered brain. Commands that act on a single brain (collect, validate, eval, build) ask for --brain when several are registered.
status --check also fails when the cache is stale because another writer is active. update exits 1 when collection or cache refresh fails, including skipped evidence files. Inspect the JSON diagnostics before treating an empty result as proof that nothing happened. collect --dry-run runs the provider and updates its private stderr log; it does not write records or success history. update --dry-run runs no providers.
Use --brain NAME for scripts and scheduled jobs that must target one brain. update follows the same selection rules as search: inside a brain it updates that brain; outside, it considers all registered brains. It skips those without collection trust.
With jq installed, JSON results can feed an ordinary shell pipeline:
Inspect problems and stale before using a filtered report as a complete inventory. In shell automation, use set -o pipefail so a failed Brain Framework command is not hidden by a successful output formatter.