Skip to content

Get started

Configuration

briar gets its settings from four places: the flags you type, env vars, a project file called .briar.toml, and your git remote. Keys and tokens only ever come from env vars. They never go in .briar.toml.

How briar picks a value

For each setting, briar takes the first source that has a value:

  1. A flag on the command line, like --company acme.
  2. An env var. Only two settings have one: BRIAR_COMPANY and BRIAR_STORE.
  3. The nearest .briar.toml.
  4. Your git origin remote. This only fills the repo owner and name.
  5. The built-in default of that command.

A value from steps 2 to 4 also makes a required flag optional. With company = "acme" in your project file, you can run briar extract with no --company. To see what each setting is and where it came from, run briar config show.

# The flag wins over BRIAR_COMPANY and .briar.toml.
$ BRIAR_COMPANY=globex briar extract --company acme --include active-work
# See every setting and its source.
$ briar config show

The first command runs for acme. The second prints a table of settings, values and sources.

The project file: .briar.toml

This file holds the values you would type on every command. briar looks for it in the folder you run from, then in each parent folder up to the root. It uses the first one it finds. In a folder, a .briar.toml wins over a pyproject.toml. A pyproject.toml counts only when it has a [tool.briar] table. If the file has a syntax error, briar logs a warning and ignores it.

Make one with briar init.

Every key

Keys that briar does not know are ignored. Watch the tables: a model line at the top level does nothing. It must sit under [agent].

KeyWhat it setsFlags it fills
companyYour name for the company. It is the ACME in JIRA_ACME_TOKEN. Env override: BRIAR_COMPANY.--company on extract, agent, plan, scaffold, auth and init
storeThe knowledge store: file or postgres. Env override: BRIAR_STORE.--store on extract, agent, plan, context, mcp serve, chat, init, and journal (see the note below)
rootThe folder of the file store. No env var.--root on extract, agent, plan, context, mcp serve, chat, and journal
trackerWhere tickets live: jira, github-issues, bitbucket-issues or linear.--tracker on extract, agent implement and plan run
reposA list of owner/repo names, like ["acme-co/acme-app", "acme-co/acme-api"].--repo on extract only
[repo] ownerThe repo owner (user or org), like acme-co.--owner on agent, plan run, scaffold and init
[repo] repoThe repo name, like acme-app. Extract gets owner/repo from it when repos is not set.--repo on extract, agent, plan run, scaffold and init
[repo] providerWhere the code lives: github or bitbucket.--provider on extract, agent and plan run
[agent] modelThe model name. Pick one your LLM provider knows, since it also fills chat and plan build.--model on agent, plan build, next and run, scaffold, and chat
[agent] git_user_nameThe name on the agent's commits.--git-user-name on agent and plan run
[agent] git_user_emailThe email on the agent's commits.--git-user-email on agent and plan run

briar journal keeps its own store

briar journal has its own --store and --root flags, and these keys do not fill them (since 1.1.92). Before, store = "postgres" made every journal command fail.

A full example

.briar.toml
company = "acme"
store = "postgres"
root = "./knowledge"
tracker = "jira"
repos = ["acme-co/acme-app", "acme-co/acme-api"]
[repo]
owner = "acme-co"
repo = "acme-app"
provider = "github"
[agent]
model = "claude-sonnet-4-6"
git_user_name = "acme-bot"
git_user_email = "[email protected]"

With this file, briar extract mines both repos into Postgres for acme, and briar agent implement --ticket-key ACME-42 works on acme-co/acme-app with that model and that commit author. The same keys can go in pyproject.toml, under [tool.briar]:

pyproject.toml
[tool.briar]
company = "acme"
store = "file"
[tool.briar.repo]
owner = "acme-co"
repo = "acme-app"

Owner and repo from git

When no flag, env var or file sets the owner and repo, briar reads git remote get-url origin. It understands both [email protected]:acme-co/acme-app.git and https://github.com/acme-co/acme-app. Commands that take a bare repo name get acme-app. Extract gets acme-co/acme-app. Outside a git checkout, or with no origin, nothing is filled in.

The knowledge store

The knowledge store holds your blobs: extract reports, saved plans and notes. There are two.

  • file: markdown files under ./knowledge (or --root). Good for one laptop. Nothing to set up.
  • postgres: two tables in a Postgres database. Good when a server and your laptop, or a team, share the same blobs. It keeps a history of every write.

