Skip to content

CLI reference

briar extract

briar extract reads your tools (code repos, issue tracker, cloud account, meeting notes). It writes what it finds into one markdown file. You, Claude Code and briar's agents read it later.

What it does

Briar calls that markdown file a knowledge blob: a named document that briar saves for you. For company acme it is named knowledge:acme and lands in ./knowledge/knowledge/acme.md.

Each kind of data comes from one extractor. An extractor is a small reader with one job, like "list open pull requests" or "find files that break often". There are 23 of them. You pick the ones you want with --include, or run them all.

Who reads the blob

  • You, with briar context get knowledge:acme.
  • Claude Code, through CLAUDE.md when you pass --merge-claude-md.
  • MCP clients and briar chat, through briar mcp serve.
  • The plan selector, with briar plan build --with-knowledge.
  • Briar's coding agents, but only a few sections. See the table below.

briar agent implement and briar agent prfix add to their prompt only the sections their role uses. All other sections stay out of their prompt.

AgentSections it takes from the blob
agent implementcodebase-conventions, code-hotspots, reviewer-profile, active-work, pr-archaeology, meeting-digest
agent prfixcodebase-conventions, code-hotspots, reviewer-profile, active-work, meeting-digest

The agents also get the ticket, the PR review or a meeting. Briar fetches those live when the agent starts, not with extract. The other 17 extractors never reach a coding agent. They are for you, Claude Code, MCP clients, chat and the plan selector.

Use it when

  • You set up briar on a repo and want agents to know its test runner, linter and reviewers.
  • You are about to run briar agent and want it to see fresh data: open PRs, reviewers, busy files, recent meetings.
  • You want one health report: CI pass rate, stale PRs, open Dependabot alerts.
  • You want Claude Code to know your project without loading a big file in every session.

Usage

$ briar extract

briar extract --company COMPANY [--include EXTRACTOR ...] [--repo OWNER/REPO ...] [--since-days N] [--max N] [--top-n N] [--sample N] [--authors-allow LOGIN ...] [--authors-block LOGIN ...] [--assignees-allow LOGIN ...] [--assignees-block LOGIN ...] [--store {file,postgres}] [--blob-name NAME] [--root PATH] [--out-json PATH] [--merge-claude-md] [--claude-md-path PATH] [--provider {github,bitbucket}] [--tracker {jira,github-issues,bitbucket-issues,linear}] [--cloud {aws,gcp,azure}] [--meeting {fireflies}] [--meeting-attendee-allow EMAIL ...] [--aws-extract-profile NAME] [--aws-extract-region REGION] [--aws-extract-service SERVICE ...] [--prhygiene-large-loc N] [--gov-branch BRANCH] [--stale-days N] [--advanced-help]

Only --company is required. You can skip it when .briar.toml or BRIAR_COMPANY sets it. A flag with ... can be given more than once.

How it works

  1. Briar picks the extractors: the ones you name with --include, or all 23.
  2. It hands each one the shared flags you gave, like --repo or --since-days.
  3. Each extractor checks that it has what it needs: a repo or project to read, and a token. If not, briar prints skipped <name> and moves on.
  4. Each extractor that runs writes one section. A section with no data is dropped, and briar prints <name>: no data.
  5. Briar joins the sections into one markdown file and saves it. If no section has data, it stops with the error nothing extracted.

Progress lines go to stderr, so stdout stays clean for scripts. When --repo is not given, briar takes the repo from .briar.toml, then from your git origin remote. So inside a repo folder, most extractors work with no extra flags.

Pick your extractors

Below are all 23 extractors, grouped by the question they answer. Pass a name to --include. Repeat the flag to run several: --include ci-health --include stale-prs. Only six of them reach briar's coding agents (see Who reads the blob).

Most of them read a code repo. They need a token for your code host: GITHUB_TOKEN for GitHub, or the BITBUCKET_ACME_* trio with --provider bitbucket. The full token list is in Good to know.

