CLI reference

briar extract

Mine live state from GitHub / Bitbucket / AWS / Jira / Linear / Sentry / meeting transcripts into a markdown knowledge blob written to local disk (or Postgres). The blob is named knowledge:<company> by default and becomes the source of truth other commands splice into agent prompts.

Synopsis

$ briar extract --company COMPANY [--include EXTRACTOR ...] [--store {file,postgres}]
              [--blob-name NAME] [--root PATH] [--out-json PATH]
              [--merge-claude-md] [--claude-md-path PATH] [--advanced-help]
              [--repo OWNER/REPO ...] [--since-days N] [--max N] [--top-n N] [--sample N]
              [--authors-allow|--authors-block|--assignees-allow|--assignees-block LOGIN ...]
              [<provider flags>] [<extractor-specific flags>]

Available extractors

Twenty-three scheduled extractors ship today. Each one is independent. If its required credentials are missing, it is skipped (a skipped <name> line goes to stderr) and the rest of the pipeline runs unchanged. If every extractor comes back empty, the command fails with nothing extracted.

Context & activity

active-tickets — open tracker tickets per project (Jira / GitHub Issues / Bitbucket Issues / Linear).
active-work — open PRs + recent activity from the configured repo provider.
aws-infra — AWS / GCP / Azure inventory: compute, databases, queues, log groups.
code-hotspots — files churned most often in the last N days; high-risk surface area.
codebase-conventions — language / framework / test-runner / migration-tool detection.
github-deployments — recent deployment events from GitHub's deployments API.
meeting-digest — Fireflies transcript summaries with attendee filters.
pr-archaeology — merged PRs with titles, descriptions, review patterns.
reviewer-profile — who reviews what, how fast, what they typically catch.
ticket-archaeology — closed tickets with resolutions, useful for context on recurring bugs.

Code quality & engineering health

Thirteen extractors mine git history and the repo-host API for engineering-quality signals. All take --provider github|bitbucket and the shared --repo owner/repo flag (repeatable). See agents/extract.md for the full per-extractor flag reference.

defect-hotspots — files most likely to break, scored by churn × bug-fixes × size.
pr-hygiene — PR size distribution, large-PR rate, rubber-stamp rate, time-to-first-review.
review-nits — phrases reviewers repeat across PRs; candidates to codify as lint rules.
revert-signals — reverts and emergency fixes; fragile areas the test/review net missed.
commit-message-quality — conventional-commits adherence and subject-line hygiene.
stale-prs — open PRs idle beyond a threshold; the review backlog.
ci-health — pass rate, flaky workflows, run-duration trend.
dependency-health — open dependency vulnerabilities by severity (Dependabot).
code-scanning — open static-analysis findings grouped by rule and file.
repo-governance — branch protection + presence of CODEOWNERS / pre-commit / linter config.
test-discipline — test-to-source file ratio and source files without an obvious test.
release-cadence — how often the repo ships: release frequency and recency.
todo-density — count of TODO / FIXME / HACK markers and the files carrying the most.

Cherry-pick with --include

Without --include, every extractor with valid credentials runs. Pass --include <name> (repeatable) to run only specific extractors.

Examples

Full extract for a company

$ briar extract --company acme

Writes knowledge:acme to ./knowledge/knowledge/acme.md. Runs every extractor whose credentials are configured.

Specific extractors with filters

$ briar extract --company acme \
    --include pr-archaeology \
    --include reviewer-profile \
    --repo acme/widgets \
    --repo acme/api \
    --max 50 \
    --authors-block dependabot \
    --authors-block renovate

The shared flags feed every included extractor that reads that concept. Here --max and --authors-block reach pr-archaeology only, because reviewer-profile has no such knob. The old per-extractor spellings (--pr-repo, --pr-max, ...) still work but print a deprecation note.

Write to Postgres

$ briar extract --company acme --store postgres

Requires BRIAR_DATABASE_URL (or the per-company override). The blob name is unchanged — only the backend differs.

Custom blob name (archive snapshot)

$ briar extract --company acme \
    --blob-name knowledge:acme.archive-2026q1

Non-AWS cloud

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

The flag names read AWS-flavoured because the AWS provider shipped first. For GCP --aws-extract-profile carries the project ID; for Azure it carries the subscription ID.

Code-quality signals

$ briar extract --company acme \
    --include defect-hotspots \
    --include pr-hygiene \
    --include ci-health \
    --include review-nits \
    --repo acme/widgets

One --repo (repeatable) feeds every included extractor. They read git history plus the repo-host API, with no extra credentials beyond the provider token already in use. To point one extractor at a different repo, use its override flag (for example --risk-repo); see briar extract --advanced-help.

Feed CLAUDE.md — read on demand

$ briar extract --company acme \
    --include defect-hotspots \
    --include ci-health \
    --repo acme/widgets \
    --merge-claude-md

