Command reference¶

bf --help lists the commands from setup to repair. bf COMMAND --help (or -h) lists a command's arguments, defaults and choices. Help reads no brain, runs no program and answers even when other values on the line are invalid. Start with Getting started for a first session, and Troubleshooting for recovery.

Commands¶

Every command taking --brain NAME|PATH selects brains as Configuration describes:

• collect, run, channel, queue, update, watch, forget and build act on exactly one brain.
• update and watch also accept repeatable --sensor, --routine and --assistant selectors.

Preview an update or a collection¶

bf update --dry-run
bf collect local-documents --dry-run

The second example needs the local-documents sensor. Only the update preview runs nothing:

collect --dry-run and run --dry-run can contact providers and still append to the program's log.

Collection windows:

• Without time options, collect covers the sensor's lookback through now.
• --since and --until accept now, today, yesterday, 12h, 7d, 2w, YYYY-MM-DD and ISO 8601 timestamps with a timezone.
• A snapshot sensor still returns its whole list.
• --allow-removal accepts a large removal once.

Export the graph¶

bf export prints one JSON object per line for each claim in the selected brains and their direct references, for tools such as DuckDB or networkx. Like search, it reads the caches offline. On the example brain:

bf export | head -1

{
  "brain": "example",
  "origin": "bf://example/actions/2026-09-19_retention/ACTION.md",
  "relation": "tagged-with",
  "subject": "bf://example/actions/2026-09-19_retention/ACTION.md",
  "target": "bf://example/tags/retention"
}

Each line has:

• brain, subject, relation, target and origin;
• the origin's date for a note, or its time and observed for a record.

relation is a declared relation, cites, tagged-with, or links for an untyped link. Lines are sorted by subject, relation, target and origin within each brain.

bf export --kind identities prints one line for each note or record that answers to more than its own address, such as through an alias, with every name it answers to, so duplicate subjects stand out:

{
  "brain": "example",
  "kind": "note",
  "names": ["bf://example/projects/example", "bf://example/projects/example.md", "repo:example/project"],
  "ref": "projects/example.md",
  "status": "stable",
  "type": "project"
}

bf export --kind items prints one line for each note and record, sorted by ref, with its metadata, its mapped fields and its text: a note's whole Markdown file or a record's text. It feeds retrievers BF leaves out, such as embedding or multilingual search, which then return refs for bf read:

{
  "brain": "example",
  "kind": "record",
  "ref": "mail:m1",
  "source": "mail",
  "title": "Launch moved",
  "time": "2026-09-29T14:20:00+02:00",
  "fields": { "status": "open" },
  "text": "The launch moves to Monday."
}

A file that changed since the cache refreshed keeps its line without text; run bf build first for a complete export. The text is your evidence: send it only to services your privacy choices allow.

A busy cache is noted on stderr. A skipped file prints bf: BRAIN: FILE: ERROR on stderr and makes the command exit 1 after the other lines.

Forget records¶

bf forget mail:1a167922 memories/mail/9f2c...json --dry-run
bf forget mail:1a167922

Each REF is a SOURCE:ID record ref or a memories/SOURCE/SHA256.json path, as bf read returns them. The command removes each record in one transaction per source, adds its file's SHA-256 to memories/SOURCE/.forgotten and refreshes the cache. Collection then skips that record whenever its sensor prints it, so a snapshot does not bring it back. A ref not collected yet is listed too.

The reply has ok, dry_run, the records with each ref, whether it was removed now and whether it was listed already, and the refreshed index. An invalid ref exits 2. forget acts on one brain and runs no program. See keep, forget and expire records for Git history and retention.

Shell completion¶

Load the completion script for your shell, for example from its startup file:

eval "$(_BF_COMPLETE=source_bash bf)"   # bash, in ~/.bashrc
eval "$(_BF_COMPLETE=source_zsh bf)"    # zsh, in ~/.zshrc
_BF_COMPLETE=source_fish bf | source    # fish, in ~/.config/fish/config.fish

Typing bf sea and Tab then completes search.

Exit codes and errors¶

Collected text and file names are data. Results, export lines, watch --json snapshots and MCP text escape these characters as JSON \uXXXX escapes, with a surrogate pair beyond U+FFFF:

• DEL and C1 controls;
• the line and paragraph separators U+2028 and U+2029, which many readers treat as line breaks;
• Unicode format characters, such as soft hyphens and zero-width, bidi or tag characters.

Decoded values are unchanged. Diagnostics and MCP errors also escape the other control characters, including newlines, so a file name cannot forge another bf: line.

Invalid input exits 2 with one line naming the argument, the reason and the help to read. When possible, BF reports it before reading any brain:

bf: invalid input: --limit: 0 is not in the range 1<=x<=50 (see bf search -h)

Other invalid inputs:

• bf search "!!!": no word to search.
• bf read 2026-13: no such month.
• bf read projects/../bf.yaml.
• bf read tasks#next: pages have no sections.
• bf read projects --rel cites: a page lists no relation.
• bf read projects/new-website.md --rel nope: the error lists the valid relations.
• An empty value choosing where or on what a command acts, such as --brain "", bf init "", bf collect "", run --hook "", --sensor "", collect SENSOR --since "", build --reproject "".
• A repeated option that takes one value: bf search launch --scope projects --scope concepts is invalid instead of searching only the last scope. Only the program selectors repeat: --sensor, --routine, --assistant and update --kind.

