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.mdwhen you pass--merge-claude-md. - MCP clients and
briar chat, throughbriar 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.
| Agent | Sections it takes from the blob |
|---|---|
agent implement | codebase-conventions, code-hotspots, reviewer-profile, active-work, pr-archaeology, meeting-digest |
agent prfix | codebase-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 agentand 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
- Briar picks the extractors: the ones you name with
--include, or all 23. - It hands each one the shared flags you gave, like
--repoor--since-days. - 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. - Each extractor that runs writes one section. A section with no data is dropped, and briar prints
<name>: no data. - 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: readspyproject.toml,package.jsonandgo.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 (likefix: 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,.editorconfigand 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 gcpor--cloud azureit 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. NeedsFIREFLIES_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
<!-- 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:acmebecomes<root>/knowledge/acme.md. The root is./knowledge; change it with--root. - Postgres store: pick it with
--store postgres. It needsBRIAR_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_runmerges the same way since 1.1.83. To start over, delete it first withbriar 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
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 COMPANYrequiredacme: 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--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 filefilepostgresfile 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>/ or ending in .md is used as a file path as is. Example: --blob-name archive:acme-2026q3.--root PATHdefault: ./knowledge--store postgres. Can also come from root in .briar.toml. Example: --root docs/knowledge.--out-json PATHdefault: none (no JSON file)--out-json out/acme.json.--merge-claude-mddefault: off.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.mdCLAUDE.md to update. Used only with --merge-claude-md. Example: --claude-md-path docs/CLAUDE.md.--advanced-help--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 originrepos 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 owncode-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-max, -max-commits and -limit rows in Advanced flags for each default. Example: --max 50.--top-n Ndefault: each extractor's ownreviewer-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 ownreviewer-profile (20), review-nits (30) and pr-hygiene (30). Example: --sample 10.--authors-allow LOGINdefault: none (no filter)pr-archaeology and active-work use it. Example: --authors-allow alice.--authors-block LOGINdefault: none (no filter)--authors-block 'dependabot[bot]'.--assignees-allow LOGINdefault: none (no filter)--assignees-allow alice.--assignees-block LOGINdefault: none (no filter)--assignees-block bob.Which service to read
--provider {github,bitbucket}default: githubgithubbitbucketprovider under [repo] in .briar.toml. Example: --provider bitbucket.--tracker {jira,github-issues,bitbucket-issues,linear}default: jirajiragithub-issuesbitbucket-issueslinearactive-tickets and ticket-archaeology. Can also come from tracker in .briar.toml. Example: --tracker linear.--cloud {aws,gcp,azure}default: awsawsgcpazureaws-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: firefliesfirefliesmeeting-digest. Fireflies is the only one today. Example: --meeting fireflies.Cloud flags (aws-infra)
--aws-extract-profile NAMEdefault: none~/.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-1us-central1) or Azure (like eastus). Example: --aws-extract-region us-west-2.--aws-extract-service SERVICEdefault: allecslambdalogsrdssqstagging-inventorytagging-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
--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)--meeting-attendee-allow [email protected].Flags for one extractor
--prhygiene-large-loc Ndefault: 400pr-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 branchrepo-governance: the branch whose protection rules to check. Example: --gov-branch release.--stale-days Ndefault: 14stale-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
-reporeplaces--repo. Endings-max,-max-commitsand-limitreplace--max. Endings-pr-sampleand-diffstat-samplereplace--sample. The endings-since-days,-top-n,-authors-*and-assignees-*match the shared flag of the same name. - A
-repoflag 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-projectand--ticket-archaeology-projectprint 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)
| Flag | What it changes | Default | Example |
|---|---|---|---|
--provider | The code host for the repo extractors. Also in -h. | github | --provider bitbucket |
--cloud | The cloud for aws-infra. Also in -h. | aws | --cloud azure |
--tracker | The tracker for the two ticket extractors. Also in -h. | jira | --tracker github-issues |
--meeting | The meeting tool for meeting-digest. Also in -h. | fireflies | --meeting fireflies |
pr-archaeology
| Flag | What it changes | Default | Example |
|---|---|---|---|
--pr-repo | The repo to read merged PRs from. Repeatable. | none | --pr-repo acme-co/acme-app |
--pr-max | The most merged PRs to read per repo. | 100 | --pr-max 50 |
--pr-authors-allow | Keep only PRs by these authors. Repeatable. | none | --pr-authors-allow alice |
--pr-authors-block | Drop PRs by these authors. Repeatable. | none | --pr-authors-block 'renovate[bot]' |
--pr-assignees-allow | Keep only PRs assigned to one of these people. Repeatable. | none | --pr-assignees-allow alice |
--pr-assignees-block | Drop PRs assigned to these people. Repeatable. | none | --pr-assignees-block bob |
active-work
| Flag | What it changes | Default | Example |
|---|---|---|---|
--active-repo | The repo to list open PRs from. Repeatable. | none | --active-repo acme-co/acme-app |
--active-authors-allow | Keep only open PRs by these authors. Repeatable. | none | --active-authors-allow alice |
--active-authors-block | Drop open PRs by these authors. Repeatable. | none | --active-authors-block 'renovate[bot]' |
--active-assignees-allow | Keep only open PRs assigned to one of these people. Repeatable. | none | --active-assignees-allow alice |
--active-assignees-block | Drop open PRs assigned to these people. Repeatable. | none | --active-assignees-block bob |
github-deployments and codebase-conventions
| Flag | What it changes | Default | Example |
|---|---|---|---|
--deploy-repo | For github-deployments: the repo to read deploys and CI runs from. Repeatable. | none | --deploy-repo acme-co/acme-app |
--conventions-repo | For codebase-conventions: the repo whose build files to read. Repeatable. | none | --conventions-repo acme-co/acme-app |
active-tickets and ticket-archaeology
| Flag | What it changes | Default | Example |
|---|---|---|---|
--ticket-project | For 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-project | For ticket-archaeology: the project to read closed tickets from. Same format. Repeatable. | none | --ticket-archaeology-project ACME |
--ticket-max | For ticket-archaeology: the most closed tickets to read per project. Jira returns at most 100. | 100 | --ticket-max 50 |
reviewer-profile
| Flag | What it changes | Default | Example |
|---|---|---|---|
--reviewer-repo | The repo whose reviewers to describe. Repeatable. | none | --reviewer-repo acme-co/acme-app |
--reviewer-pr-sample | How many recent merged PRs to read comments from, per repo. | 20 | --reviewer-pr-sample 40 |
--reviewer-top-n | How many reviewers to describe, per repo. | 5 | --reviewer-top-n 3 |
code-hotspots
| Flag | What it changes | Default | Example |
|---|---|---|---|
--hotspots-repo | The repo to read commits from. Repeatable. | none | --hotspots-repo acme-co/acme-app |
--hotspots-since-days | How many days of commits to read. | 30 | --hotspots-since-days 60 |
--hotspots-max-commits | The most commits to read per repo. | 100 | --hotspots-max-commits 50 |
--hotspots-top-n | How many busy files to show per repo. | 10 | --hotspots-top-n 20 |
aws-infra
| Flag | What it changes | Default | Example |
|---|---|---|---|
--aws-extract-profile | AWS profile, Google Cloud project ID or Azure subscription ID. Also in -h. | none | --aws-extract-profile acme-prod |
--aws-extract-region | The region to read. Also in -h. | us-east-1 | --aws-extract-region eu-west-1 |
--aws-extract-service | Which AWS services to list. Repeatable. Also in -h. | all | --aws-extract-service lambda |
meeting-digest
| Flag | What it changes | Default | Example |
|---|---|---|---|
--meeting-since-days | How many days of meetings to read. | 7 | --meeting-since-days 14 |
--meeting-max | The most meetings to list. Fireflies returns at most 50. | 25 | --meeting-max 10 |
--meeting-attendee-allow | Keep only meetings with one of these attendees. Repeatable. Also in -h. | none | --meeting-attendee-allow [email protected] |
defect-hotspots
| Flag | What it changes | Default | Example |
|---|---|---|---|
--risk-repo | The repo to score. Repeatable. | none | --risk-repo acme-co/acme-app |
--risk-since-days | How many days of commits to read. | 90 | --risk-since-days 180 |
--risk-max-commits | The most commits to read per repo. | 200 | --risk-max-commits 100 |
--risk-top-n | How many risky files to show per repo. | 10 | --risk-top-n 5 |
review-nits
| Flag | What it changes | Default | Example |
|---|---|---|---|
--nits-repo | The repo to read review comments from. Repeatable. | none | --nits-repo acme-co/acme-app |
--nits-pr-sample | How many recent merged PRs to read, per repo. | 30 | --nits-pr-sample 60 |
--nits-top-n | How 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
| Flag | What it changes | Default | Example |
|---|---|---|---|
--prhygiene-repo | The repo to check. Repeatable. | none | --prhygiene-repo acme-co/acme-app |
--prhygiene-max | How many merged PRs to use for the "no review comment" share. | 100 | --prhygiene-max 200 |
--prhygiene-diffstat-sample | How 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-loc | Changed lines above which a PR counts as large. Also in -h. | 400 | --prhygiene-large-loc 600 |
ci-health
| Flag | What it changes | Default | Example |
|---|---|---|---|
--cihealth-repo | The repo to read CI runs from. Repeatable. | none | --cihealth-repo acme-co/acme-app |
--cihealth-limit | The most CI runs to read per repo. | 100 | --cihealth-limit 50 |
dependency-health
| Flag | What it changes | Default | Example |
|---|---|---|---|
--deps-repo | The repo to read Dependabot alerts from. Repeatable. | none | --deps-repo acme-co/acme-app |
--deps-max | The most alerts to read per repo. | 200 | --deps-max 50 |
code-scanning
| Flag | What it changes | Default | Example |
|---|---|---|---|
--scan-repo | The repo to read code scanning alerts from. Repeatable. | none | --scan-repo acme-co/acme-app |
--scan-max | The most alerts to read per repo. | 200 | --scan-max 50 |
--scan-top-n | How many rules to show per repo. | 10 | --scan-top-n 5 |
repo-governance
| Flag | What it changes | Default | Example |
|---|---|---|---|
--gov-repo | The repo to check. Repeatable. | none | --gov-repo acme-co/acme-app |
--gov-branch | The branch whose protection rules to check. Also in -h. | default branch | --gov-branch release |
revert-signals
| Flag | What it changes | Default | Example |
|---|---|---|---|
--revert-repo | The repo to read commits from. Repeatable. | none | --revert-repo acme-co/acme-app |
--revert-since-days | How many days of commits to read. | 90 | --revert-since-days 30 |
--revert-max-commits | The most commits to read per repo. | 200 | --revert-max-commits 100 |
stale-prs
| Flag | What it changes | Default | Example |
|---|---|---|---|
--stale-repo | The repo to list open PRs from. Repeatable. | none | --stale-repo acme-co/acme-app |
--stale-max | The most open PRs to read per repo. | 100 | --stale-max 50 |
--stale-days | Days open after which a PR is stale. Also in -h. | 14 | --stale-days 30 |
test-discipline
| Flag | What it changes | Default | Example |
|---|---|---|---|
--testdisc-repo | The repo whose file tree to read. Repeatable. | none | --testdisc-repo acme-co/acme-app |
--testdisc-top-n | How many files with no test to show per repo. | 10 | --testdisc-top-n 25 |
todo-density
| Flag | What it changes | Default | Example |
|---|---|---|---|
--todo-repo | The repo to search. Repeatable. | none | --todo-repo acme-co/acme-app |
--todo-max | The most search results to read per repo. GitHub returns at most 100. | 200 | --todo-max 100 |
--todo-top-n | How many files to show per repo. | 10 | --todo-top-n 5 |
release-cadence
| Flag | What it changes | Default | Example |
|---|---|---|---|
--release-repo | The repo to read releases from. Repeatable. | none | --release-repo acme-co/acme-app |
--release-max | The most releases to read per repo. | 100 | --release-max 20 |
commit-message-quality
| Flag | What it changes | Default | Example |
|---|---|---|---|
--msg-repo | The repo to read commit titles from. Repeatable. | none | --msg-repo acme-co/acme-app |
--msg-since-days | How many days of commits to read. | 90 | --msg-since-days 30 |
--msg-max-commits | The 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.
| Service | What to set | Used by |
|---|---|---|
| GitHub | GITHUB_TOKEN | The 19 repo extractors. Also the ticket extractors with --tracker github-issues. |
| Bitbucket | BITBUCKET_ACME_USERNAME, BITBUCKET_ACME_APP_PASSWORD, BITBUCKET_ACME_WORKSPACE | Repo extractors with --provider bitbucket. Ticket extractors with --tracker bitbucket-issues. |
| Jira | JIRA_ACME_URL plus JIRA_ACME_EMAIL and JIRA_ACME_TOKEN (or a browser session token) | The ticket extractors (Jira is the default tracker). |
| Linear | LINEAR_ACME_TOKEN | Ticket extractors with --tracker linear. |
| AWS | AWS_ACME_ACCESS_KEY_ID and AWS_ACME_SECRET_ACCESS_KEY, or an AWS profile, or your normal AWS login | aws-infra. |
| Google Cloud | Google default login, plus the project ID in --aws-extract-profile | aws-infra --cloud gcp. |
| Azure | Azure default login, plus the subscription ID in --aws-extract-profile | aws-infra --cloud azure. |
| Fireflies | FIREFLIES_ACME_API_KEY | meeting-digest. |
| Postgres | BRIAR_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
skippedline, and the others still run. aws-infrais the exception. It always runs, because the AWS library ships with briar. Without AWS access, its section saysUNREACHABLEand shows the error. Leave it out with--includeif 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 forAWS_ACME_*keys. Then it tries a~/.awsprofile namedacme, then your normal AWS login (env vars, SSO, instance role). - With
--aws-extract-profile acme-prod, briar looks forAWS_ACME_PROD_*keys, then theacme-prodprofile.
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-hotspotsanddefect-hotspotslook at no more than 50 commits, whatever--maxsays. todo-densitymakes 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 independency-health. You cannot change these. - A wide
--since-daysor a big--maxmeans more API calls. Start small on a large repo.
On Bitbucket
dependency-health,code-scanning,release-cadence,todo-densityandtest-disciplinecome back empty.repo-governancechecks the files, but always shows branch protection as missing.ci-healthreads 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--maxlimit. - 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
--repoand expecting Jira tickets. Jira needs--ticket-project ACME. - Writing
--include a,b. Give one name per--include. - Using
--cloud gcpwithout--aws-extract-region. The default region is an AWS name. - Reading with
briar context getafter 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
- briar runbook: run the same extractors on a schedule from a YAML file.
- briar secrets doctor: check which tokens each extractor can use.
- briar context: read, list and delete saved blobs.
- Plugin registries: every provider, tracker, cloud and AWS service briar knows.