Understand the code and its reviewers

  • codebase-conventions: reads pyproject.toml, package.json and go.mod. It reports the language, test runner, linter, formatter and migration tool. It knows Python, JavaScript, TypeScript and Go. Needs a repo and a code host token.
  • code-hotspots: finds the files changed most in recent commits. For each one it lists the files that often change with it, such as its test. Default: last 30 days, 100 commits, top 10 files. Needs a repo and a code host token.
  • reviewer-profile: reads review comments on recent merged PRs. For the top reviewers it shows PRs reviewed, comments per PR, the files they comment on most and a few sample comments. Needs a repo and a code host token.
  • review-nits: sorts review comments into 8 common asks and counts each one. The asks are: missing test, naming, magic value, error handling, typing, docs, simplify, and edge case. A frequent ask is a good lint rule to add. Needs a repo and a code host token.
  • commit-message-quality: checks recent commit titles. It shows the share that follow Conventional Commits (like fix: handle empty cart), the share over 72 or under 10 characters, and the median length. Needs a repo and a code host token.
# language, test runner, linter
$ briar extract --company acme --include codebase-conventions
# files that change together
$ briar extract --company acme --include code-hotspots
# what each reviewer asks for
$ briar extract --company acme --include reviewer-profile
# the asks reviewers repeat
$ briar extract --company acme --include review-nits
# how commit titles are written
$ briar extract --company acme --include commit-message-quality

Learn from history

  • pr-archaeology: reads recent merged PRs. It shows how many, the median time from open to merge, the top authors and the most requested reviewers. You can filter by author or assignee. Needs a repo and a code host token.
  • ticket-archaeology: reads recently closed tickets. It shows a rough time to close (from created to last update), top reporters, assignees, labels and ticket types. Needs a tracker project and a tracker token (Jira by default).
  • release-cadence: reads published releases. It shows how many, the latest tag and date, the median days between releases and the number of prereleases. GitHub only.
# merged PR patterns
$ briar extract --company acme --include pr-archaeology
# closed Jira tickets in project ACME
$ briar extract --company acme --include ticket-archaeology --ticket-archaeology-project ACME
# how often the repo ships
$ briar extract --company acme --include release-cadence

Find risky code

  • defect-hotspots: ranks files by risk. The score grows with how often a file changes, how many bug-fix commits touched it, and its size. A bug-fix commit has a word like fix, bug, hotfix, patch, revert or regression in its title. Default: last 90 days, 200 commits, top 10 files.
  • revert-signals: counts revert and hotfix commits (words like revert, hotfix, rollback, quick fix). It lists the files those commits touched most. These are files that slipped past review and CI. Default: last 90 days, 200 commits.
  • todo-density: searches the code for TODO, FIXME and HACK. It lists the files with the most. It uses one code search, so treat the totals as a rough count. GitHub only.
  • test-discipline: compares the number of test files to source files. It lists source files that have no test with a matching name. It is a rough check. GitHub only.
# files most likely to break
$ briar extract --company acme --include defect-hotspots
# reverts and hotfixes
$ briar extract --company acme --include revert-signals
# where the TODOs are
$ briar extract --company acme --include todo-density
# source files with no test
$ briar extract --company acme --include test-discipline

Check repo health

  • pr-hygiene: looks at recent merged PRs. It shows the median PR size in changed lines, and the size that 90% of PRs stay under. It also shows the share of large PRs (over 400 lines), the share merged with no review comment, and the median time to the first review comment.
  • ci-health: reads recent CI runs. It shows the pass rate, the median run time, and flaky workflows. A workflow is flaky when it both passed and failed on the same branch, or needed a retry. Made for GitHub Actions; see On Bitbucket.
  • dependency-health: lists open Dependabot alerts by severity (critical, high, medium, low) and the top 10 packages. GitHub only. Your token must be allowed to read Dependabot alerts.
  • code-scanning: lists open code scanning alerts (for example from CodeQL), grouped by rule, with one example file per rule. GitHub only.
  • repo-governance: checks branch protection (required reviews, status checks, admin rules, code owner review). It also checks for CODEOWNERS, a pre-commit config, .editorconfig and a linter config. Every repo gets a section, even when all of it is missing.
# PR size and review habits
$ briar extract --company acme --include pr-hygiene
# CI pass rate and flaky workflows
$ briar extract --company acme --include ci-health
# open Dependabot alerts
$ briar extract --company acme --include dependency-health
# open code scanning alerts
$ briar extract --company acme --include code-scanning
# branch protection and project files
$ briar extract --company acme --include repo-governance

See work in flight

  • active-work: lists up to 25 open PRs per repo, with author, branch, draft state and comment count. It tells agents what work is already open, so they do not collide with it. You can filter by author or assignee.
  • active-tickets: lists up to 25 open tickets per project, with status, reporter and assignee. Needs a tracker project and a tracker token (Jira by default).
  • stale-prs: lists open PRs older than 14 days, oldest first, up to 20 per repo. Age counts from when the PR was opened, not from its last update.