A well-formed ref that names nothing exits 1 and suggests what exists:

• a close page, note, sensor, routine or assistant name (did you mean projects?);
• the note's sections for a missing #section.

collect and run suggest only enabled programs. They fail on a disabled one with sensor NAME is disabled in bf.yaml; set enabled: true to run it.

Commands also exit 1 in these cases:

attention entries include scheduled programs that failed, are overdue or never succeeded, or fell silent, unresolved assistant work and failing channels.

Using replies¶

Every reply states times with your local offset. Dates and field values follow the retrieval reference. Files, run history and the cache keep UTC. Search and read replies follow that reference. problems is always a list of objects with error and, when known, brain and file.

An update reply has:

• ok, dry_run and its brain;
• the sensors, routines and, when the brain declares any, assistants it ran or found due;
• manual for skipped manual programs;
• the refreshed index.

Each assistants row has:

• assistant, its name;
• status: ran, due, skipped or failed, with its skipped reason or error;
• what it concerns: a job and the record it wrote, a schedule with its start and end on a dry run, an input read, such as channel C: read failed: REASON; see logs/channel.C.read.log, or a delivery.

A job waiting for queue space and a delivery still pending are failed rows until they finish.

A run reply has ok, dry_run, any hook and its routines, each with a status of ran, skipped or failed. An assistant's run reply has assistants instead: one entry with its status (ran or failed), the record it wrote (none on a dry run) and the reply text, or an error.

Program and source status¶

bf status groups results under brains. Each brain has:

• its cache, notes, problems, attention, sources, coverage totals and usage;
• routines and assistants when it declares any;
• messaging once its assistant queue exists.

healthy is false exactly when a brain has a problem or an attention entry, its cache is stale or missing, or a brain or reference is unavailable or cannot load. A brain that cannot load appears with only brain, error and, when known, path.

For example, an hourly mail sensor that collected one message reports:

{
  "state": "active",
  "freshness": "fresh",
  "mode": "window",
  "last_collected": "2026-09-29T15:00:00+02:00",
  "window": { "since": "2026-09-28T15:00:00+02:00", "until": "2026-09-29T15:00:00+02:00" },
  "records": 1,
  "bytes": 612,
  "latest": "2026-09-29T14:20:00+02:00",
  "changed": "2026-09-29T15:00:00+02:00",
  "last_run": {
    "records": 1,
    "added": 1,
    "updated": 0,
    "unchanged": 0,
    "removed": 0,
    "requested_start": "2026-09-28T15:00:00+02:00",
    "requested_end": "2026-09-29T15:00:00+02:00",
    "reconcile": false,
    "elapsed_seconds": 0.02,
    "output_bytes": 597
  }
}

A brain also lists warnings when a source or authored folder holds more than 80% of the 100,000-entry scan limit. Warnings never fail status --check. For example:

{"warning":"directory nears the scan limit","directory":"memories/mail","entries":81234,"limit":100000}

Attention entries¶

Like the home page, attention lists:

• scheduled programs this machine runs that failed, are overdue or never succeeded, or are silent, such as {"sensor":"mail","freshness":"never","failed":true};
• assistants with failed or uncertain jobs, whatever their schedules.

Status also lists:

• assistants whose schedules cannot start;
• channels with an unresolved delivery that failed or is uncertain, or with a current stream or read error, such as {"channel":"chat","freshness":"unknown","failed":true}.

An assistant also lists its channel inputs. It is failed, without failures, while one of its jobs is failed or uncertain, and so is its source in sources.

A disabled sensor, routine or assistant reports no failure and appears in no attention entry, so it never fails status --check itself. A failed delivery of its answers still fails its channel. Its log keeps the last failure, and messaging its unresolved jobs.

Messaging¶

messaging holds:

• jobs: the latest 50, each with its state and error;
• deliveries: the next 50 unresolved, each with its state and error;
• counts and delivery_counts by state;
• delivery_failures: the unresolved deliveries holding an error;
• transports: each health: entry now reporting an error, with its time at;
• wakes: each assistant's requested wake with its due time and the job running it, or null.

A transports entry names a stream (health:channel:NAME), a read input (health:read:ASSISTANT:CHANNEL), an assistant's schedule admission (health:assistant:NAME), the dispatcher (health:dispatcher) or a worker lane. Watch clears these entries whenever it starts or stops. Each bf update replaces its read and admission entries.

Status and retrieval read the queue without creating or locking it. When status cannot read the queue, it adds a problems entry instead of messaging. Its assistants then show unknown freshness with that error, and schedules without next_due. Examples of a queue that status cannot read:

• one holding unresolved work under a former path or name;
• one from an earlier release or another build;
• one holding an interrupted write.

List projects with jq¶

With jq, list projects needing review:

(
  set -e
  offset=0
  while [ -n "$offset" ]; do
    page=$(bf read projects --offset "$offset")
    jq -r '.items[] | select(.review) | [.ref, .next // ""] | @tsv' <<<"$page"
    offset=$(jq -r '.next_offset // empty' <<<"$page")
  done
)

Each line holds a project ref and its first open task. Pages end near 32 KiB, often after a few dozen projects, so the loop follows next_offset until it is absent. The subshell stops at the first failed command and keeps its exit status without closing your shell.