Skip to content
Briar
View on GitHub

CLI reference

Utilities.

Four commands you'll reach for after extracting and running plans: context for direct knowledge-blob CRUD, dashboard for the read-only HTML status page, journal for inspecting past runs, and version for sanity checks. Below them: project setup (init, config show, doctor), the MCP server (mcp serve), chat, and shell completion.

briar context

Direct CRUD over the knowledge / plan blobs in the configured store. Same backends as everywhere else (file / postgres), same blob names.

Common flags

--store {file,postgres}default: file
filepostgres
Knowledge store backend.
--root PATHdefault: ./knowledge
Local file root.

$ briar context put

briar context put [--content TEXT | --from-file PATH] [--category CAT] BLOB_NAME

Create or update a blob.

blob_namerequired
Positional. E.g. knowledge:acme.
--content TEXT
Inline content. Use - for stdin.
--from-file PATH
Read content from this path.
--category CAT
Explicit category. Default: derived from the blob-name prefix (the part before :).
$ cat notes.md | briar context put knowledge:acme --content -
$ briar context put knowledge:acme.q3 --from-file ./plan-notes.md

$ briar context get

briar context get BLOB_NAME

Print the markdown body to stdout.

$ briar context get knowledge:acme | less
$ briar context get plan:q3 > /tmp/plan.md

$ briar context list

briar context list [--prefix PREFIX]

List stored blobs.

--prefix STRING
Filter to names starting with this prefix.
$ briar context list
$ briar context list --prefix knowledge:
$ briar context list --prefix plan:

$ briar context delete

briar context delete [--yes] BLOB_NAME

Remove a blob. Prompts unless --yes.

$ briar context delete knowledge:acme.archive-2025q4 --yes

$ briar context categories

briar context categories

Print distinct category prefixes — e.g. knowledge, plan.

briar dashboard

Serve a read-only HTML status page for the host: host health (disk, memory, load), scheduler liveness and recent cycles from the scheduler log, the schedules declared in the runbook YAMLs, GitHub API quota, the deployed git commit, and network connectivity. Designed to run alongside briar runbook serve on the same host.

--host ADDRESSdefault: 127.0.0.1
Bind address. Default is loopback-only; pass --host 0.0.0.0 to expose publicly, but verify firewall + auth first.
--port PORTdefault: 8080
Bind port.
--examples DIRdefault: ./examples
Directory of runbook YAMLs (schedules view).
--log-file PATHdefault: /var/log/briar/scheduler.log
Path to the scheduler log.
--disk-path PATHdefault: /
Filesystem path used for disk-usage stats.
--repo-path PATHdefault: .
Path of the deployed git checkout.
--once
Render once to stdout and exit (CI-friendly snapshot).
$ briar dashboard \
    --host 0.0.0.0 --port 8080 \
    --examples runbooks/ \
    --repo-path /opt/briar-scheduler \
    --log-file /var/log/briar/scheduler.log

briar journal

Inspect decision-journal sessions recorded by other briar commands. Today scaffold (scaffold.*) and plan run (plan.run) open sessions. Each session is a structured stream of events such as selector decisions and per-card results.

$ briar journal list

briar journal list [--store {file}] [--root PATH] [--command FILTER] [--limit N]
--store {file}default: file
file
Journal store backend.
--root PATHdefault: ./journal
Root directory for the file-backed store.
--command PREFIX
Filter by command prefix (e.g. scaffold., plan.run).
--limit Ndefault: 50
Cap on sessions returned.
$ briar journal list --command plan.run --limit 5
$ briar journal list --command scaffold.

$ briar journal show

briar journal show [--store {file}] [--root PATH] SESSION_ID

Pretty-print one session as markdown.

$ briar journal show 7a3b8c2d

$ briar journal export

briar journal export [--as {markdown,json}] [--out PATH] SESSION_ID

Write one session to a path.