# open PRs
$ briar extract --company acme --include active-work
# open Jira tickets in project ACME
$ briar extract --company acme --include active-tickets --ticket-project ACME
# PRs open for more than 14 days
$ briar extract --company acme --include stale-prs

Know what runs in production

  • aws-infra: lists your cloud resources. On AWS: ECS services, RDS databases, Lambda functions, SQS queues, the 10 biggest CloudWatch log groups, and every tagged resource. With --cloud gcp or --cloud azure it lists compute, databases, queues and logs. Needs a cloud login.
  • github-deployments: lists deploy environments, the last 10 deployments and the last 5 CI runs. Despite the name, it also works with --provider bitbucket.
# AWS resources in us-east-1
$ briar extract --company acme --include aws-infra
# environments and recent deploys
$ briar extract --company acme --include github-deployments

Catch up on meetings

  • meeting-digest: lists Fireflies meetings from the last 7 days, up to 25. Each one has the date, attendees, the summary (first 600 characters) and up to 8 action items. Needs FIREFLIES_ACME_API_KEY.
# meetings from the last two weeks
$ briar extract --company acme --include meeting-digest --since-days 14

Ticket-based extractors need a project

active-tickets and ticket-archaeology skip themselves until you name a project. For Jira, pass the project key with --ticket-project ACME or --ticket-archaeology-project ACME. For Linear, pass the team key the same way. For GitHub Issues and Bitbucket Issues, --repo works too.

Examples

Your first run

Run this inside your repo folder with GITHUB_TOKEN set. Briar takes the repo from .briar.toml or git.

$ briar extract --company acme

The progress lines look like this (your list will differ):

running pr-archaeology ...
running aws-infra ...
running active-work ...
skipped active-tickets (not available in this env)
...
stale-prs: no data
...
wrote blob 'knowledge:acme' (... bytes, ... sections) via store=file

You get ./knowledge/knowledge/acme.md, with one section for each extractor that found data.

A few extractors at once

$ briar extract --company acme \
--include codebase-conventions \
--include reviewer-profile \
--include ci-health \
--repo acme-co/acme-app

You get a blob with three sections: the repo's tools, its reviewers and its CI health. Nothing else runs.

A time window

$ briar extract --company acme \
--include defect-hotspots \
--include revert-signals \
--include commit-message-quality \
--since-days 30 \
--max 100

You get the risky files, reverts and commit habits of the last 30 days. Each extractor reads at most 100 commits.

Filter by author or assignee

$ briar extract --company acme \
--include pr-archaeology \
--include active-work \
--authors-block 'dependabot[bot]' \
--assignees-allow alice

You get merged and open PRs without Dependabot's PRs, and only those assigned to alice. Quote names with brackets, or your shell may change them.

Your cloud resources

$ briar extract --company acme \
--include aws-infra \
--aws-extract-profile acme-prod \
--aws-extract-region us-west-2 \
--aws-extract-service ecs \
--aws-extract-service rds

You get the ECS services and RDS databases in us-west-2, read with the acme-prod AWS profile. For Google Cloud, put the project ID in --aws-extract-profile and always set the region:

$ briar extract --company acme \
--include aws-infra \
--cloud gcp \
--aws-extract-profile acme-prod-123 \
--aws-extract-region us-central1

You get the compute, databases, queues and logs of that project.

Save to Postgres

$ briar extract --company acme --store postgres
$ briar context get knowledge:acme --store postgres

The first command saves the blob in the database that BRIAR_DATABASE_URL points to. The second prints it. The blob name is the same; only the place changes.

Feed Claude Code through CLAUDE.md

$ briar extract --company acme \
--include codebase-conventions \
--include defect-hotspots \
--include ci-health \
--merge-claude-md

You get the full result in .briar/knowledge/acme.md. Your CLAUDE.md gets a short list of topics and a line telling Claude to read that file when a task needs it. Claude Code loads CLAUDE.md in every session, so the list stays short. The details load only when needed.

Safe to run again

The list sits between <!-- BEGIN briar-knowledge --> and <!-- END briar-knowledge -->. A new run replaces only that block. Your own text in CLAUDE.md stays. The detail file is always written to local disk, even with --store postgres.

JSON for scripts

