CLI Reference

Initializes a new knowledge base. By default the mode is auto-detected from your login state:

• Logged in: creates a cloud workspace named name (defaults to current directory name) and sets it as active.
• Not logged in: creates .sourcebrain/ in the current directory for local mode.

Use --local to force a local repository even while logged in, or --cloud to require cloud mode. The two flags are mutually exclusive.

When run in an interactive terminal, init then offers a short guided setup: it can create a local .sourcebrain/ alongside a cloud workspace (so doctor and scan work), add .sourcebrain/ to your .gitignore, and, for Pro users, kick off an AI codebase scan. Pass --no-guided to skip it; it is skipped automatically in non-interactive shells (scripts, CI).

Prints a quick orientation snapshot, the CLI equivalent of git status. It reports which backend is active (a local .sourcebrain/ repository, a cloud workspace, or your personal @me space), your login state and server, the active workspace, the lesson count, and when the knowledge base last changed.

Run it whenever you're unsure whether you're working locally or against the cloud. It reads one lightweight listing, so it's cheap and needs no extra setup. In cloud mode it also prints the sourcebrain open hint for jumping to the web UI.

Prints who you're logged in as on the cloud: your account email, billing plan, and the workspace commands currently target. A fast identity check when you juggle more than one account or server.

A cloud feature: you must be logged in. For a fuller local/cloud orientation (including whether you're inside a local repository and how many lessons it holds), use sourcebrain status.

A guided tour of SourceBrain, tailored to your current setup. It opens with a checklist of where you are (logged in, active workspace, a local .sourcebrain/ repository, how many lessons are in reach) and the handful of commands most useful from there, then walks through the full tour. Safe to re-run whenever you want a refresher.

With --setup it instead runs the interactive walkthrough that init offers: create a local repository, add it to .gitignore, import existing knowledge files, and optionally kick off an AI codebase scan. Handy when you joined an existing workspace and never ran init on this machine.

Brings preexisting knowledge, like CLAUDE.md and other agent memory files, docs folders, or note vaults, into SourceBrain without retyping it. Each file becomes a proposed lesson you review before anything is saved. Files can live anywhere on disk. Directories are walked for Markdown and text files; YAML front matter is stripped; the lesson path comes from the file's name and location.

A multi-section document is split into one lesson per top-level section, so a big CLAUDE.md or rules file becomes curated, per-topic lessons an agent can pull individually, not a single monolith. Pass --no-split to import each file whole.

Imports are safe to re-run: unchanged files are skipped, and a file that looks like it covers the same topic as an existing lesson is flagged during review so you can reconcile the two. No AI involved; in local mode nothing leaves your machine.

From a live database: a .sql file (DDL dump or migrations) turns into one draft schema node per CREATE TABLE, under db/<table>. You never hand SourceBrain a connection string; dump the schema with your database's own tool and import the file. Postgres (pg_dump), MySQL and MariaDB (mysqldump), SQLite (.schema), SQL Server (SSMS Generate Scripts), and Oracle dumps all work, and the dialect is detected automatically. Dump schema only, not data: a full dump's INSERT rows are your users' data and do not belong in a knowledge base.

Assembles your lessons into a single Markdown rules file, the inverse of import. Two uses: your knowledge stays portable (export it back to a plain CLAUDE.md any time, no lock-in), and it bridges tools that don't speak MCP. Point Claude, Cursor, or a teammate at the generated file, and re-run sourcebrain export to refresh it after editing lessons.

The format only sets the default filename (claude-md writes CLAUDE.md, agents-md writes AGENTS.md); the content is the same. Scope to part of the tree with --under. Trashed lessons are never included.

Searches lessons and prints their paths ranked by relevance, best match first. Works in both local and cloud mode. Unlike context, which bundles the full Markdown of matches for an AI prompt, search returns just the paths; pipe one into sourcebrain show to read it.

Ranking respects your plan automatically: local mode and Free workspaces use keyword ranking, while Pro and Enterprise blend in semantic ranking when the server has embeddings configured (and fall back to keyword otherwise).

On Pro and Enterprise, each result is prefixed with a normalized 0.00 to 1.00 relevance score (relative to the top match), and any result found by meaning alone (one keyword search would have missed) is tagged ~ semantic. Free and local results are unscored.

Everything about the knowledge graph, in one place. Lessons link to each other with a wikilink: write another lesson's path in double brackets, e.g. [[auth/jwt]] (or [[auth/jwt|JWTs]] to show different text). links show lists every lesson that links to the given lesson, plus the links going the other way; links graph prints the whole graph (--json mirrors what the web graph view consumes); links suggest proposes wikilinks a lesson should add.

Outgoing links that point at a lesson which doesn't exist are flagged as broken. In cloud mode the same data drives the web graph view, and links show also resolves cross-workspace links ([[ws:slug/path]]) in both directions. (The old top-level backlinks and graph commands still work as deprecated aliases.)

Shows a unified diff between two versions of a lesson, coloured like git diff in a terminal. With no version arguments it compares the previous version to the latest, i.e. exactly what the most recent edit changed.

Version labels match sourcebrain log: latest, v2, v1, or a bare number like 2. Pass one version to diff it against the latest, or two to diff any pair.

Moves a lesson to the trash. It is a soft, recoverable delete: the lesson and its full history are kept and can be brought back with sourcebrain trash restore. You are asked to confirm first unless you pass -f. Alias: sourcebrain delete.

The lifecycle for deleted lessons. Bare sourcebrain trash (or trash list) lists what is currently in the trash, with when each lesson was deleted. trash restore brings a lesson back.

trash purge permanently deletes a trashed lesson and its entire history; this cannot be undone, so it confirms first unless you pass -f. (The old top-level sourcebrain restore and sourcebrain purge still work as deprecated aliases.)

Opens the active cloud workspace in the SourceBrain web app in your default browser. Pass a lesson path to jump straight to that lesson.

A cloud feature: you must be logged in with a workspace selected.

Scans every lesson for references to code that has changed or been deleted since the lesson was last updated, then reports the likely-stale ones. Schema nodes are also checked against the repo's .sql migrations and dumps: undocumented columns, documented columns that no longer exist, and type drift. Alias: sourcebrain check.

Doctor inspects your working tree, so it must run inside a local repository (one initialized with sourcebrain init). For each lesson it resolves code references from an optional refs: frontmatter list, from inline code spans in the body, and from the lesson's own path when that path is itself a source file (e.g. a lesson named src/app.jsx is checked against that file). A ref may also include an anchor (path#Symbol for a function or type, or path:40-58 for a line range) to point at an exact location instead of a whole file. It then flags two problems:

• missing-file: a referenced file no longer exists.
• file-changed-since: a referenced file changed (by git commit time, or filesystem mtime outside git) after the lesson's last update.
• possible-secret: lesson content matches a known credential shape (API key, token, private key block). Lessons are shared knowledge; remove the value and rotate it if it was real. The same check warns at save time in add, edit, import, and the MCP write tools.

On Pro, doctor additionally runs symbol-level code drift checks: if a lesson names a function or type that no longer exists in the referenced source file, it's flagged too. Go is parsed precisely; Python, Ruby, JavaScript/TypeScript, Rust, PHP, Swift, Kotlin, and Scala are checked by matching definition patterns (def, class, fn, …); for Java, C#, and C/C++ a symbol is flagged only when its name disappears from the file entirely, the most conservative signal.

Run outside a local repository (logged in, with a cloud workspace selected) and doctor runs the server-side checks instead, the same ones the web Health page shows: broken links — a [[wikilink]] whose target lesson doesn't exist — and overlapping lessons, pairs similar enough to duplicate or contradict each other. Broken links are checked on every plan; overlap detection needs Pro with semantic search. Links to a lesson that exists but you can't read are not reported: those work for everyone with access.

With --staged or --since <ref>, doctor switches to a change-scoped check: instead of auditing every lesson, it reports the lessons a specific change may have invalidated. It looks two ways, because the lesson that goes wrong often isn't the one anchored to the file you touched: anchored lessons whose refs point at a changed file, and related lessons whose content is about what you changed even if nothing links them to that file (keyword-ranked locally, semantic when embeddings are configured). This is the check to run in a pre-commit hook, or for an agent to run after editing code.

The other half of sourcebrain doctor: when a lesson is flagged stale but is still accurate, sourcebrain verify clears the warning without editing the content. It shows the current staleness findings, then saves a new version with unchanged text and a “verified” note, moving the lesson's last-updated time past the code change that triggered the warning.

The attestation appears in sourcebrain log like any other version, so “someone checked this and it still holds” is recorded rather than implied. If the lesson is not still accurate, don't verify it — fix it with sourcebrain edit or trash it.

The reverse of a lesson's reference list: given a source file, lists every lesson that references it, including any symbol or line anchors. Use it to answer "what knowledge is attached to the file I'm editing?"

It inspects your working tree, so run it inside your project, a local repository, or (in cloud mode) any git checkout with a workspace selected. It also flags any match whose file has changed or been removed since the lesson was written with a ⚠ stale marker, the same staleness signal as doctor.

--json emits machine-readable output intended for editor integrations and other tooling, including a stale flag (and stale_detail) per match.

The forward direction: opens a file a lesson references in your editor, jumping straight to the anchored symbol or line range. show lists a lesson's referenced files with an index; pass that index to pick one (with a single reference the index is optional).

The editor is chosen from --editor, then $SOURCEBRAIN_EDITOR, then code (VS Code) if it's on your PATH, then $VISUAL /$EDITOR. Symbol anchors are located by a best-effort search when the file has no line anchor. Like refs, it runs inside a local repository.

Manage the logged-in account. name and nickname set the optional identity teammates see (each prints the current value with no argument, and clears it with --clear). password changes your password (prompts for the current one, then the new one twice; all hidden).

verify-email re-sends the address-verification link when sourcebrain whoami reports your email as unverified. The link always goes to the account's own address, and the server rate limits it to a few sends per ten minutes.

delete permanently deletes your account, your personal My Lessons space, and any workspaces you own that have no other members. You confirm by typing DELETE and your password. Team workspaces you own that still have other members must be handed off or deleted first. This cannot be undone; on success your saved credentials are cleared.

Manage a workspace's organization membership (see Organizations). attach puts a workspace you own into an org you belong to, and org members then see it automatically. detach takes it back out (workspace owner or org admin); people invited directly keep their access.

visibility flips an attached workspace between org (every org member gets access) and private (grouped under the org, but access stays invite-only). The workspace argument defaults to the active workspace.

Manage organizations. create makes you the owner (Pro); show prints the org's workspaces, members, and outstanding invites. invite adds an existing account immediately, or sends a signup invite to an email without one, and they join the org automatically when they register (pending lists those, revoke cancels one).

delete removes the org itself; its workspaces are not deleted, they just leave the org and keep their direct members. Attach and detach workspaces with sourcebrain workspace attach/detach.

Designates one org-visible workspace as the organization's shared context: the cross-repo conventions space that search, ask, the context bundle, and MCP retrieval include alongside every member workspace's own lessons. Shared hits appear with a ws:slug/path prefix and rank slightly below same-workspace matches, so repo-specific knowledge wins ties.

Org-admin only. Run with --clear (or without a workspace) to remove the designation.

Share one of your personal lessons with specific people, or publish a copy to a whole team workspace. With no flags, it lists who the lesson is shared with.

Recipients must have a SourceBrain account and see the lesson via sourcebrain shared. --can-edit grants edit access (default is read-only). Sharing acts on your cloud personal space (Pro).

Lists the lessons other people have shared with you, with the owner and whether you can edit.

show <path> prints a shared lesson; edit <path> opens it in your editor and saves a new version, available only when the owner granted you edit access. Add -m to edit for a version note.

Lists pending change requests. When a workspace’s approval workflow (a beta feature) is on, a non-admin member’s lesson add/edit becomes a request an admin approves (applies it) or rejects. Admins see all pending requests; members see their own.

enable / disable turn the workflow on or off for the active workspace (admin only).

A pull-based way to follow activity on the lessons, plans, and schemas you care about, with no notifications. watch subscribes to a node; unwatch stops. watching lists everything you follow with an unread count each.

inbox shows unread updates on the nodes you watch, newest first (changes by other people and plan status moves). You are never notified about your own edits. Add --all for recent activity regardless of read state, and --read to mark everything read after showing it.

A cloud/team feature: you must be logged in with a workspace selected.

Create a plan (opens your editor without -c). It starts as a draft visible only to you; publish it to its team or workspace by moving it to proposed.

plan status advances it through the lifecycle. Only valid transitions are allowed; archive is reachable from any state.

Creates a schema: a typed kind of lesson that documents a table or collection, each column's type, keys, allowed values, and the gotchas a plain DDL dump never captures. It renders as a structured view in the web app and is served to AI tools as structured JSON (get_lesson format="schema").

Without -c, schema create opens your editor prefilled with a starter template showing the fenced sourcebrain-schema block format; the content must contain a valid block. Creating is a cloud/team feature.

schema diagram renders every schema as a Mermaid ER diagram: one entity per table with keys and gotchas as attribute comments, and a relationship edge for each fk: reference. A referenced table with no schema node renders as an empty entity, an undocumented gap made visible. The output pastes into anything that renders Mermaid (GitHub, GitLab, Obsidian). Works in local and cloud mode.

Read or add comments on a lesson or plan. Discussion is a beta feature an admin enables per workspace; you can comment on anything you can see. Comments are flat, plain-text, and pull-based (no notifications). enable / disable turn discussion on or off for the active workspace (admin only), and status shows whether it's on, the CLI counterpart to Settings → Discussion.

Uploads lessons from the local database to the cloud workspace. For each lesson:

• If only local: upload it.
• If same hash: skip (already in sync).
• If both sides changed: show a diff and prompt to resolve.

Reports a summary: X pushed, Y skipped, Z unresolved.

Downloads lessons from the cloud workspace to the local database. Mirror of push:

• If only cloud: download it.
• If same hash: skip.
• If both sides changed: show a diff and prompt to resolve.

Runs pull then push in one step, the full round trip. It pulls first, so you integrate the cloud's version before uploading yours, then pushes your local changes back up.

Both halves prompt on conflicts with a diff, exactly like running the two commands separately. Like push and pull, it needs both a local .sourcebrain/ repository and an active cloud workspace.

Asks a natural-language question and prints an answer synthesized from the lessons in your active workspace, followed by a list of the lessons it drew on. You can quote the question or type it as bare words.

The server retrieves only the lessons most relevant to your question (not the whole knowledge base) and asks the configured AI model to answer from them, so the answer stays grounded in your team's knowledge and cites its sources. When the workspace belongs to an organization with a shared context, those cross-repo lessons are considered too.

A Pro, cloud feature: you must be logged in with a workspace selected, and it is metered per workspace. Pass --json for a machine-readable { answer, sources } object. See Answering questions in the AI guide.

Starts a Model Context Protocol (MCP) server over stdio so AI tools like Claude Desktop and Cursor can read and write your knowledge base directly. The server targets whichever backend is active (local .sourcebrain/ or your selected cloud workspace) and exposes a full set of tools to read and search (get_workspace_info, search_lessons, get_lesson…), write (add_lesson, plans, change requests), navigate (get_graph, lessons_for_file), and check staleness (check_lessons).

You normally don't run this by hand; your AI tool launches it for you via its MCP config. See the AI Integration guide for setup.

Installs SourceBrain's hooks into an AI coding tool so lessons reach the agent automatically, instead of depending on it remembering to call a tool. Where sourcebrain mcp makes lessons available, this makes them arrive. Currently supported target: claude-code.

The hooks shell out to sourcebrain hook, so the binary must be on PATH. On a machine with no knowledge base configured they are inert — silent, exit 0 — so committing the shared config can't break a teammate's setup. Removal only touches SourceBrain's own entries.

Drafts a lesson describing a file (or a range of lines) using AI, so you don't start from a blank page. The draft is a starting point; review and edit it, then save it yourself with sourcebrain add. Nothing is saved automatically.

This is a Pro, cloud feature: you must be logged in, and the selected code is sent to the server, which calls the configured AI model. It's metered per workspace. See Lesson suggestion in the AI guide for the server requirements and limits.

Bootstraps a workspace by drafting lessons for files you choose, so you don't start from an empty knowledge base. The CLI sends a list of your source files (paths and sizes only) and prints a link; open it to pick which files to scan and watch a budget bar. The CLI then uploads just those files' contents, the server drafts lessons, and you review and accept them in the browser. Nothing is saved automatically.

A Pro, cloud feature. You must be logged in, and it runs from inside a local repository. The first run asks you to opt in (your code is sent to the AI provider for the files you select). See Codebase scan in the AI guide for budgets and requirements.

Reports how close the active workspace is to its plan limits, feature by feature: lessons, members, and workspaces, plus the monthly AI budgets (lesson suggestions, answers, and codebase-scan tokens). Each limited feature shows a utilization bar and percentage; unlimited ones are labelled as such, and features not in your plan are flagged so you know what an upgrade unlocks. Alias: sourcebrain limits.

A cloud feature: you must be logged in with a workspace selected. Limits come from the workspace owner's plan, and the monthly budgets reset at the start of each calendar month. This is the CLI counterpart to the usage panel on the web Settings page.

Shows or sets the organization AI instructions for the active cloud workspace: the guidance returned at the top of get_workspace_info that steers every agent which connects. This is the CLI counterpart to the web AI Settings page. Alias: sourcebrain ai.

Run with no arguments to print the current instructions. set replaces them: pass the text as an argument, or run set with no argument to edit them in your $EDITOR. Pass an empty string ("") to clear them and fall back to the built-in default. A cloud feature.

Inspects what a .sourcebrainignore file at the project root excludes, most importantly from the codebase scanner, which sends file contents to the AI provider. The file uses .gitignore syntax and is meant to be committed, so the whole team shares one policy and changes go through review. These commands are read-only views that resolve the patterns against your real working tree; to change what is excluded, edit .sourcebrainignore.

ignore list lists every excluded file with the pattern that matched it (useful for catching a typo'd pattern that silently matches nothing). ignore check <path> reports whether one file is excluded and by which pattern, exiting 0 when ignored and 1 when not, mirroring git check-ignore. Runs inside a local checkout.