--as {markdown,json}default: markdown
markdownjson
Serialization for the exported session. (Named --as, not --format, so it doesn't collide with the global --format flag.)
--out PATHdefault: -
Output path. Use - for stdout.
$ briar journal export 7a3b8c2d --as json --out /tmp/last-run.json

briar init

Write a starter .briar.toml (see Configuration). The repo owner and name are read from the git origin remote when present. Fails if the file exists, unless --force.

--company COMPANY
Company key to write into the config.
--store {file,postgres}default: file
filepostgres
Default knowledge store backend.
--owner OWNER
Repo owner. Default: inferred from git origin.
--repo REPO
Repo name. Default: inferred from git origin.
--path PATHdefault: ./.briar.toml
Output path.
--force
Overwrite an existing file.
$ briar init --company acme
$ briar init --company acme --store postgres --force

briar config show

Print each project setting (company, store, root, tracker, owner, repo, provider, model, git_user_name, git_user_email) with its resolved value and where it came from: env var, config file, git origin, or unset. Read-only.

$ briar config show

briar doctor

Check the local setup: Python version, briar version, project config file, git remote, an LLM key (ANTHROPIC_API_KEY, OPENAI_API_KEY or GEMINI_API_KEY), GITHUB_TOKEN, and the store (postgres needs a DSN). Missing pieces are warnings; it exits non-zero only on a hard failure, so it works in CI.

$ briar doctor

briar mcp serve

Start an MCP (Model Context Protocol) server that exposes briar's knowledge, runbook config and extraction as tools, so an MCP host (Claude Desktop, Cursor, briar chat) can drive briar. Tools: version, knowledge_list, knowledge_get, knowledge_categories, knowledge_put, knowledge_delete, runbook_get, runbook_validate, mcp_server_set_enabled, extract_run. Tools that change things only preview unless called with confirm=true. Needs the mcp extra: pip install "briar-cli[mcp]".

--transport {stdio,http}default: stdio
stdiohttp
stdio for local hosts, http (Streamable HTTP) for remote or browser clients.
--host HOSTdefault: 127.0.0.1
HTTP bind host (http only).
--port PORTdefault: 8765
HTTP bind port (http only).
--token-env NAME
Name of the env var that holds the bearer token required on HTTP requests. Binding a non-loopback host without a token is refused (http only).
--store {file,postgres}default: file
filepostgres
Knowledge store the tools work on.
--root PATHdefault: ./knowledge
Local knowledge file root (file store only).
--runbook YAML
Runbook YAML for the config tools. Omit to turn the config tools off.
$ briar mcp serve --runbook examples/multi_company.yaml
$ MCP_TOKEN=... briar mcp serve --transport http --host 0.0.0.0 --token-env MCP_TOKEN

briar chat

Interactive assistant in the terminal. It starts briar mcp serve as a subprocess, binds its tools, and runs an LLM tool-use loop so you can ask for changes in plain language. The model can never confirm a change on its own: each gated tool runs as a dry run first, you see the preview, and it only runs for real after you approve. Needs the mcp extra.

--llm PROVIDERdefault: anthropic
anthropicopenaigeminibedrock
LLM provider.
--model MODEL
Override the provider's default model.
--store {file,postgres}default: file
filepostgres
Knowledge store backend.
--root PATHdefault: ./knowledge
Local knowledge file root.
--runbook YAML
Runbook YAML for the config tools. Omit to turn them off.
$ briar chat --runbook examples/multi_company.yaml

briar completion

Print a shell-completion script for bash or zsh.

$ eval "$(briar completion bash)"
$ eval "$(briar completion zsh)"

briar version

Print the installed CLI version (briar-cli <semver>). briar --version (or -V) prints the same line.

$ briar version

Global flags

Every command takes --format (table, json, yaml, csv, quiet; default table for lists, json for single records) and --verbose / -v (DEBUG logging, also BRIAR_VERBOSE=1). Both can go anywhere on the command line.

See also