Which store each command uses

CommandDefault when you set nothing
extract, agent, planpostgres when BRIAR_DATABASE_URL is set, else file
context, mcp serve, chat, initfile, even when BRIAR_DATABASE_URL is set
A runbook companyfile, unless its knowledge: block says store: postgres

To use Postgres everywhere on the command line, set BRIAR_STORE=postgres or put store = "postgres" in .briar.toml.

Setting up Postgres

Commands find the database URL in BRIAR_DATABASE_URL. A runbook company looks in three places, in order: the env var named by config.dsn_env in its knowledge: block, then BRIAR_ACME_DATABASE_URL (for acme), then BRIAR_DATABASE_URL. Plain postgresql:// and postgres:// URLs work.

briar does not make the tables on its own. An admin runs a one-time setup from Python. It makes the two tables and a briar_kb role that can only read and write them. There is no CLI command for it in 1.1.75.

import os
from briar.storage.postgres import StorePostgres
StorePostgres.bootstrap_admin(
os.environ["ADMIN_DATABASE_URL"], # connection string of an admin user
os.environ["BRIAR_KB_PASSWORD"], # the password to give the briar_kb role
)
# Then point briar at the database as briar_kb.
$ export BRIAR_DATABASE_URL="postgresql://briar_kb:${BRIAR_KB_PASSWORD}@db.acme.com:5432/briar"
$ briar doctor

You get store ok from doctor once the URL is set. Doctor does not connect. Run briar context list --store postgres to test the real connection.

The env vars briar reads for itself

These change how briar runs. Service keys come after, in Service keys. A yes or no var takes 1, true or yes, unless the table says otherwise.

Project defaults

VariableWhat it does
BRIAR_COMPANYFills every --company. Wins over .briar.toml.
BRIAR_STOREFills every knowledge --store (file or postgres). Wins over .briar.toml. Before 1.1.64 this was BRIAR_DEFAULT_STORE, which now means the key store only.

Knowledge store

VariableWhat it does
BRIAR_DATABASE_URLThe Postgres URL. Setting it also makes extract, agent and plan use Postgres by default.
BRIAR_ACME_DATABASE_URLA Postgres URL for one runbook company (here acme). Only runbooks read it.
BRIAR_PG_POOL_SIZEOpen database connections to keep per process. Default 4.
BRIAR_PG_POOL_OVERFLOWExtra connections allowed at busy times. Default 2.

Key stores and logins

VariableWhat it does
BRIAR_DEFAULT_STOREThe default --cred-store for briar auth, when it names a store. Else envfile.
BRIAR_SECRETS_FILEThe path of the env file. Without it, briar uses /etc/briar/secrets.env if it exists, else ~/.config/briar/secrets.env.
VAULT_ADDR, VAULT_TOKENWhere Vault is and how to log in, for the vault store.
BRIAR_GITHUB_CLIENT_IDThe GitHub OAuth app client ID. Needed only by briar auth login github-device.

Logging

VariableWhat it does
BRIAR_VERBOSEDebug logs on stderr, like --verbose.
BRIAR_LOG_LEVELDEBUG, INFO, WARNING or ERROR. Used when --verbose is off. Default WARNING.
BRIAR_LIB_DEBUGAlso show the debug logs of the libraries briar uses (AWS, HTTP and so on). They stay quiet by default, even with --verbose.

Journal

VariableWhat it does
BRIAR_JOURNALoff, 0 or no stops plan run and scaffold from writing sessions.
BRIAR_JOURNAL_STOREWhere sessions are kept. Only file today. Default file.
BRIAR_JOURNAL_ROOTThe journal folder. Default ./journal.
BRIAR_JOURNAL_SINKSA comma list of extra outputs. Only file today: a markdown copy in ./journal/published/. Default file. Unknown names are skipped.

Telemetry and updates

VariableWhat it does
DO_NOT_TRACK1 turns telemetry and the update check off. Wins over every other setting.
BRIAR_TELEMETRYoff, errors-only or full, for this run. Wins over the saved level. off also stops the update check.
BRIAR_SENTRY_DSNSend telemetry to your own Sentry project.
BRIAR_ENVThe Sentry environment tag. Default production.
BRIAR_NO_UPDATE_CHECKStop the daily PyPI check that prints "a newer version is out" on stderr.