$ briar extract --company acme \
--include ci-health \
--include stale-prs \
--out-json out/acme.json
$ jq '.sections[].data' out/acme.json

You get the usual markdown blob plus out/acme.json. The JSON has the company, the time, and each section with its title, text and raw numbers in data.

Where the results go

Briar saves the blob in a store: local files (the default) or Postgres. The blob name is knowledge:<company> unless you set --blob-name.

  • File store: a name like knowledge:acme becomes <root>/knowledge/acme.md. The root is ./knowledge; change it with --root.
  • Postgres store: pick it with --store postgres. It needs BRIAR_DATABASE_URL. When that variable is set, Postgres is already the default.
  • Since 1.1.82 a run merges into the blob with the same name: the sections of the extractors it ran are replaced (or dropped when they found nothing), and every other section stays. Before 1.1.82 each run replaced the whole blob. The MCP tool extract_run merges the same way since 1.1.83. To start over, delete it first with briar context delete knowledge:acme. Postgres also keeps every old version in a history table.

Read the blob back, or list what you have:

$ briar context get knowledge:acme
$ briar context list --prefix knowledge:

briar context uses the file store by default, even when BRIAR_DATABASE_URL is set. Add --store postgres to read from the database, or set BRIAR_STORE=postgres once. If you used --root, pass the same --root here. See briar context.

Keep a snapshot

$ briar extract --company acme --blob-name archive:acme-2026q3

You get ./knowledge/archive/acme-2026q3.md, and knowledge:acme stays as it was.

Coding agents read every blob that starts with knowledge:acme

The coding agents load every blob whose name starts with knowledge:acme and take their sections from all of them. A snapshot named knowledge:acme.old could feed old data to them. Use another prefix for snapshots, like archive:.

All parameters

briar extract -h shows 29 flags. They are all below. Each one can also come from an env var or .briar.toml where noted. A flag on the command line always wins.

Main flags

--company COMPANYrequired
Your company or workspace name. It sets the blob name, the title of the markdown, and the names of the token env vars briar looks for (for acme: JIRA_ACME_TOKEN and so on). BRIAR_COMPANY or company in .briar.toml can set it for you. Example: --company acme.
--include EXTRACTORdefault: all available
Which extractor to run. Give one name per flag and repeat the flag for more. Allowed values: the 23 names in Pick your extractors. With no --include, briar tries all 23 and skips the ones that lack a repo, project or token. Example: --include ci-health --include stale-prs.
--store {file,postgres}default: postgres if BRIAR_DATABASE_URL is set, else file
filepostgres
Where to save the blob. file writes markdown files. postgres writes to the database in BRIAR_DATABASE_URL. You can also set it with BRIAR_STORE or store in .briar.toml. The old name --storage still works but is hidden. Example: --store postgres.
--blob-name NAMEdefault: knowledge:<company>
The name to save the blob under. In the file store, a name with a / or ending in .md is used as a file path as is. Example: --blob-name archive:acme-2026q3.
--root PATHdefault: ./knowledge
The folder for the file store. Ignored with --store postgres. Can also come from root in .briar.toml. Example: --root docs/knowledge.
--out-json PATHdefault: none (no JSON file)
Also write the result as JSON to this path. Briar creates the folder if needed. The markdown blob is still saved as usual. Example: --out-json out/acme.json.
--merge-claude-mddefault: off
Also write the full result to .briar/knowledge/<company>.md and add a short topic list to CLAUDE.md. A new run replaces only briar's block. If CLAUDE.md does not exist, briar creates it. Example: --merge-claude-md.
--claude-md-path PATHdefault: ./CLAUDE.md
Which CLAUDE.md to update. Used only with --merge-claude-md. Example: --claude-md-path docs/CLAUDE.md.
--advanced-help
Print the 69 advanced per-extractor flags and exit. It works on its own, without --company. Example: briar extract --advanced-help.

-h or --help prints the short help and exits.

Shared flags

These flags reach every extractor you run that reads that kind of value. When you leave one out, each extractor uses its own default (listed in Advanced flags).

