Skip to content

CLI reference

briar plan

A plan is a to-do list made from a board of tickets. briar plan builds it, shows it, and works through it. Each card becomes one briar agent implement run, so each card ends as a draft PR.

How a plan works

You build a plan once from a board. briar saves it in your knowledge store as a blob named plan:q3. A blob is one saved markdown text. Then briar plan run repeats one loop. It asks a model which card to do next. It runs the coding agent on that card. It saves what it learned. Then it asks again.

Cards

A card is one ticket from the board. Each card holds its key (like ACME-42), its title, a short summary, what is in scope and out of scope, its risks, the cards it depends on, a branch name, a branch parent, and a status.

plan build fills these in. With --llm, a model writes them. Without it, briar reads them from headings in the ticket text, such as "In scope", "Out of scope" and "Risks". It finds links from lines like "Depends on ACME-41" or "Blocked by ACME-40".

The cards a card depends on are only a hint for the model. briar never holds a card back because of them.

Card statuses

StatusMeaning
pendingNot started. Every new card starts here. Only pending cards can be picked.
in_progressplan run is working on it right now.
doneThe agent run for this card ended without an error.
blockedThe agent run failed. briar saves a short reason on the card.

You can set any status by hand with plan advance.

The selector and its four decisions

The selector is one model call. It reads the plan, the journal (which cards finished or failed before), and the plan's knowledge blob. It answers with one of four decisions.

DecisionMeaningWhat plan run does next
pickWork on this pending card. It may also name a branch parent.Runs the coding agent on the card.
replanThe board has changed, so the card list is out of date.Reads the board again, then asks the selector again.
completeNothing is left to do. briar also says this, with no model call, when no card is pending.Stops.
blockedNo card can move forward without a person.Stops with exit code 1.

A pick must name a pending card. If the selector names any other key, or its answer is not valid JSON, the command stops with an error.

A replan reads at most 50 cards from the board. Cards that were in the plan keep their status. New cards start as pending. Cards that left the board are dropped.

Branch stacking

Stacking means one PR builds on the branch of another PR, not on main. Each card has a branch parent. plan build sets it to --default-branch. When the selector picks a card, it may name another parent. When it names none, a card whose dependency is done starts from that dependency's branch (since 1.1.96), so it builds on code not merged yet. briar saves the parent on the card and in the journal.

Since 1.1.85, plan run uses both fields. The coding agent clones the card's parent, pushes the card's branch name, and opens the draft PR against the parent. If the parent is --default-branch and that branch does not exist in the repo (for example the repo uses master), briar warns and starts from the repo's real default branch. Any other missing parent fails the card.

Before 1.1.85

The branch parent was only saved. The agent always cloned the default branch and pushed chore/acme-42, whatever the card said.

The plan's knowledge blob

plan build also writes a blob named knowledge:acme.q3: the company, a dot, and the plan name. It starts with the board details and each card's scope and risks. briar writes it only when the plan has a company.

After each card that ends as done, plan run asks the planner model to rewrite this blob so it notes the finished card. This step is the writeback. If it fails, the run goes on.

Each time the selector picks, it reads this blob and knowledge:acme. It reads the first 8,000 bytes of each. Since 1.1.93 the coding agent of each card also gets this blob, read again before the card, as a Plan notes section of its prompt. Before 1.1.93 it saw only the sections its persona reads.

The journal

The journal is a log of decisions. Each plan run is one session in it, saved under ./journal. It records the start, each selector decision, each card start, each card done or failed, each replan, and why the run stopped. Every entry has a short reason.

plan status, plan next and plan run read it to learn which cards finished or failed before. You can read it too:

$ briar journal list --command plan.run

You get one row per plan run session. Pass a session ID from that list to briar journal show to see every decision in it.

Flags every subcommand shares

Every plan subcommand takes the first three. status, next and run also take the two journal flags. A flag on the command line wins over an env var. An env var wins over .briar.toml. That file wins over the built-in default.

