CLI reference

briar plan

Build an ordered, LLM-annotated implementation plan from a tracker board, then iterate the selector → implement → writeback loop until the board is done. Eight subcommands cover the full lifecycle.

Flags common to every subcommand

Every plan subcommand accepts --store, --root and --company. status, next and run also accept the two journal flags. They are documented once here and elided from each subcommand below.

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

filepostgres

Knowledge-store backend used to persist the plan.

--root PATHdefault: ./knowledge

Local file root (only used when --store=file).

--company COMPANY

Company key. Used by the postgres store for DSN resolution, by tracker providers for per-company credentials, and to namespace the plan-scoped knowledge blob (knowledge:<company>.<plan>).

--journal-store {file}default: file

file

Journal backend used by status, next, and run to read past decisions.

--journal-root PATHdefault: ./journal

Local journal root.

$ briar plan build

briar plan build [--name NAME] [--default-branch BRANCH]
                 [--max-cards N] [--with-knowledge] [--print] [--dry-run]
                 [--llm {anthropic,openai,gemini,bedrock}] [--model MODEL]
                 BOARD

Fetch a tracker board and persist an ordered implementation plan. Cards get LLM-annotated with scope, out-of-scope, risks, and inferred dependencies.

board URL | jira:KEYrequired

Positional. Board URL (Jira board, GitHub Projects v2) or short form (jira:KAN).

--name SLUG

Plan name. Defaults to a slug derived from the board URL.

--default-branch BRANCHdefault: main

Branch each card branches from by default. The LLM selector may override per pick.

--max-cards Ndefault: 50

Cap on cards pulled from the board.

--with-knowledge

Splice the company's knowledge blob (knowledge:<company>) and active-tickets blob into each card's synthesis context.

--print

After building, print the plan markdown to stdout.

--dry-run

Build the plan but do NOT persist it. Implies --print.

--llm PROVIDER

anthropicopenaigeminibedrock

LLM provider. Omit (empty) for heuristics-only synthesis (faster but shallower).

--model MODEL

Override the LLM provider's default model (e.g. claude-sonnet-4-6).

$ briar plan build jira:KAN --name q3 --company acme \
    --llm anthropic --with-knowledge

$ briar plan show

briar plan show NAME

Print the markdown body of a stored plan to stdout.

namerequired

Positional. Plan slug (used at build time).

$ briar plan show q3 --company acme | less

$ briar plan status

briar plan status NAME

Show past / current / to-be-done cards with the journal artifacts each one produced. The quick at-a-glance view of plan progress.

namerequired

Positional. Plan name.

$ briar plan status q3 --company acme

$ briar plan next

briar plan next --llm {anthropic,openai,gemini,bedrock}
                [--model MODEL] NAME

Ask the LLM selector what to do next; print the decision (card key + rationale) without executing. Useful for previewing a run.

namerequired

Positional. Plan name.

--llm PROVIDERrequired

anthropicopenaigeminibedrock

LLM provider.

--model MODEL

Override the LLM provider's default model.

$ briar plan next q3 --llm anthropic --company acme

$ briar plan advance

briar plan advance --card CARD
                   [--status {pending,in_progress,done,blocked}] NAME

Mark a card with a chosen status manually. Useful when you completed a card outside Briar (a human PR) and want the plan to reflect reality.

namerequired

Positional. Plan name.

--card CARD_KEYrequired

Card key to mark.

--status STATUSdefault: done

pendingin_progressdoneblocked

Status to set.

$ briar plan advance q3 --card KAN-7 --status done --company acme
$ briar plan advance q3 --card KAN-9 --status blocked --company acme

$ briar plan list

briar plan list

List stored plans in the configured store.

$ briar plan list --company acme

$ briar plan clear

briar plan clear [--yes] NAME

Remove a plan from the store. Prompts unless --yes.

namerequired

Positional. Plan name.

--yes

Skip confirmation.

$ briar plan clear q3 --company acme --yes

$ briar plan run

briar plan run --llm PROVIDER --company COMPANY
               [--owner OWNER] [--repo REPO]
               [--limit N] [--continue-on-failure] [--max-replans N]
               [--tracker-project KEY] [--tracker {...}] [--provider {...}]
               [--meeting-key ID] [--meeting-query Q] [--slack-query Q]
               [--runbook YAML]
               [--git-user-name NAME] [--git-user-email EMAIL]
               [--keep-worktree] [--dry-run] [--max-iter N] NAME

The headline command. Iterates the LLM selector: pick → implement → writeback, with REPLAN actions allowed up to --max-replans. Continues until the plan is done, --limit is hit, or a card fails (unless --continue-on-failure). --company is required here (flag, BRIAR_COMPANY, or .briar.toml).

Positional

namerequired

Plan name.

Loop control

--limit Ndefault: 0

Stop after N cards (0 = unlimited).

--continue-on-failure

On implement failure, mark card blocked and continue. Default: stop.

--max-replans Ndefault: 3

Cap on selector REPLAN actions per invocation.

--max-iter Ndefault: 0 (agent default, 30)

Iteration ceiling per card (passed through to agent implement).

--dry-run

Propagate --dry-run to every implement call.

--keep-worktree

Don't delete the temp worktree after each card. Useful for post-mortem inspection.

Target repo + tracker

--owner OWNER

Repository owner (GitHub) or workspace (Bitbucket). Inferred from the git origin remote if omitted.

--repo REPO

Repository as owner/repo, or a bare name with --owner. Inferred from git if omitted.

--tracker-project KEY

Tracker project key passed to agent implement. Defaults to <owner>/<repo>.

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

bitbucket-issuesgithub-issuesjiralinear

Tracker provider.

--provider {bitbucket,github}default: github

bitbucketgithub

Repository provider.

--git-user-name NAME

Override git committer name.

--git-user-email EMAIL

Override git committer email.

Context wiring

--runbook YAML

Runbook YAML for this company's messages: block, so the agent knows where to write outbound comments.

--meeting-key ID

Specific meeting ID to splice in.

--meeting-query STRING

Keyword search across recent meetings; default = card key.

--slack-query STRING

Keyword search across Slack threads; default = card key.

The per-card agent reuses the plan's --root as its file-store root, so there is no separate --knowledge flag. Hidden sizing knobs still work: --meeting (default fireflies), --meeting-top-k (3), --meeting-max-bytes (50000), --chat (default slack), --slack-top-k (3), --slack-max-bytes (30000).

LLM

--llm PROVIDERrequired

anthropicopenaigeminibedrock

LLM provider used by the selector, replans and the knowledge writeback. The per-card engineer agent always runs on Anthropic.

--model MODEL

Override the LLM provider's default model. The same value is also passed to each per-card agent implement.

$ briar plan run q3 --company acme --llm anthropic \
    --owner acme --repo widgets \
    --tracker jira --tracker-project KAN \
    --runbook runbooks/acme.yaml \
    --limit 5 --continue-on-failure

LLM cost shows up here

Each loop iteration runs the selector (one LLM call) and the engineer agent (many LLM calls — one per tool-use turn). Use --limit liberally during your first runs. briar telemetry preview does not estimate cost; that's on your provider dashboard.

Flags common to every subcommand

$ briar plan build

$ briar plan show

$ briar plan status

$ briar plan next

$ briar plan advance

$ briar plan list

$ briar plan clear

$ briar plan run

Positional

Loop control

Target repo + tracker

Context wiring

LLM

See also