CLI reference

gbrain is a single binary that exposes the entire brain over a Unix-style CLI. This page documents every subcommand grouped by domain. For the authoritative flag list on your installed version, run gbrain --help or gbrain <command> --help.

Global options

These flags apply to every subcommand and may appear before or after the command name.

Flag	Description
--db <PATH>	Database path. Env: GBRAIN_DB. Default: ./brain.db.
--model <ALIAS|HF_ID>	Embedding model. Env: GBRAIN_MODEL. Default: small. Recognized aliases: small, base, large, m3. Any other value is treated as a Hugging Face model ID (online build only).
--json	Emit JSON instead of human-readable text. Most commands honor this.
--help, -h	Print help. Works at root or per-command.
--version, -V	Print version and exit.

Data — read and write

init [PATH]

Create a new brain database. Records the active embedding model in brain_config so subsequent opens validate against it.

gbrain init ~/brain.db
gbrain init ~/brain-large.db --model large   # online build only

get <SLUG>

Read a page by slug. Slugs may be collection-qualified (<collection>::<slug>) when more than one collection is attached.

gbrain get people/alice
gbrain get research::people/alice

put <SLUG>

Write or update a page from stdin. For updates, supply --expected-version to enable optimistic concurrency (OCC). On a conflict the call fails and you must re-fetch before retrying.

cat updated.md | gbrain put people/alice --expected-version 7

Flag	Type	Default	Notes
--expected-version <N>	i64	none	Required for safe updates; absent means “create only”.

list

List pages with optional filters.

Flag	Type	Default
--wing <NAME>	string	none
--type <TYPE>	string	none
--limit <N>	u32	50

search <QUERY>

FTS5 full-text search. By default the input is sanitized so natural-language queries with ?, !, etc. work without escaping. Pass --raw to send the query verbatim and use FTS5 expert syntax (quoted phrases, boolean operators, prefix wildcards).

Flag	Type	Default
--wing <NAME>	string	none
--limit <N>	u32	10
--raw	flag	false

gbrain search "river ai"
gbrain search '"local-first" AND (sqlite OR fts5)' --raw

query <QUERY>

Hybrid retrieval: FTS5 + vector similarity, fused via set-union. Use --depth auto to enable progressive expansion — the engine grows the context window until the token budget is exhausted.

Flag	Type	Default
--depth <auto|''>	string	auto
--limit <N>	u32	10
--token-budget <N>	u32	4000
--wing <NAME>	string	none

gbrain query "who is interested in offline-first knowledge systems?"

Ingest — import, export, embed

ingest <PATH>

Single-file ingestion with SHA-256 idempotency. Re-running on the same file is a no-op unless --force is set.

Flag	Type	Default
--force	flag	false

import <PATH>

Batch import a markdown directory. Page types are inferred from a PARA-style folder layout (projects/, areas/, resources/, archives/).

Flag	Type	Default
--validate-only	flag	false

export <PATH>

Export every page to a markdown directory.

Flag	Type	Default
--raw	flag	false
--import-id <ID>	string	none

--raw writes byte-for-byte the original ingested content (preserves frontmatter ordering and whitespace); without it, the export is the canonicalized form.

embed [SLUG]

Generate or refresh embeddings.

Flag	Type	Default
--all	flag	false
--stale	flag	false

gbrain embed people/alice          # one page
gbrain embed --stale                # only re-embed pages whose chunks changed
gbrain embed --all                  # rebuild every embedding

Graph — links and backlinks

link <FROM> <TO>

Create a typed temporal cross-reference. Both ends must exist as pages.

Flag	Type	Default
--relationship <NAME>	string	related
--valid-from <DATE>	ISO-8601	none (open-start)
--valid-until <DATE>	ISO-8601	none (open-end)

link-close <LINK_ID>

Close an open temporal link interval by setting valid_until.

Flag	Type
--valid-until <DATE> (required)	ISO-8601

links <SLUG>

List outbound links from a page, with link IDs.

Flag	Type	Default
--temporal <current|all>	string	current

unlink <FROM> <TO>

Remove a cross-reference entirely. With --relationship, only that edge is removed.

Flag	Type	Default
--relationship <NAME>	string	none (remove all)

backlinks <SLUG>

List inbound links to a page.

Flag	Type	Default
--temporal <current|all>	string	current

graph <SLUG>

N-hop neighbourhood graph from a page (BFS over links, with temporal filtering).

Flag	Type	Default
--depth <N>	u32	2
--temporal <current|all>	string	current

Tags and timeline

tags <SLUG>

Manage tags. Both --add and --remove are repeatable.

gbrain tags people/alice                       # list
gbrain tags people/alice --add infra --add ops # add two tags
gbrain tags people/alice --remove ops          # remove one

timeline <SLUG>

Show timeline entries for a page.

Flag	Type	Default
--limit <N>	u32	20

timeline-add <SLUG>

Append a structured timeline entry. --date and --summary are required.

Flag	Type	Required
--date <DATE>	ISO-8601	yes
--summary <TEXT>	string	yes
--source <REF>	string	no
--detail <TEXT>	string	no

Intelligence — checks and gaps

check [SLUG]

Run contradiction detection on a single page or, with --all, every page. Heuristic; backed by the assertions table.

Flag	Type
--all	flag
--type <TYPE>	string

gaps

List unresolved knowledge gaps. By default only unresolved gaps are returned.

Flag	Type	Default
--limit <N>	u32	20
--resolved	flag	false

Maintenance

validate

Brain integrity checks. With no flags, all checks run.

Flag	Type
--all	flag
--links	flag
--assertions	flag
--embeddings	flag

compact

Checkpoint the SQLite WAL into a single file. Safe to run while no writers are active.

stats

Brain statistics: page count, link count, gap count, active embedding model.

gbrain stats
gbrain stats --json

Collections — vault sync (Unix, v0.9.6)

collection groups all vault-sync subcommands. See Manage collections for end-to-end guidance.

gbrain collection add notes ~/Documents/Obsidian --writable
gbrain collection list
gbrain collection info notes
gbrain collection sync notes
gbrain collection ignore add notes "_attachments/**"
gbrain collection quarantine list notes

Subcommands: add · list · info · sync · restore · restore-reset · reconcile-reset · ignore add|remove|list|clear · quarantine list|export|discard|restore.

Configuration

config

Read or write runtime config keys.

gbrain config get default_token_budget
gbrain config set default_token_budget 6000
gbrain config reset default_token_budget

Subcommands: get <KEY> · set <KEY> <VALUE> · reset <KEY>.

See Configuration for the full key list.

System — serve, skills, raw

serve

Start the MCP stdio server. Connects any MCP client to this brain.

GBRAIN_DB=~/brain.db gbrain serve

serve ships on macOS and Linux today; Windows parity is on the roadmap.

skills

Skills are agent-shaped markdown files embedded in the binary, extractable to ~/.gbrain/skills/, and overridable from the working directory.

gbrain skills list      # show resolution order
gbrain skills doctor    # verify hashes; report shadowing

Subcommands: list · doctor.

call <TOOL> [PARAMS_JSON]

Invoke a raw MCP tool from the CLI. Useful for debugging and for shell scripts.

gbrain call brain_search '{"query":"alice","limit":3}'

pipe

JSONL streaming mode. Reads one JSON request object per line on stdin, writes one response per line on stdout. Designed for shell pipelines and lightweight harnesses.

version

Print the version and the brain’s schema-version state.

Exit codes

Code	Meaning
0	Success
1	General failure (validation, IO, business-rule violation)
2	Argument or flag parsing error

When --json is set, errors are also emitted as a JSON object with an error field on stderr.