--store STOREdefault: postgres if BRIAR_DATABASE_URL set, else file
filepostgres
Where the plan and the knowledge blobs live. file uses markdown files under --root. postgres uses the database in BRIAR_DATABASE_URL. BRIAR_STORE or store in .briar.toml also set it. Example: --store postgres.
--root PATHdefault: ./knowledge
The folder of the file store. briar ignores it with postgres. plan run passes the same folder to each card's agent. Example: --root ./knowledge.
--company COMPANY
The company key. briar uses it to find tracker keys (like JIRA_ACME_URL), to pick a database, and to name the blob knowledge:acme.q3. plan run needs it. It can come from BRIAR_COMPANY or company in .briar.toml. Example: --company acme.
--journal-store STOREdefault: file
file
Where to read past run decisions. Only file exists today. Example: --journal-store file.
--journal-root PATHdefault: ./journal
The journal folder to read. New sessions are written to BRIAR_JOURNAL_ROOT (default ./journal), not to this flag. Keep the two the same. Example: --journal-root /var/lib/briar/journal.

The examples below run inside a checkout of acme-co/acme-app with company = "acme" in .briar.toml. That is why they skip --company.

$ briar plan build

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

Reads the cards on a board and saves them as a plan. With --llm, a model writes a summary, the scope, the risks, the links between cards, and a branch name for each card.

Use it when

  • You start work on a new sprint, epic or project board.
  • You want to read the plan before any code runs (--dry-run).
  • The board changed a lot and you want to start over with a fresh plan.

Boards it can read

FormExampleWhat briar reads
Jira, short formjira:ACMEThe open tickets in project ACME.
Jira board URLhttps://acme.atlassian.net/jira/software/projects/ACME/boards/12 (the /c/projects/ form works too)The open tickets in project ACME. The board number is not used as a filter.
GitHub Projects (v2)https://github.com/orgs/acme-co/projects/3 or https://github.com/users/dana/projects/3Up to 100 items. Needs GITHUB_TOKEN.

Jira needs your company's Jira keys, like JIRA_ACME_URL. On GitHub, a card key looks like acme-co/acme-app#12. A draft item gets a key that starts with draft:. Any other URL fails with no board reader recognised URL.

What it does, step by step

  1. Reads up to --max-cards cards from the board.
  2. With --llm, asks the model about each card. It may only link cards that are on the same board. Its branch name looks like feat/login-retry.
  3. Fills any field that is still empty from the ticket text.
  4. Gives a card with no good branch name one from its key: ACME-42 becomes chore/acme-42. Sets each branch parent to --default-branch.
  5. Saves plan:q3 and writes knowledge:acme.q3.
  6. Prints a short record: the plan name, the blob name, the knowledge blob name, the card count, the tracker and the project.

Examples

# 1. Look at the plan first. Nothing is saved.
$ briar plan build jira:ACME --name q3 --dry-run

You get the plan as markdown on screen. With no --llm, the summaries come from the ticket text only.

# 2. Build and save, with a model.
$ briar plan build jira:ACME --name q3 --llm anthropic

You get plan:q3 and knowledge:acme.q3 in your store, and a short record with the card count.

# 3. Use what briar extract already knows about acme, and print the result.
$ briar plan build jira:ACME --name q3 --llm anthropic --with-knowledge --print

The model also sees knowledge:acme, active-tickets:acme and active-work:acme for each card. You also get the plan markdown on screen.

# 4. A GitHub Projects board, fewer cards, another base branch.
$ briar plan build https://github.com/orgs/acme-co/projects/3 --name q3 --max-cards 20 --default-branch develop --llm anthropic

You get a plan of at most 20 cards. Each card's branch parent is develop.

# 5. Another model for the planner.
$ briar plan build jira:ACME --name q3 --llm openai --model gpt-4o

You get the same plan, written by gpt-4o. It needs OPENAI_API_KEY.

Parameters