Writes the full bundle to .briar/knowledge/acme.md and splices a short topic index into CLAUDE.md. Because CLAUDE.md auto-loads into every Claude Code session but the detail file does not, the agent reads the detail only when a task touches one of the listed topics — knowledge on demand, without a per-session context cost.

Non-destructive, re-runnable

The index lives inside a  …  block. Re-running replaces only briar's block and leaves any hand-written CLAUDE.md content untouched. The detail file is written locally even with --store postgres, since the reference resolves from the project root.

Core flags

--company COMPANYrequired

Company name. Drives the markdown title, the default blob name, and the per-company env-var interpolation (JIRA_{COMPANY}_TOKEN, etc.).

--include EXTRACTOR

active-ticketsactive-workaws-infraci-healthcode-hotspotscode-scanningcodebase-conventionscommit-message-qualitydefect-hotspotsdependency-healthgithub-deploymentsmeeting-digestpr-archaeologypr-hygienerelease-cadencerepo-governancerevert-signalsreview-nitsreviewer-profilestale-prstest-disciplineticket-archaeologytodo-density

Which extractor to run. Repeatable. Omit to run every extractor whose credentials are present.

--store {file,postgres}default: postgres if BRIAR_DATABASE_URL is set, else file

filepostgres

Where to write the result. Postgres requires BRIAR_DATABASE_URL. The old spelling --storage is still accepted as a hidden alias.

--blob-name NAMEdefault: knowledge:<company>

Storage blob name. Useful for snapshots — knowledge:acme.archive-2026q1 won't clobber knowledge:acme.

--root PATHdefault: ./knowledge

Local file root. Only used when --store=file.

--out-json PATH

Parallel JSON output path. The markdown still lands in the configured store; JSON is a sidecar useful for piping into downstream tooling.

--merge-claude-md

Also merge a knowledge index into CLAUDE.md so Claude Code sessions can read the full detail on demand. Writes the bundle to .briar/knowledge/<company>.md and splices a short, marker-bounded topic index into CLAUDE.md — re-runs replace only briar's block. Off by default.

--claude-md-path PATHdefault: ./CLAUDE.md

Which CLAUDE.md to merge the index into. Only used with --merge-claude-md.

--advanced-help

Print the full list of per-extractor override flags (hidden from -h) and exit.

Common extractor options

One shared flag per concept. Each value is passed to every extractor selected with --include that reads that concept. When none of these is given, each extractor uses its own default (listed under the per-extractor sections below).

--repo OWNER/REPO

Repository (or tracker project) to mine. Repeatable. Feeds every included extractor's repo or project list. When unset, it is filled from repos or [repo] in .briar.toml, then from the local git origin remote.

--since-days N

Lookback window in days (history-based extractors).

--max N

Max items or commits to inspect per repo.

--top-n N

How many results to show per repo.

--sample N

How many recent PRs to sample per repo.

--authors-allow LOGIN

Only include items whose author is in this list. Repeatable. Today only pr-archaeology and active-work apply author filters.

--authors-block LOGIN

Exclude items whose author is in this list. Repeatable. Same two extractors.

--assignees-allow LOGIN

Accepted, but no extractor filters on it yet: the normalised PR shape has no assignee, so these values are ignored. Repeatable.

--assignees-block LOGIN

Accepted but ignored today, like --assignees-allow. Repeatable.

Per-extractor overrides

The per-extractor flags below (--pr-repo, --hotspots-top-n, ...) are hidden from -h but still work. An explicit override wins over the shared flag for that one extractor. Using one prints a deprecation note; --ticket-project and --ticket-archaeology-project are the exception and stay fully supported.

Provider flags

Pick which provider implementation the extractors talk to.

--provider {github,bitbucket}default: github

githubbitbucket

Repository provider used by active-work, pr-archaeology, reviewer-profile, code-hotspots, codebase-conventions, and all thirteen code-quality extractors.

--cloud {aws,gcp,azure}default: aws

awsgcpazure

Cloud provider used by aws-infra.

--tracker {jira,github-issues,bitbucket-issues,linear}default: jira

jiragithub-issuesbitbucket-issueslinear

Tracker provider used by active-tickets and ticket-archaeology.

--meeting {fireflies}default: fireflies

fireflies

Meeting provider used by meeting-digest.

pr-archaeology flags

--pr-repo owner/repo

Repository slug to mine. Repeatable.

--pr-max Ndefault: 100

Max merged PRs per repo.

--pr-authors-allow LOGIN

Only include PRs whose author is in this list. Repeatable.

--pr-authors-block LOGIN

Exclude PRs by author. Repeatable. Useful for bot exclusion (dependabot, renovate).

--pr-assignees-allow LOGIN