--repo OWNER/REPOdefault: from .briar.toml, then git origin
The repo to read. Repeat it for more repos. It feeds every extractor that reads a repo. It also names the tracker project for GitHub Issues and Bitbucket Issues, but never for Jira or Linear. When you leave it out, briar uses repos or [repo] from .briar.toml, then your git origin remote. A --repo you pass replaces that default (since 1.1.91; before, it was added to it). Example: --repo acme-co/acme-app.
--since-days Ndefault: each extractor's own
How many days back to look. It reaches code-hotspots (30), defect-hotspots (90), revert-signals (90), commit-message-quality (90) and meeting-digest (7). Example: --since-days 30.
--max Ndefault: each extractor's own
The most items to read per repo or project. The item depends on the extractor: merged PRs, commits, CI runs, alerts, releases, tickets or meetings. It reaches 14 extractors. See the -max, -max-commits and -limit rows in Advanced flags for each default. Example: --max 50.
--top-n Ndefault: each extractor's own
How many results to show per repo: files, reviewers, rules or ask types. It reaches reviewer-profile (5), code-hotspots (10), defect-hotspots (10), review-nits (15), code-scanning (10), test-discipline (10) and todo-density (10). Example: --top-n 5.
--sample Ndefault: each extractor's own
How many recent PRs to look at closely, one by one. It reaches reviewer-profile (20), review-nits (30) and pr-hygiene (30). Example: --sample 10.
--authors-allow LOGINdefault: none (no filter)
Keep only PRs written by these people. Repeat it for more names. Only pr-archaeology and active-work use it. Example: --authors-allow alice.
--authors-block LOGINdefault: none (no filter)
Drop PRs written by these people, such as bots. Repeat it for more names. Same two extractors. Example: --authors-block 'dependabot[bot]'.
--assignees-allow LOGINdefault: none (no filter)
Keep only PRs assigned to one of these people. Same two extractors. Bitbucket PRs have no assignee, so this drops all of them. Example: --assignees-allow alice.
--assignees-block LOGINdefault: none (no filter)
Drop PRs assigned to any of these people. Same two extractors. Example: --assignees-block bob.

Which service to read

--provider {github,bitbucket}default: github
githubbitbucket
The code host for the 19 extractors that read a repo. Can also come from provider under [repo] in .briar.toml. Example: --provider bitbucket.
--tracker {jira,github-issues,bitbucket-issues,linear}default: jira
jiragithub-issuesbitbucket-issueslinear
The issue tracker for active-tickets and ticket-archaeology. Can also come from tracker in .briar.toml. Example: --tracker linear.
--cloud {aws,gcp,azure}default: aws
awsgcpazure
The cloud for aws-infra. For Google Cloud or Azure, install the extra first: pip install 'briar-cli[gcp]' or 'briar-cli[azure]'. Example: --cloud gcp.
--meeting {fireflies}default: fireflies
fireflies
The meeting tool for meeting-digest. Fireflies is the only one today. Example: --meeting fireflies.

Cloud flags (aws-infra)

--aws-extract-profile NAMEdefault: none
On AWS: the profile name in ~/.aws to log in with. On Google Cloud: the project ID. On Azure: the subscription ID. Google Cloud and Azure skip aws-infra without it. Example: --aws-extract-profile acme-prod.
--aws-extract-region REGIONdefault: us-east-1
The region to read. The default is an AWS region, so set it yourself for Google Cloud (like us-central1) or Azure (like eastus). Example: --aws-extract-region us-west-2.
--aws-extract-service SERVICEdefault: all
ecslambdalogsrdssqstagging-inventory
Which AWS services to list. Repeat it for more. The first five each read one service. tagging-inventory lists every resource that has at least one tag, across all services. AWS only. Example: --aws-extract-service ecs.

tagging-inventory keeps the blob small

The markdown gets only a count per service. The full list (ARN, type, region, tags) goes into the section's data, which you can save with --out-json. Untagged resources do not show up. In a runbook, knowledge.config.inventory can also save that list as its own blob. See Runbook YAML.

Meeting flag (meeting-digest)

--meeting-attendee-allow EMAILdefault: none (every meeting)
Keep only meetings where at least one of these emails attended. Repeat it for more emails. With none, briar lists every meeting your Fireflies key can see. Example: --meeting-attendee-allow [email protected].

Flags for one extractor

--prhygiene-large-loc Ndefault: 400
For pr-hygiene: a PR counts as large when lines added plus lines deleted go over this. Example: --prhygiene-large-loc 600.
--gov-branch BRANCHdefault: provider's default branch
For repo-governance: the branch whose protection rules to check. Example: --gov-branch release.
--stale-days Ndefault: 14
For stale-prs: a PR open longer than this many days is stale. Example: --stale-days 30.

Advanced flags