board BOARDrequired
Comes first, with no flag name. The board to read, in one of the forms above. Example: jira:ACME.
--name NAME
The plan name. Every other plan command needs it. If you leave it out, briar makes one from the URL: jira:ACME gives jiraacme, a Jira board URL gives boards-12. So always pass it. Example: --name q3.
--default-branch BRANCHdefault: main
The branch parent each card starts with. The selector may change it per pick. If the repo has no such branch, cards start from its real default branch (since 1.1.85). Example: --default-branch develop.
--max-cards Ndefault: 50
The most cards to read from the board. GitHub Projects stops at 100 whatever you pass. Example: --max-cards 20.
--with-knowledge
Show the model what you already extracted for the company: knowledge:acme, active-tickets:acme and active-work:acme. It needs a company, and it only matters with --llm. A missing blob is skipped. Example: --with-knowledge.
--print
After saving, also print the plan as markdown. Example: --print.
--dry-run
Build the plan and print it, but save nothing. briar does not write the knowledge blob either. Example: --dry-run.
--llm PROVIDER
anthropicopenaigeminibedrock
The model provider that writes each card. Leave it out to build from the ticket text only. If its key is missing, briar warns and builds without it. Example: --llm anthropic.
--model MODEL
The model to use at that provider. Each provider has its own default (see model providers). Example: --model gpt-4o.

Plus --store, --root and --company from the shared flags.

$ briar plan list

briar plan list

Prints the name of every saved plan.

  • Use it when you forgot a plan's name.
  • Use it to check which store holds your plans.
$ briar plan list
$ briar plan list --store postgres

You get one row per plan, like plan:q3. Other commands take either q3 or plan:q3. It takes only the shared flags --store, --root and --company.

$ briar plan show

briar plan show NAME

Prints a saved plan as markdown. You see the board, the tracker, the project and the default branch. Then each card in order, with its links, branch, status, URL, summary, scope and risks. The raw JSON comes last.

  • Use it to read the plan before you run it.
  • Use it to check what the model wrote for one card.
$ briar plan show q3
$ briar plan show q3 --store postgres

You get the whole plan on screen.

name NAMErequired
The plan name you used at build time. Example: q3.

Plus --store, --root and --company from the shared flags.

$ briar plan status

briar plan status NAME [--journal-store file] [--journal-root PATH]

Shows each card grouped by status: done, in progress, blocked and pending. It reads the journal to add when a card started and why a card failed.

  • Use it after a run to see what got done.
  • Use it to find blocked cards and the reason they failed.
$ briar plan status q3
$ briar --format json plan status q3
$ briar plan status q3 --journal-root /var/lib/briar/journal

You get a table like the one below. With --format json you get the same data as JSON, with a count per status.

Example output (made-up cards)
PLAN q3 (board: jira:ACME)
DONE (1)
ACME-42 Add retry to login
IN PROGRESS (0)
(none)
BLOCKED (1)
ACME-43 Rate-limit the export API "implement rc=1" (implement rc=1)
PENDING (2)
ACME-44 Add audit log for exports [deps: ACME-43]
ACME-45 Document the export API

Done cards show only the key and title. In 1.1.75 plan run does not save the commit or the PR URL in the journal. Find the PR on the board or in the run output.

name NAMErequired
The plan name. Example: q3.

Plus all five shared flags.

$ briar plan next

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

Asks the selector what to do next and prints its answer. It changes nothing. It does not save the plan or write to the journal.

  • Use it to preview a run before you spend money on the coding agent.
  • Use it to check that your model key works.
$ briar plan next q3 --llm anthropic
$ briar plan next q3 --llm openai --model gpt-4o
$ briar --format yaml plan next q3 --llm gemini

You get one record: action, key, why and branch_parent. A pick also shows the card's title, branch_name and summary.

name NAMErequired
The plan name. Example: q3.
--llm PROVIDERrequired
anthropicopenaigeminibedrock
The model provider for the selector. If its key is missing, the command stops with an error. Example: --llm anthropic.
--model MODEL
The model to use at that provider. Example: --model gpt-4o.

Plus all five shared flags.

$ briar plan run