Details are in briar telemetry.

Agent runs and alerts

VariableWhat it does
BRIAR_NO_DEFAULT_MCPDo not start the built-in think and time MCP servers in agent runs, like --no-default-mcp. Without the [mcp] extra, briar skips these servers anyway and logs one warning. This var hides that warning. The Docker image sets it to 1. Also takes on.
CIAny value: the agent does not borrow your machine's git name and email. Set them with flags, [agent] or the runbook.
BRIAR_NOTIFY_SINKSWhere to send an alert when a runbook task fails. See Failure alerts.

Where briar keeps its own files

VariableWhat it does
XDG_CONFIG_HOMEThe base for the env file, the telemetry level and the install ID. Default ~/.config, so files land in ~/.config/briar/.
XDG_CACHE_HOMEThe base for the update check cache. Default ~/.cache.

Service keys: the naming pattern

Each service key is an env var. Most names have three parts: the service, your company, and the field. With --company acme, the Jira URL is JIRA_ACME_URL. With --company globex it is JIRA_GLOBEX_URL. So one machine can hold keys for many companies at once.

briar makes the company part upper case and turns - into _: acme-co gives JIRA_ACME_CO_URL. A few keys have no company part, because one value serves every company: GITHUB_TOKEN, the LLM keys, TELEGRAM_BOT_TOKEN and the SMTP_* mail settings.

Let briar list what you need

You do not have to work out the names. Run briar secrets doctor on your runbooks to see each missing name. Or run briar auth login and let it write them.

The tables below use acme as the company.

Code hosts and trackers

ServiceEnv vars
GitHub (code, issues, projects)GITHUB_TOKEN, with no company part
Bitbucket Cloud (code, issues)BITBUCKET_ACME_USERNAME, BITBUCKET_ACME_APP_PASSWORD, BITBUCKET_ACME_WORKSPACE
Jira with an API tokenJIRA_ACME_URL, JIRA_ACME_EMAIL, JIRA_ACME_TOKEN
Jira with a browser sessionJIRA_ACME_URL, plus JIRA_ACME_TENANT_SESSION_TOKEN or JIRA_ACME_SESSION_TOKEN. Writes to Jira also need JIRA_ACME_XSRF_TOKEN. JIRA_ACME_USER_AGENT is optional.
Jira login kindJIRA_ACME_AUTH_KIND: token or session. When it is empty, briar uses the session if a session cookie var is set, else the token.
LinearLINEAR_ACME_TOKEN

Clouds

CloudHow briar logs in
AWSFirst AWS_ACME_ACCESS_KEY_ID and AWS_ACME_SECRET_ACCESS_KEY (plus AWS_ACME_SESSION_TOKEN for short-lived keys). If they are not set, a ~/.aws profile named acme, if there is one. Else the normal AWS chain: AWS env vars, SSO, or a server role. --aws-extract-profile names a profile by hand. The region is --aws-extract-region, default us-east-1.
Google CloudGoogle's default login: GOOGLE_APPLICATION_CREDENTIALS pointing at a service account file, or gcloud auth application-default login. Pass the project ID in --aws-extract-profile. Needs pip install "briar-cli[gcp]".
AzureAzure's default login: the Azure CLI, a service principal in env vars, or a managed identity. Pass the subscription ID in --aws-extract-profile. Needs pip install "briar-cli[azure]".

briar auth login aws-sso and aws-static also write AWS_ACME_REGION. In 1.1.75 extract does not read it, so pass --aws-extract-region when you are not in us-east-1.

Meeting notes

ServiceEnv vars
FirefliesFIREFLIES_ACME_API_KEY

Slack and Telegram

UseEnv vars
Read Slack threads for an agent (--slack-query)SLACK_ACME_TOKEN (the xoxc- token of a browser session) and SLACK_ACME_COOKIE_D (the d cookie)
Post to a Slack channel (runbook message or alert)SLACK_ACME_WEBHOOK_URL
Post to a Telegram chat (runbook message or alert)TELEGRAM_BOT_TOKEN, with no company part, and TELEGRAM_ACME_CHAT_ID

AI model providers