Briar has 69 more flags, one set per extractor. They are hidden from -h. Print them with briar extract --advanced-help. Use one when two extractors in the same run need different values.

  • An advanced flag wins over the shared flag, for its own extractor only.
  • The name tells you which shared flag it replaces. A name ending in -repo replaces --repo. Endings -max, -max-commits and -limit replace --max. Endings -pr-sample and -diffstat-sample replace --sample. The endings -since-days, -top-n, -authors-* and -assignees-* match the shared flag of the same name.
  • A -repo flag left empty is filled from --repo. That is why its default says "none".
  • Using a flag that replaces a shared one prints a note on stderr. The flag still works. --ticket-project and --ticket-archaeology-project print no note: they are the normal way to name a Jira or Linear project.
  • Eleven of these flags also show in -h. They are marked "Also in -h".

Service choice (shared by many extractors)

FlagWhat it changesDefaultExample
--providerThe code host for the repo extractors. Also in -h.github--provider bitbucket
--cloudThe cloud for aws-infra. Also in -h.aws--cloud azure
--trackerThe tracker for the two ticket extractors. Also in -h.jira--tracker github-issues
--meetingThe meeting tool for meeting-digest. Also in -h.fireflies--meeting fireflies

pr-archaeology

FlagWhat it changesDefaultExample
--pr-repoThe repo to read merged PRs from. Repeatable.none--pr-repo acme-co/acme-app
--pr-maxThe most merged PRs to read per repo.100--pr-max 50
--pr-authors-allowKeep only PRs by these authors. Repeatable.none--pr-authors-allow alice
--pr-authors-blockDrop PRs by these authors. Repeatable.none--pr-authors-block 'renovate[bot]'
--pr-assignees-allowKeep only PRs assigned to one of these people. Repeatable.none--pr-assignees-allow alice
--pr-assignees-blockDrop PRs assigned to these people. Repeatable.none--pr-assignees-block bob

active-work

FlagWhat it changesDefaultExample
--active-repoThe repo to list open PRs from. Repeatable.none--active-repo acme-co/acme-app
--active-authors-allowKeep only open PRs by these authors. Repeatable.none--active-authors-allow alice
--active-authors-blockDrop open PRs by these authors. Repeatable.none--active-authors-block 'renovate[bot]'
--active-assignees-allowKeep only open PRs assigned to one of these people. Repeatable.none--active-assignees-allow alice
--active-assignees-blockDrop open PRs assigned to these people. Repeatable.none--active-assignees-block bob

github-deployments and codebase-conventions

FlagWhat it changesDefaultExample
--deploy-repoFor github-deployments: the repo to read deploys and CI runs from. Repeatable.none--deploy-repo acme-co/acme-app
--conventions-repoFor codebase-conventions: the repo whose build files to read. Repeatable.none--conventions-repo acme-co/acme-app

active-tickets and ticket-archaeology

FlagWhat it changesDefaultExample
--ticket-projectFor active-tickets: the project to list open tickets from. Use a Jira project key (upper case), a Linear team key, or owner/repo for GitHub or Bitbucket Issues. Repeatable.none--ticket-project ACME
--ticket-archaeology-projectFor ticket-archaeology: the project to read closed tickets from. Same format. Repeatable.none--ticket-archaeology-project ACME
--ticket-maxFor ticket-archaeology: the most closed tickets to read per project. Jira returns at most 100.100--ticket-max 50

reviewer-profile

FlagWhat it changesDefaultExample
--reviewer-repoThe repo whose reviewers to describe. Repeatable.none--reviewer-repo acme-co/acme-app
--reviewer-pr-sampleHow many recent merged PRs to read comments from, per repo.20--reviewer-pr-sample 40
--reviewer-top-nHow many reviewers to describe, per repo.5--reviewer-top-n 3

code-hotspots

FlagWhat it changesDefaultExample
--hotspots-repoThe repo to read commits from. Repeatable.none--hotspots-repo acme-co/acme-app
--hotspots-since-daysHow many days of commits to read.30--hotspots-since-days 60
--hotspots-max-commitsThe most commits to read per repo.100--hotspots-max-commits 50
--hotspots-top-nHow many busy files to show per repo.10--hotspots-top-n 20

aws-infra

FlagWhat it changesDefaultExample
--aws-extract-profileAWS profile, Google Cloud project ID or Azure subscription ID. Also in -h.none--aws-extract-profile acme-prod
--aws-extract-regionThe region to read. Also in -h.us-east-1--aws-extract-region eu-west-1
--aws-extract-serviceWhich AWS services to list. Repeatable. Also in -h.all--aws-extract-service lambda