briar plan run NAME --llm {anthropic,openai,gemini,bedrock} [--model MODEL] [--limit N] [--continue-on-failure] [--max-replans N] [--max-iter N] [--owner OWNER] [--repo REPO] [--tracker {bitbucket-issues,github-issues,jira,linear}] [--tracker-project KEY] [--provider {bitbucket,github}] [--git-user-name NAME] [--git-user-email EMAIL] [--runbook YAML] [--meeting-key ID] [--meeting-query TEXT] [--slack-query TEXT] [--keep-worktree] [--dry-run]

Works through the plan one card at a time. For each card it runs the coding agent, which tries to open a draft PR. It stops when the plan is done, when it hits a limit, or when a card fails.

MCP helpers and Docker

Each card runs the coding agent, which tries to start two MCP helper servers. Without the [mcp] extra, briar skips them with one warning and the card goes on. plan run has no --no-default-mcp flag. To skip those servers and the warning, set BRIAR_NO_DEFAULT_MCP=1. It also needs git and gh. The Docker image has both, so plan run works there too (see Agents in Docker).

Use it when

  • You built a plan and want draft PRs for its cards.
  • You want to try one card end to end (--limit 1).
  • You leave it running for a while with --limit and --continue-on-failure.

What it does, step by step

  1. Checks that it knows the company and the repo, loads the plan, and checks the --llm key.
  2. Opens a journal session for the run.
  3. Stops if --limit cards were already picked in this run.
  4. Asks the selector for a decision.
  5. On complete it stops. On blocked it stops with exit code 1. On replan it reads the board again and goes back to step 3.
  6. On pick it marks the card in_progress and saves the plan.
  7. It runs agent implement on the card. The card key is the ticket key.
  8. If the agent ends without an error, the card is done and briar runs the writeback. If not, the card is blocked, with a short reason.
  9. After a failure it stops, unless you passed --continue-on-failure. Otherwise it goes back to step 3.
  10. At the end it prints a summary: done, blocked, replans, stopped_early and remaining_pending.

Examples

# 1. One card from a Jira plan, to see how it goes.
$ briar plan run q3 --llm anthropic --tracker jira --tracker-project ACME --limit 1

You get one card done or blocked, most likely a draft PR, and the summary record.

# 2. Up to 5 cards, and keep going after a failure.
$ briar plan run q3 --llm anthropic --tracker jira --tracker-project ACME --limit 5 --continue-on-failure

You get up to 5 cards worked. A failed card is marked blocked and the run moves on.

# 3. The planner on OpenAI. The coding agent still runs on Anthropic.
$ briar plan run q3 --llm openai --model gpt-4o --tracker jira --tracker-project ACME

Here --model only changes the planner. Each card's agent uses its default Anthropic model. You need both an OpenAI key and an Anthropic key.

# 4. One Anthropic model for the planner and the coding agent.
$ briar plan run q3 --llm anthropic --model claude-sonnet-4-6 --tracker jira --tracker-project ACME

With --llm anthropic, the same model also reaches each card's agent.

# 5. A GitHub Projects plan with GitHub Issues, plus agent context.
$ briar plan run q3 --llm anthropic --repo acme-co/acme-app --runbook runbooks/acme.yaml --slack-query "q3 launch" --max-iter 40 --keep-worktree

The tracker defaults to github-issues and the project to acme-co/acme-app. Each card's agent gets the runbook's channels and MCP servers, Slack threads about "q3 launch", and up to 40 turns.

A dry run changes nothing (1.1.81 and later)

plan run --dry-run walks the cards in memory: the selector still picks, each card's agent runs dry, and nothing is saved (no card status, no notes, no plan.run history). Before 1.1.81 it marked each picked card done; if you did that, set the cards back with plan advance q3 --card ACME-42 --status pending.

The plan name

name NAMErequired
The plan to work on, as named at build time. Example: q3.

Limits and loop control

