CLI reference
Utilities
context reads and writes your knowledge blobs. dashboard shows a server's health. journal shows what past plan runs decided. init, config show and doctor set up and check a project. mcp serve and chat let an AI app drive briar. Last come completion, version and the flags that work on every command.briar context
Reads and writes blobs in your knowledge store. A blob is one named piece of markdown text. briar extract writes blobs. agent and plan read them. With context you can see them, fix them, or add your own.
Use it when
- You want to read what extract found before you run an agent.
- You want to save notes or a hand-written plan as a blob.
- You want to delete old blobs, or move one to another store.
Blob names and categories
A blob name looks like category:rest. The category is the part before the first colon. The file store keeps knowledge:acme in the file ./knowledge/knowledge/acme.md. A name with no colon, like notes, has no category and lives at ./knowledge/notes.md. A name with a / or ending in .md is taken as a file path, as is.
| Name | Who writes it | What it holds |
|---|---|---|
knowledge:acme | briar extract, by default | The extract report for the company acme, one section per extractor. |
knowledge:acme.weekly | A runbook schedule with the task weekly, when the runbook's knowledge name is knowledge:acme | The report for that one task. |
knowledge:acme.q3 | briar plan run on the plan q3 | What briar learned from the cards it finished. The plan selector reads it. |
plan:q3 | briar plan build | A saved plan and its cards. |
inventory:acme | The same runbook, when its knowledge: block has config: {inventory: "true"} | The full data each extractor found, as JSON. |
The coding agent looks at the blobs whose names start with knowledge:acme, but keeps only the extractor sections its role uses, such as codebase-conventions and reviewer-profile. A note you save there, and the plan blob knowledge:acme.q3, do not reach it. The plan blob is read by the plan selector. plan build also reads active-tickets:acme and active-work:acme when they exist.
Parameters every context subcommand takes
You can put these before or after the subcommand. Both briar context --store postgres list and briar context list --store postgres work.
--store STOREdefault: filefilepostgresfile is a folder of markdown files. postgres is a database at BRIAR_DATABASE_URL. The default stays file even when BRIAR_DATABASE_URL is set. To switch every context command, set BRIAR_STORE=postgres or store = "postgres" in .briar.toml. Example: --store postgres.--root PATHdefault: ./knowledgepostgres. The root line in .briar.toml changes the default. Example: --root ./kb.$ briar context put
briar context put BLOB_NAME [--content TEXT | --from-file PATH] [--category CATEGORY]Saves a blob. If the name exists, the new text replaces the old. It prints the saved record as JSON: name, category, size in bytes, and the file path for the file store.
Examples
# Text on the command line.$ briar context put notes:acme --content "Deploys freeze on Fridays."
You get ./knowledge/notes/acme.md with that line.
# Text from a file.$ briar context put notes:acme.release --from-file release-notes.md
You get the whole file saved under that name.
# Text from another command, through stdin.$ git log --oneline -20 | briar context put notes:acme.recent --content -
You get the last 20 commit lines as a blob.
# Copy a blob from the file store into Postgres.$ briar context get knowledge:acme | briar context put knowledge:acme --store postgres
You get the same blob in Postgres. With no --content and no --from-file, put reads stdin.
Parameters
BLOB_NAMErequirednotes:acme.--content TEXT- to read stdin. Example: --content "Use pnpm, not npm.".--from-file PATH--from-file notes.md.--category CATEGORY--category notes.It also takes --store and --root, as above. With no text and no pipe, it stops with an error.
$ briar context get
briar context get BLOB_NAMEPrints one blob's markdown to stdout. If the blob does not exist or is empty, it stops with blob not found and exit code 1.
# Read the extract report for acme.$ briar context get knowledge:acme# Read a saved plan from Postgres into a file.$ briar context get plan:q3 --store postgres > q3-plan.md
You get the raw markdown, ready to read or pipe. It takes --store and --root, as above.
$ briar context list
briar context list [--prefix PREFIX]Lists the blobs in the store with their category, size and last change time, sorted by name.
# Every blob.$ briar context list# Only the plans.$ briar context list --prefix plan:# Only acme knowledge, as JSON.$ briar context list --prefix knowledge:acme --format json
You get a table with name, category, byte_count and updated_at. In the file store, updated_at is the file time in Unix seconds.
--prefix PREFIX--prefix knowledge:.$ briar context delete
briar context delete BLOB_NAME [--yes]Deletes one blob. It asks first. In the file store it also removes the category folder when it becomes empty.
# Asks: Delete blob notes:acme from store file? [y/N]$ briar context delete notes:acme# No question, for scripts.$ briar context delete notes:acme.recent --yes
You get deleted notes:acme.recent, or not found when there was no such blob.
--yesy stops with aborted and exit code 1. Example: --yes.$ briar context categories
briar context categoriesCounts the blobs in each category. Names with no colon show under (none).
$ briar context categories$ briar context categories --store postgres
You get a table with category and blob_count, like knowledge 3 and plan 1.
briar dashboard
Serves a small web page about the health of the host that runs your scheduler (briar runbook serve). It only reads. It has no login: anyone who can reach the port can see the page.
The page shows:
- Disk use, memory, load and uptime. Memory, load and uptime come from
/proc, so they only show on Linux. - The git commit, branch and remote of your deployed checkout.
- Whether a
briar runbook serveprocess is running. - The schedules in your runbook YAML files, with the next run time.
- Recent runs and the last 80 lines of the scheduler log. GitHub API quota, read from the log lines (no extra API call).
- Whether the host can reach
api.github.com,github.comandsts.amazonaws.comon port 443.
/healthz answers ok, for uptime checks. A panel whose data is missing shows empty, without an error.
Use it when
- You run the scheduler on a server and want one page to check.
- A scheduled extract stopped and you want to know why.
- You want a snapshot of the host for a ticket or a chat.
Examples
# Serve on http://127.0.0.1:8080 (this machine only).$ briar dashboard --examples runbooks/
You get the page at http://127.0.0.1:8080. Stop it with Ctrl-C.
# Print the page once, as HTML, and exit.$ briar dashboard --once --examples runbooks/ > status.html
You get one HTML file you can open or attach.
# On a server, with its paths.$ briar dashboard --port 9000 \--examples /opt/briar/runbooks \--log-file /var/log/briar/scheduler.log \--repo-path /opt/briar \--disk-path /var
You get the page on port 9000, with the server's own files.
Parameters
--host ADDRESSdefault: 127.0.0.10.0.0.0 opens it to the network. Do that only behind a firewall or a proxy with a login. Example: --host 0.0.0.0.--port PORTdefault: 8080--port 9000.--examples DIRdefault: ./examples*.yaml files there. Example: --examples runbooks/.--log-file PATHdefault: /var/log/briar/scheduler.log--log-file ./scheduler.log.--disk-path PATHdefault: /--disk-path /var.--repo-path PATHdefault: .--repo-path /opt/briar.--once--once.briar journal
Shows the decision journal. A journal session is the record of one run: what briar decided, and why. Only two commands write sessions: briar plan run (command name plan.run) and briar scaffold (scaffold.implementation or scaffold.pr-fixes). A plain briar agent implement or prfix writes none.
Sessions land in the folder where you ran the command: ./journal/sessions/DATE/ID.json, plus a readable copy in ./journal/published/ID.md. An ID is 12 hex characters, like 7a3b8c2d91e4. BRIAR_JOURNAL_ROOT moves the folder, and BRIAR_JOURNAL=off stops the writing.
Use it when
- A plan run picked a card you did not expect, and you want to know why.
- You want to paste a run's record into a PR or a ticket.
- You want a JSON copy of a run for your own tools.
Parameters every journal subcommand takes
--store STOREdefault: filefilefile is the only choice in 1.1.75. Example: --store file.--root PATHdefault: ./journal--root /opt/briar/journal.If .briar.toml sets store or root
store and root lines in .briar.toml (and BRIAR_STORE) also change these two defaults. With store = "postgres", journal commands fail with unknown journal store 'postgres'. With root = "./kb", they look in the wrong folder. Pass --store file --root ./journal in those projects.$ briar journal list
briar journal list [--command PREFIX] [--limit N] [--store file] [--root PATH]Lists sessions, newest first, one per line.
# The 50 newest sessions.$ briar journal list# The 5 newest plan runs.$ briar journal list --command plan.run --limit 5# Every scaffold session.$ briar journal list --command scaffold.
7a3b8c2d91e4 plan.run target=q3@acme-co/acme-app decisions=14 started=2026-10-09T14:02:11+00:00
You get the ID, the command, the target, the number of decisions and the start time. With no sessions you get (no sessions).
--command PREFIX--command plan.run.--limit Ndefault: 50--limit 5.$ briar journal show
briar journal show SESSION_ID [--store file] [--root PATH]Prints one session as markdown: a title, the start and end time, then each decision with its value and reason.
$ briar journal show 7a3b8c2d91e4
You get readable markdown. An unknown ID stops with not found and exit code 1.
$ briar journal export
briar journal export SESSION_ID [--as {markdown,json}] [--out PATH] [--store file] [--root PATH]Writes one session to a file or to stdout.
# Markdown to stdout.$ briar journal export 7a3b8c2d91e4# JSON to a file.$ briar journal export 7a3b8c2d91e4 --as json --out q3-run.json
You get the session in that format. When you write a file, briar prints wrote q3-run.json on stderr.
--as FORMATdefault: markdownmarkdownjson--as so it does not clash with the global --format. Example: --as json.--out PATHdefault: -- means stdout. Example: --out q3-run.md.briar init
Writes a starter .briar.toml in the current folder. This file holds the values you would type on every command, like your company and repo (see Configuration). It reads the repo owner and name from your git origin remote. It prints the file to stdout and wrote .briar.toml to stderr.
Use it when
- You start using briar in a repo.
- You are tired of typing
--companyon every command.
Examples
# Inside a clone of acme-co/acme-app.$ briar init --company acme
company = "acme"store = "file"[repo]owner = "acme-co"repo = "acme-app"provider = "github"# Uncomment to set agent defaults:# [agent]# model = "claude-sonnet-4-6"# git_user_name = "your-bot"# git_user_email = "[email protected]"
You get this file, plus a few comment lines at the top. From now on, commands in this folder use acme and acme-co/acme-app on their own.
# Use Postgres, and replace the file that is there.$ briar init --company acme --store postgres --force# Outside a git checkout, name the repo yourself.$ briar init --company acme --owner acme-co --repo acme-app --path ~/acme/.briar.toml
You get the file with those values, at that path.
Parameters
--company COMPANYcompany = "", which you must fill in by hand. Example: --company acme.--store STOREdefault: filefilepostgres--store postgres.--owner OWNERorigin. Example: --owner acme-co.--repo REPOorigin. Example: --repo acme-app.--path PATHdefault: ./.briar.toml--path config/.briar.toml.--force--force.briar config show
Prints each project setting, its value, and where the value came from. It only reads. Use it when a command picks a value you did not expect. It takes no flags of its own.
$ briar config show$ briar config show --format json
You get the config file path on stderr, then a table with setting, value and source. The settings are company, store, root, tracker, owner, repo, provider, model, git_user_name and git_user_email. A source is one of:
env (BRIAR_COMPANY)orenv (BRIAR_STORE): an env var set it.config (.briar.toml), with[repo]or[agent]for keys in those tables.inferred (git origin): owner and repo from your git remote.-with the value(unset): nothing set it, so each command uses its own default.
A flag you type on a command still wins over all of these. It does not show here, because flags belong to one run.
briar doctor
Checks this machine and project in a few seconds. It makes no network calls and opens no database. Each check is ok, warn or fail. It exits with 1 only on a fail, so you can run it in CI. It takes no flags of its own.
$ briar doctor$ briar doctor --format json
| Check | ok when | Otherwise |
|---|---|---|
python | Python is 3.10 or newer. | fail |
briar | Always. It shows the version. | Never fails. |
project config | A .briar.toml is found here or above. | warn: run briar init |
git remote | The folder has a git origin briar can read. | warn |
llm key | ANTHROPIC_API_KEY, OPENAI_API_KEY or GEMINI_API_KEY is set. | warn |
github token | GITHUB_TOKEN is set. | warn |
store | The store is file, or it is postgres and a database URL is set. | fail |
The llm key check does not look at CLAUDE_CODE_OAUTH_TOKEN or AWS Bedrock. If you use one of those, its warning is safe to ignore. It only checks that a key is set, not that it works.
briar mcp serve
Starts an MCP server. MCP (Model Context Protocol) is a standard way for an AI app to call tools. With this server, an app like Claude Desktop, Cursor or briar chat can read and change your knowledge blobs, read your runbook and run extract. It needs the mcp extra: pip install "briar-cli[mcp]". The Docker image has it.
Use it when
- You want to ask an AI app about your team's knowledge blobs.
- You want an app to run an extract for you, after you approve it.
- You want one shared briar server that remote apps can call.
The tools it offers
Tools that change something take confirm. By default they only preview what they would do. They act only when called with confirm=true.
| Tool | What it does |
|---|---|
version | Returns the briar version. |
knowledge_list | Lists blobs, with an optional name prefix. |
knowledge_get | Returns one blob's text, or null. |
knowledge_categories | Counts blobs per category. |
knowledge_put | Saves a blob. Needs confirm=true. |
knowledge_delete | Deletes a blob. Needs confirm=true. |
runbook_get | Returns the runbook as JSON. Keys show as env var names only. Needs --runbook. |
runbook_validate | Checks the runbook and reports what is wrong. Needs --runbook. |
mcp_server_set_enabled | Turns an MCP server in a company's runbook on or off. Needs --runbook and confirm=true. |
extract_run | Runs extractors for a company and merges them into the blob, like briar extract: the sections of the extractors that ran are replaced, the rest stay (since 1.1.83; before, it replaced the whole blob). Pass repo (a list of owner/repo) for the repo extractors; without it they are skipped. since_days and max_items work like --since-days and --max. These three need 1.1.84 or later. tracker and ticket_project (Jira keys, Linear teams) feed the ticket extractors since 1.1.94. Without confirm=true it only lists what would run. |
Examples
# For a local app: talk over stdin and stdout.$ briar mcp serve --runbook runbooks/acme.yaml
You get a server that waits for an app to start it. You do not run this by hand. You tell the app to run it, as below.
{"mcpServers": {"briar": {"command": "briar","args": ["mcp", "serve", "--runbook", "/home/dana/acme/runbooks/acme.yaml"]}}}
# For remote apps: HTTP on this machine only, no token.$ briar mcp serve --transport http# On the network: a token is a must.$ export BRIAR_MCP_TOKEN="$(openssl rand -hex 32)"$ briar mcp serve --transport http --host 0.0.0.0 --port 8765 --token-env BRIAR_MCP_TOKEN
You get the server at http://HOST:8765/mcp. With a token, each request must send Authorization: Bearer <the value of BRIAR_MCP_TOKEN>, or it gets 401.
Parameters
--transport TRANSPORTdefault: stdiostdiohttpstdio: the app starts briar and talks over stdin and stdout. http: briar listens on a port. Example: --transport http.--host HOSTdefault: 127.0.0.1http only. The address to listen on. Any address other than 127.0.0.1, localhost or ::1 needs --token-env, or briar refuses to start. Example: --host 0.0.0.0.--port PORTdefault: 8765http only. The port. Example: --port 9100.--token-env NAMEhttp only. The name of an env var that holds the token, not the token itself. That keeps the token out of your shell history. Off by default. Example: --token-env BRIAR_MCP_TOKEN.--store STOREdefault: filefilepostgres--store postgres.--root PATHdefault: ./knowledge--root ./kb.--runbook YAML--runbook runbooks/acme.yaml.briar chat
A chat with briar in your terminal. You type what you want in plain words. An LLM (the AI model) answers and calls briar's MCP tools for you. briar starts briar mcp serve in the background for this. Before any change, you see a preview and a Execute? [y/N] question. The model cannot say yes for you. It needs the mcp extra and a key for the LLM.
Use it when
- You want to ask what briar knows about a company.
- You want to fix a blob or run an extract without looking up flags.
Examples
# Start a chat with the default model (Anthropic).$ briar chat# Let it read and change a runbook too.$ briar chat --runbook runbooks/acme.yaml# Use OpenAI, with a set model.$ briar chat --llm openai --model gpt-4o
A short chat looks like this. The answer depends on your store.
you> which blobs do we have for acme?briar> You have knowledge:acme and knowledge:acme.q3 ...you> /exit
You get answers built from your own store. Quit with /exit, /quit or Ctrl-D. Each question gets up to 25 rounds of tool calls.
Parameters
--llm PROVIDERdefault: anthropicanthropicopenaigeminibedrockanthropic reads CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY. openai reads OPENAI_API_KEY. gemini reads GEMINI_API_KEY. bedrock uses your normal AWS login. With no key, chat stops and names the var to set. Example: --llm gemini.--model MODELclaude-sonnet-4-5, gpt-4o, gemini-2.5-pro, or anthropic.claude-sonnet-4-20250514-v1:0 on Bedrock. The model line under [agent] in .briar.toml also fills it. Example: --model claude-sonnet-4-6.--store STOREdefault: filefilepostgres--store postgres.--root PATHdefault: ./knowledge--root ./kb.--runbook YAML--runbook runbooks/acme.yaml.briar completion
Prints a script that lets your shell complete briar commands, subcommands and flag names when you press Tab. It does not complete flag values.
# See the script.$ briar completion bash# Turn it on for this shell. Add the line to ~/.bashrc or ~/.zshrc to keep it.$ eval "$(briar completion bash)"$ eval "$(briar completion zsh)"
You get Tab completion in that shell. The script holds a fixed list of names, so run the eval line again after you upgrade briar. The zsh script needs zsh's completion system (compinit) to be on.
SHELLrequiredbashzshbriar completion zsh.briar version
Prints the installed version, like briar-cli 1.1.75. The flags --version and -V print the same line. They print it before briar reads any config or starts telemetry, so they work even when your setup is broken.
$ briar version$ briar --version
Flags that work on every command
You can put these anywhere on the line, before or after the command.
--format FORMATdefault: tabletablejsonyamlcsvquiettable prints lists as a table and single records as JSON. json, yaml and csv do what they say. quiet prints only the id field of each row, one per line, for use with xargs. Rows with no id, like context blobs, print nothing. It only changes commands that print records: context put, list and categories, config show, doctor, telemetry, plan and runbook. Example: --format json or --format=yaml.--verbose, -vBRIAR_VERBOSE=1 does the same. BRIAR_LOG_LEVEL=INFO picks a level in between. Example: -v.--version, -Vbriar -V.$ briar context list --format json$ briar -v doctor$ briar --format=csv context list --prefix knowledge:
You get JSON, then the doctor table with debug logs, then a CSV of your knowledge blobs.
See also
- briar extract: writes the
knowledge:blobs thatcontext getreads. - Configuration: every
.briar.tomlkey and env var. - Auth, secrets and telemetry: log in, check keys, and see what usage data is sent.