meeting-digest

FlagWhat it changesDefaultExample
--meeting-since-daysHow many days of meetings to read.7--meeting-since-days 14
--meeting-maxThe most meetings to list. Fireflies returns at most 50.25--meeting-max 10
--meeting-attendee-allowKeep only meetings with one of these attendees. Repeatable. Also in -h.none--meeting-attendee-allow [email protected]

defect-hotspots

FlagWhat it changesDefaultExample
--risk-repoThe repo to score. Repeatable.none--risk-repo acme-co/acme-app
--risk-since-daysHow many days of commits to read.90--risk-since-days 180
--risk-max-commitsThe most commits to read per repo.200--risk-max-commits 100
--risk-top-nHow many risky files to show per repo.10--risk-top-n 5

review-nits

FlagWhat it changesDefaultExample
--nits-repoThe repo to read review comments from. Repeatable.none--nits-repo acme-co/acme-app
--nits-pr-sampleHow many recent merged PRs to read, per repo.30--nits-pr-sample 60
--nits-top-nHow many ask types to show per repo. There are only 8 types, so values above 8 change nothing.15--nits-top-n 3

pr-hygiene

FlagWhat it changesDefaultExample
--prhygiene-repoThe repo to check. Repeatable.none--prhygiene-repo acme-co/acme-app
--prhygiene-maxHow many merged PRs to use for the "no review comment" share.100--prhygiene-max 200
--prhygiene-diffstat-sampleHow many PRs to open one by one for size and first review time. Each one costs extra API calls.30--prhygiene-diffstat-sample 10
--prhygiene-large-locChanged lines above which a PR counts as large. Also in -h.400--prhygiene-large-loc 600

ci-health

FlagWhat it changesDefaultExample
--cihealth-repoThe repo to read CI runs from. Repeatable.none--cihealth-repo acme-co/acme-app
--cihealth-limitThe most CI runs to read per repo.100--cihealth-limit 50

dependency-health

FlagWhat it changesDefaultExample
--deps-repoThe repo to read Dependabot alerts from. Repeatable.none--deps-repo acme-co/acme-app
--deps-maxThe most alerts to read per repo.200--deps-max 50

code-scanning

FlagWhat it changesDefaultExample
--scan-repoThe repo to read code scanning alerts from. Repeatable.none--scan-repo acme-co/acme-app
--scan-maxThe most alerts to read per repo.200--scan-max 50
--scan-top-nHow many rules to show per repo.10--scan-top-n 5

repo-governance

FlagWhat it changesDefaultExample
--gov-repoThe repo to check. Repeatable.none--gov-repo acme-co/acme-app
--gov-branchThe branch whose protection rules to check. Also in -h.default branch--gov-branch release

revert-signals

FlagWhat it changesDefaultExample
--revert-repoThe repo to read commits from. Repeatable.none--revert-repo acme-co/acme-app
--revert-since-daysHow many days of commits to read.90--revert-since-days 30
--revert-max-commitsThe most commits to read per repo.200--revert-max-commits 100

stale-prs

FlagWhat it changesDefaultExample
--stale-repoThe repo to list open PRs from. Repeatable.none--stale-repo acme-co/acme-app
--stale-maxThe most open PRs to read per repo.100--stale-max 50
--stale-daysDays open after which a PR is stale. Also in -h.14--stale-days 30

test-discipline

FlagWhat it changesDefaultExample
--testdisc-repoThe repo whose file tree to read. Repeatable.none--testdisc-repo acme-co/acme-app
--testdisc-top-nHow many files with no test to show per repo.10--testdisc-top-n 25

todo-density

FlagWhat it changesDefaultExample
--todo-repoThe repo to search. Repeatable.none--todo-repo acme-co/acme-app
--todo-maxThe most search results to read per repo. GitHub returns at most 100.200--todo-max 100
--todo-top-nHow many files to show per repo.10--todo-top-n 5

release-cadence

FlagWhat it changesDefaultExample
--release-repoThe repo to read releases from. Repeatable.none--release-repo acme-co/acme-app
--release-maxThe most releases to read per repo.100--release-max 20

commit-message-quality