--limit Ndefault: 0
Stop after this many cards are picked in this run. 0 means no limit. Replans do not count. Example: --limit 1.
--continue-on-failure
When a card fails, mark it blocked and go on. Without it, the run stops at the first failure. Example: --continue-on-failure.
--max-replans Ndefault: 3
The most replans in one run. If the selector asks for one more, the run stops with exit code 1. Example: --max-replans 1.
--max-iter Ndefault: 30
The most model turns each card's agent gets. 0 also means 30. Example: --max-iter 40.
--dry-run
Pass --dry-run to each card's agent and save nothing (see the note above). Example: --dry-run.
--keep-worktree
Keep each card's worktree folder after its run. briar always keeps it when the card fails. Example: --keep-worktree.

Repo and tracker

--repo REPO
The repo the agent works on, as owner/repo, or a bare name with --owner. If you leave it out, briar uses [repo] in .briar.toml, then the git origin remote. Example: --repo acme-co/acme-app.
--owner OWNER
The GitHub owner, or the Bitbucket workspace. You need it only when --repo is a bare name. Example: --owner acme-co --repo acme-app.
--tracker TRACKERdefault: github-issues
bitbucket-issuesgithub-issuesjiralinear
Where each card's ticket lives. The agent reads the ticket from there. This default differs from agent implement, which uses jira. For a Jira plan, pass --tracker jira. tracker in .briar.toml also sets it. Example: --tracker jira.
--tracker-project KEYdefault: owner/repo
The tracker project, passed to the agent as --ticket-project. The default is the repo, which suits GitHub Issues. For Jira, pass the project key. For Linear, pass the team key. Example: --tracker-project ACME.
--provider PROVIDERdefault: github
bitbucketgithub
Where the repo lives. Example: --provider bitbucket.
--git-user-name NAME
The commit author name for every card. If you leave it out, briar uses the runbook's git_identity.name, then your own git config (not in CI). Use a real person, never a bot. Example: --git-user-name "Dana Lee".
--git-user-email EMAIL
The commit author email. Same rules. Example: --git-user-email [email protected].

Context for the coding agent

These go to each card's agent unchanged. They work as on briar agent.

--runbook YAML
A runbook file. The agent gets your company's messages: channels, mcp: servers and git_identity:. Example: --runbook runbooks/acme.yaml.
--meeting-key ID
One Fireflies meeting ID to add to every card's prompt. It wins over --meeting-query. Example: --meeting-key 01HZX3K9QW.
--meeting-query TEXT
Search words for recent meetings. The default is the card key. Example: --meeting-query "q3 launch".
--slack-query TEXT
Search words for Slack threads. The default is the card key. Example: --slack-query "q3 launch".

Hidden flags work here too, as on briar agent: --meeting (default fireflies), --meeting-top-k (3), --meeting-max-bytes (50000), --chat (default slack), --slack-top-k (3) and --slack-max-bytes (30000). There is no --knowledge flag here. The agent uses the plan's --root.

Models

--llm PROVIDERrequired
anthropicopenaigeminibedrock
The planner model provider. It runs the selector, the replans and the writeback. The coding agent on each card always runs on Anthropic. Example: --llm anthropic.
--model MODEL
The planner model. With --llm anthropic, each card's agent uses it too. With any other provider, the agent keeps its default (claude-sonnet-4-5). model under [agent] in .briar.toml also sets this flag. Example: --model claude-sonnet-4-6.

Plus all five shared flags. --company is required here.

Good to know

  • A card is done when its agent run ends without an error and with at least one commit (since 1.1.96). briar does not check that a PR exists.
  • If a run is killed during a card, that card stays in_progress. The selector only picks pending cards. Set it back with plan advance --status pending.
  • Each card costs one selector call, a full agent run (up to 30 model turns), and one writeback call when it is done. Start with --limit 1.
  • You need the --llm key and an Anthropic key. You also need what agent implement needs: a repo token, git and gh, tracker keys and a git identity.
  • With --provider bitbucket, each card's agent opens the draft PR with a short Python script (since 1.1.88). Before, it was told to use curl, which its bash tool blocks, so only the branch got pushed. briar does not check that a PR exists before marking the card done (it does check for a commit, since 1.1.96).