ProviderEnv vars
AnthropicCLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY. When both are set, the OAuth token wins. agent always runs on Anthropic.
OpenAIOPENAI_API_KEY. Needs pip install "briar-cli[openai]".
Google GeminiGEMINI_API_KEY. Needs pip install "briar-cli[gemini]".
AWS BedrockThe normal AWS chain (AWS env vars, profile, SSO, or a server role). It does not read the AWS_ACME_* vars.

Only plan build, plan next, plan run and chat let you pick a provider, with --llm.

Where keys are saved

briar auth login saves keys into a store. Pick it with --cred-store: envfile (the default, a local file), aws-secretsmanager, ssm or vault. Only the env file is loaded into the env when commands run. The full table, with paths and needs, is in The four stores.

$ briar auth login jira-token --company acme
$ briar auth login github-pat --cred-store vault
$ briar auth list --cred-store aws-secretsmanager

You get Jira keys in the env file, a GitHub token in Vault, and a list of key names in Secrets Manager.

Loading keys at start

Before each command, briar loads the env file into its env. It skips names you already set in your shell, so your shell wins. It skips -h and --version runs. On a server, systemd can load the same file with EnvironmentFile=. Then briar finds every name already set, which is fine.

# See which names the file holds. Sets nothing.
$ briar secrets bootstrap --dry-run

You get a count of names. See briar secrets bootstrap.

Failure alerts

When a runbook task fails (in runbook extract or runbook serve), briar can send an alert. List the places in BRIAR_NOTIFY_SINKS, comma separated. The alert title is briar: acme / weekly failed. The body is the reason and the first 1500 characters of the error. A place with no keys is skipped. An unknown name is logged and skipped. A failed send never stops the run.

NameEnv vars it needs
slackSLACK_ACME_WEBHOOK_URL
telegramTELEGRAM_BOT_TOKEN and TELEGRAM_ACME_CHAT_ID
emailSMTP_HOST, EMAIL_ACME_TO (a comma list), and a sender: EMAIL_FROM, or else SMTP_USER. Also SMTP_PORT (default 587), SMTP_USER, SMTP_PASSWORD, and SMTP_STARTTLS (on unless set to false).
pagerdutyPAGERDUTY_ACME_ROUTING_KEY. Sent as a warning.

Alerts are not the same as a runbook's messages: block. That block lists the places an agent may post to while it works. See messages in the runbook.

Example setups

A laptop

# Add the [mcp] extra for mcp serve, chat and runbook MCP servers.
$ pip install briar-cli
# Inside your repo, once.
$ briar init --company acme
$ briar auth login github-pat
$ briar auth login jira-token --company acme
$ export ANTHROPIC_API_KEY=sk-ant-... # your own key
$ briar doctor

You get a .briar.toml, your GitHub and Jira keys in ~/.config/briar/secrets.env, and a doctor report with no warnings. Put the export line in your shell profile, or in the env file, to keep it.

A server that runs the scheduler

/etc/briar/secrets.env (mode 600)
# Values in angle brackets are yours to fill in.
GITHUB_TOKEN=<github token>
JIRA_ACME_URL=https://acme.atlassian.net
JIRA_ACME_TOKEN=<jira api token>
ANTHROPIC_API_KEY=<anthropic key>
BRIAR_DATABASE_URL=postgresql://briar_kb:<password>@db.acme.com:5432/briar
BRIAR_NOTIFY_SINKS=slack,email
SLACK_ACME_WEBHOOK_URL=<slack incoming webhook url>
SMTP_HOST=smtp.acme.com
BRIAR_LOG_LEVEL=INFO
/etc/systemd/system/briar.service (part)
[Service]
EnvironmentFile=/etc/briar/secrets.env
WorkingDirectory=/opt/briar
ExecStart=/usr/local/bin/briar runbook serve /opt/briar/runbooks
$ sudo chmod 600 /etc/briar/secrets.env
$ briar secrets doctor --examples /opt/briar/runbooks

You get a scheduler that reads its keys from one locked file, writes to Postgres, and sends Slack and email alerts. Doctor shows any key that is still missing.

A CI job

# Keys come from your CI secret settings, as env vars.
$ export BRIAR_COMPANY=acme
$ export DO_NOT_TRACK=1
$ briar extract --include ci-health --include pr-hygiene --out-json report.json

You get the blob knowledge:acme plus a JSON copy in report.json, with no telemetry and no update check. The repo comes from the git remote of the CI checkout, so no .briar.toml is needed.

Where to go next