FlagWhat it changesDefaultExample
--msg-repoThe repo to read commit titles from. Repeatable.none--msg-repo acme-co/acme-app
--msg-since-daysHow many days of commits to read.90--msg-since-days 30
--msg-max-commitsThe most commits to read per repo.200--msg-max-commits 100

Good to know

Tokens each service needs

Briar reads tokens from env vars. In the names below, ACME is your --company in capitals, with - turned into _. briar auth login can save them for you. Details are in Configuration.

ServiceWhat to setUsed by
GitHubGITHUB_TOKENThe 19 repo extractors. Also the ticket extractors with --tracker github-issues.
BitbucketBITBUCKET_ACME_USERNAME, BITBUCKET_ACME_APP_PASSWORD, BITBUCKET_ACME_WORKSPACERepo extractors with --provider bitbucket. Ticket extractors with --tracker bitbucket-issues.
JiraJIRA_ACME_URL plus JIRA_ACME_EMAIL and JIRA_ACME_TOKEN (or a browser session token)The ticket extractors (Jira is the default tracker).
LinearLINEAR_ACME_TOKENTicket extractors with --tracker linear.
AWSAWS_ACME_ACCESS_KEY_ID and AWS_ACME_SECRET_ACCESS_KEY, or an AWS profile, or your normal AWS loginaws-infra.
Google CloudGoogle default login, plus the project ID in --aws-extract-profileaws-infra --cloud gcp.
AzureAzure default login, plus the subscription ID in --aws-extract-profileaws-infra --cloud azure.
FirefliesFIREFLIES_ACME_API_KEYmeeting-digest.
PostgresBRIAR_DATABASE_URL--store postgres.

Check which tokens briar can see before you run:

$ briar secrets doctor

When a token is missing

  • The extractor is skipped with a skipped line, and the others still run.
  • aws-infra is the exception. It always runs, because the AWS library ships with briar. Without AWS access, its section says UNREACHABLE and shows the error. Leave it out with --include if you do not use AWS.
  • Briar only checks that a token is set, not that it works. A wrong token shows up later, as an error or as an empty section.
  • On AWS without --aws-extract-profile, briar looks for AWS_ACME_* keys. Then it tries a ~/.aws profile named acme, then your normal AWS login (env vars, SSO, instance role).
  • With --aws-extract-profile acme-prod, briar looks for AWS_ACME_PROD_* keys, then the acme-prod profile.

Limits and API costs

  • Commit-based extractors read the file list of the newest 50 commits only. Each one costs one extra API call. So code-hotspots and defect-hotspots look at no more than 50 commits, whatever --max says.
  • todo-density makes one GitHub code search, with at most 100 results. GitHub allows only about 10 code searches a minute.
  • GitHub calls retry up to 3 times and time out after 30 seconds.
  • Some sizes are fixed: 25 open PRs or tickets per repo or project, 20 stale PRs, 10 deployments, 5 CI runs in github-deployments, and 10 listed alerts in dependency-health. You cannot change these.
  • A wide --since-days or a big --max means more API calls. Start small on a large repo.

On Bitbucket

  • dependency-health, code-scanning, release-cadence, todo-density and test-discipline come back empty.
  • repo-governance checks the files, but always shows branch protection as missing.
  • ci-health reads Pipelines runs, but its numbers are not reliable there yet. It expects GitHub's result names, so the pass rate can show 0.
  • The commit extractors ignore --since-days. They read the newest commits up to the --max limit.
  • PRs have no assignee, so the assignee filters do not fit.

In Docker

briar extract works in the iklob1/briar image. So do the coding agents (see Agents in Docker).

$ docker run --rm \
-v "$PWD":/work -w /work \
-v "$HOME/.config/briar":/home/briar/.config/briar \
-e GITHUB_TOKEN \
iklob1/briar:1.1.75 extract --company acme --repo acme-co/acme-app

You get ./knowledge/knowledge/acme.md in your folder. With the repo in .briar.toml you can leave out --repo. Reading it from your origin remote also works. On Linux that needs 1.1.79 or later: older images refused a folder owned by another user than the container's (uid 1000).

Common mistakes

  • Passing --repo and expecting Jira tickets. Jira needs --ticket-project ACME.
  • Writing --include a,b. Give one name per --include.
  • Using --cloud gcp without --aws-extract-region. The default region is an AWS name.
  • Reading with briar context get after saving to Postgres. Add --store postgres.
  • If branch protection shows as missing on GitHub, check your token. A token that cannot read protection settings looks the same as no protection.

See also