Exit codeMeaning
0The plan is complete, or --limit was reached, and no card failed in this run.
1The selector said blocked, the replan limit was hit, a card failed, or the selector gave a bad answer. Also when the company or the model key is missing.
2Bad flags, or a crash.

$ briar plan advance

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

Sets the status of one card by hand. It does not run the writeback and does not write to the journal.

  • You finished a card yourself and want the plan to know.
  • You want a blocked card to run again: set it to pending.
  • You want the selector to skip a card: set it to blocked.
$ briar plan advance q3 --card ACME-42
$ briar plan advance q3 --card ACME-43 --status pending
$ briar plan advance q3 --card ACME-44 --status blocked

You get the changed card as a record. A key that is not in the plan stops with card 'ACME-99' not in plan 'q3'.

name NAMErequired
The plan name. Example: q3.
--card KEYrequired
The card key to change, as shown by plan status. Example: --card ACME-42.
--status STATUSdefault: done
pendingin_progressdoneblocked
The new status. Example: --status pending.

Plus --store, --root and --company from the shared flags.

$ briar plan clear

briar plan clear NAME [--yes]

Deletes a saved plan. It asks Delete plan 'q3'? [y/N] first, unless you pass --yes. It keeps knowledge:acme.q3 and the journal.

  • Use it when a plan is finished or no longer useful.
  • Use it before you build a new plan with the same name.
$ briar plan clear q3
$ briar plan clear q3 --yes

You get deleted q3. It exits with 1 when the plan is not found, or when you answer no.

name NAMErequired
The plan name. Example: q3.
--yes
Delete without asking. Use it in scripts. Example: --yes.

Plus --store, --root and --company from the shared flags.

A full example, start to finish

This walks one Jira project from board to draft PRs. It runs inside a checkout of acme-co/acme-app with company = "acme" in .briar.toml.

# 1. Build the plan from project ACME, then read it.
$ briar plan build jira:ACME --name q3 --llm anthropic --with-knowledge
$ briar plan show q3
# 2. Ask what would run first. Nothing changes.
$ briar plan next q3 --llm anthropic
# 3. Do one card.
$ briar plan run q3 --llm anthropic --tracker jira --tracker-project ACME --limit 1
# 4. See where things stand.
$ briar plan status q3
$ briar journal list --command plan.run
# 5. ACME-43 failed. Fix the ticket text, then let it run again.
$ briar plan advance q3 --card ACME-43 --status pending
# 6. Do the rest, up to 10 cards, and keep going after a failure.
$ briar plan run q3 --llm anthropic --tracker jira --tracker-project ACME --limit 10 --continue-on-failure
  1. You get plan:q3 and knowledge:acme.q3, then the plan on screen.
  2. You get the selector's pick and its reason.
  3. You get one card worked, most likely a draft PR from a branch like chore/acme-42, and a summary.
  4. You get the card table, and one journal session for the run.
  5. ACME-43 is pending again, so the selector can pick it.
  6. You get up to 10 more cards worked. Failed cards are marked blocked. After each done card, knowledge:acme.q3 grows.

Model providers

build, next and run take --llm. Each provider reads its own key and has its own default model.

--llmKeyDefault model
anthropicANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKENclaude-sonnet-4-5
openaiOPENAI_API_KEYgpt-4o
geminiGEMINI_API_KEYgemini-2.5-pro
bedrockYour usual AWS login (the default AWS credential chain)anthropic.claude-sonnet-4-20250514-v1:0

Good to know

  • The journal is written to BRIAR_JOURNAL_ROOT (default ./journal), from the folder where you run briar. Run plan commands from the same folder each time, or the selector loses its history.
  • BRIAR_JOURNAL=off turns the journal off. Then the selector cannot see which cards failed before.
  • A plan keeps the company it was built with. If you build without a company, briar skips the plan's knowledge blob and --with-knowledge. Later runs of that plan skip the writeback too.
  • plan clear does not delete knowledge:acme.q3. Remove it with briar context delete knowledge:acme.q3 (add --store postgres if that is your store).

See also