Accepted but ignored today (no assignee on the normalised PR shape). Repeatable.

--pr-assignees-block LOGIN

Accepted but ignored today. Repeatable.

AWS / cloud flags

--aws-extract-profile PROFILE

Local AWS profile name (falls back to the default boto3 credential chain). For GCP/Azure this carries the project ID / subscription ID.

--aws-extract-region REGIONdefault: us-east-1

AWS region to inspect. For GCP/Azure this is the matching region / location.

--aws-extract-service {ecs,lambda,logs,rds,sqs,tagging-inventory}

ecslambdalogsrdssqstagging-inventory

Which AWS services to include in the inventory. Repeatable. Default: all of them. The first five describe one service each; tagging-inventory walks the Resource Groups Tagging API to enumerate every tagged resource across all services.

Account-wide inventory, without prompt bloat

tagging-inventory keeps the knowledge blob small — only per-service counts go in the markdown body, while the full per-resource detail (ARN, type, region, tags) rides in the section's structured data. Persist it with the JSON sidecar (--out-json), or set knowledge.config.inventory: "true" in a runbook to write a byte-stable inventory:<company> companion blob that only changes when the estate drifts. Tagged resources only — untagged need AWS Config / Resource Explorer.

active-work flags

--active-repo owner/repo

Repository slug to scan for active work. Repeatable.

--active-authors-allow LOGIN

Only include items by author. Repeatable.

--active-authors-block LOGIN

Exclude items by author. Repeatable.

--active-assignees-allow LOGIN

Accepted but ignored today (no assignee on the normalised PR shape). Repeatable.

--active-assignees-block LOGIN

Accepted but ignored today. Repeatable.

github-deployments + codebase-conventions

--deploy-repo owner/repo

Repository slug to scan for deployments. Repeatable.

--conventions-repo owner/repo

Repository slug to detect conventions for. Repeatable.

Ticket flags

--ticket-project PROJECT_KEY

Tracker project key to scan for active tickets. Repeatable.

--ticket-archaeology-project PROJECT_KEY

Tracker project key to mine for closed tickets. Repeatable.

--ticket-max Ndefault: 100

Max closed tickets per project.

reviewer-profile flags

--reviewer-repo owner/repo

Repository slug to profile reviewers for. Repeatable.

--reviewer-pr-sample Ndefault: 20

How many recent merged PRs to sample per repo.

--reviewer-top-n Ndefault: 5

How many top reviewers to profile per repo.

code-hotspots flags

--hotspots-repo owner/repo

Repository slug to analyse. Repeatable.

--hotspots-since-days Ndefault: 30

Commit lookback window in days.

--hotspots-max-commits Ndefault: 100

Max commits to inspect per repo.

--hotspots-top-n Ndefault: 10

How many hotspot files to surface per repo.

meeting-digest flags

--meeting-since-days Ndefault: 7

How many days back to scan.

--meeting-max Ndefault: 25

Cap on meetings included in the digest.

--meeting-attendee-allow EMAIL

Only include meetings with at least one of these attendee emails. Repeatable. Empty = no filter (every accessible meeting).

Code-quality extractor flags

Three code-quality knobs have no shared equivalent and show in -h:

--prhygiene-large-loc Ndefault: 400

pr-hygiene: LOC threshold (additions + deletions) for a "large" PR.

--gov-branch BRANCH

repo-governance: branch to check protection for. Default: the provider's default branch.

--stale-days Ndefault: 14

stale-prs: a PR open longer than this many days is stale.

Per-extractor overrides and their defaults (each *-repo flag is repeatable and defaults to empty):

Extractor	Override flags (default)
`defect-hotspots`	`--risk-repo`, `--risk-since-days` (90), `--risk-max-commits` (200), `--risk-top-n` (10)
`pr-hygiene`	`--prhygiene-repo`, `--prhygiene-max` (100), `--prhygiene-diffstat-sample` (30)
`review-nits`	`--nits-repo`, `--nits-pr-sample` (30), `--nits-top-n` (15)
`revert-signals`	`--revert-repo`, `--revert-since-days` (90), `--revert-max-commits` (200)
`commit-message-quality`	`--msg-repo`, `--msg-since-days` (90), `--msg-max-commits` (200)
`stale-prs`	`--stale-repo`, `--stale-max` (100)
`ci-health`	`--cihealth-repo`, `--cihealth-limit` (100)
`dependency-health`	`--deps-repo`, `--deps-max` (200)
`code-scanning`	`--scan-repo`, `--scan-max` (200), `--scan-top-n` (10)
`repo-governance`	`--gov-repo`
`test-discipline`	`--testdisc-repo`, `--testdisc-top-n` (10)
`release-cadence`	`--release-repo`, `--release-max` (100)
`todo-density`	`--todo-repo`, `--todo-max` (200), `--todo-top-n` (10)