CLI reference
briar plan
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
| Status | Meaning |
|---|---|
pending | Not started. Every new card starts here. Only pending cards can be picked. |
in_progress | plan run is working on it right now. |
done | The agent run for this card ended without an error. |
blocked | The 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.
| Decision | Meaning | What plan run does next |
|---|---|---|
pick | Work on this pending card. It may also name a branch parent. | Runs the coding agent on the card. |
replan | The board has changed, so the card list is out of date. | Reads the board again, then asks the selector again. |
complete | Nothing is left to do. briar also says this, with no model call, when no card is pending. | Stops. |
blocked | No 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
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 filefilepostgresfile 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: ./knowledgeplan run passes the same folder to each card's agent. Example: --root ./knowledge.--company COMPANYJIRA_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: filefilefile exists today. Example: --journal-store file.--journal-root PATHdefault: ./journalBRIAR_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
| Form | Example | What briar reads |
|---|---|---|
| Jira, short form | jira:ACME | The open tickets in project ACME. |
| Jira board URL | https://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/3 | Up 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
- Reads up to
--max-cardscards from the board. - With
--llm, asks the model about each card. It may only link cards that are on the same board. Its branch name looks likefeat/login-retry. - Fills any field that is still empty from the ticket text.
- Gives a card with no good branch name one from its key:
ACME-42becomeschore/acme-42. Sets each branch parent to--default-branch. - Saves
plan:q3and writesknowledge:acme.q3. - 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 BOARDrequiredjira:ACME.--name NAMEplan 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--default-branch develop.--max-cards Ndefault: 50--max-cards 20.--with-knowledgeknowledge: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--print.--dry-run--dry-run.--llm PROVIDERanthropicopenaigeminibedrock--llm anthropic.--model MODEL--model gpt-4o.Plus --store, --root and --company from the shared flags.
$ briar plan list
briar plan listPrints 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 NAMEPrints 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 NAMErequiredq3.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.
PLAN q3 (board: jira:ACME)DONE (1)ACME-42 Add retry to loginIN 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 NAMErequiredq3.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 NAMErequiredq3.--llm PROVIDERrequiredanthropicopenaigeminibedrock--llm anthropic.--model MODEL--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
[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
--limitand--continue-on-failure.
What it does, step by step
- Checks that it knows the company and the repo, loads the plan, and checks the
--llmkey. - Opens a journal session for the run.
- Stops if
--limitcards were already picked in this run. - Asks the selector for a decision.
- On
completeit stops. Onblockedit stops with exit code 1. Onreplanit reads the board again and goes back to step 3. - On
pickit marks the card in_progress and saves the plan. - It runs agent implement on the card. The card key is the ticket key.
- 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.
- After a failure it stops, unless you passed
--continue-on-failure. Otherwise it goes back to step 3. - At the end it prints a summary:
done,blocked,replans,stopped_earlyandremaining_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 NAMErequiredq3.Limits and loop control
--limit Ndefault: 00 means no limit. Replans do not count. Example: --limit 1.--continue-on-failure--continue-on-failure.--max-replans Ndefault: 3--max-replans 1.--max-iter Ndefault: 300 also means 30. Example: --max-iter 40.--dry-run--dry-run to each card's agent and save nothing (see the note above). Example: --dry-run.--keep-worktree--keep-worktree.Repo and tracker
--repo REPOowner/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--repo is a bare name. Example: --owner acme-co --repo acme-app.--tracker TRACKERdefault: github-issuesbitbucket-issuesgithub-issuesjiralinearagent 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--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: githubbitbucketgithub--provider bitbucket.--git-user-name NAMEgit_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--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 YAMLmessages: channels, mcp: servers and git_identity:. Example: --runbook runbooks/acme.yaml.--meeting-key ID--meeting-query. Example: --meeting-key 01HZX3K9QW.--meeting-query TEXT--meeting-query "q3 launch".--slack-query TEXT--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 PROVIDERrequiredanthropicopenaigeminibedrock--llm anthropic.--model MODEL--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
--llmkey and an Anthropic key. You also need what agent implement needs: a repo token,gitandgh, 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 usecurl, which itsbashtool 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 code | Meaning |
|---|---|
0 | The plan is complete, or --limit was reached, and no card failed in this run. |
1 | The 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. |
2 | Bad 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 NAMErequiredq3.--card KEYrequiredplan status. Example: --card ACME-42.--status STATUSdefault: donependingin_progressdoneblocked--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 NAMErequiredq3.--yes--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
- You get
plan:q3andknowledge:acme.q3, then the plan on screen. - You get the selector's pick and its reason.
- You get one card worked, most likely a draft PR from a branch like
chore/acme-42, and a summary. - You get the card table, and one journal session for the run.
- ACME-43 is pending again, so the selector can pick it.
- You get up to 10 more cards worked. Failed cards are marked blocked. After each done card,
knowledge:acme.q3grows.
Model providers
build, next and run take --llm. Each provider reads its own key and has its own default model.
| --llm | Key | Default model |
|---|---|---|
anthropic | ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN | claude-sonnet-4-5 |
openai | OPENAI_API_KEY | gpt-4o |
gemini | GEMINI_API_KEY | gemini-2.5-pro |
bedrock | Your 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. Runplancommands from the same folder each time, or the selector loses its history. BRIAR_JOURNAL=offturns 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 cleardoes not deleteknowledge:acme.q3. Remove it withbriar context delete knowledge:acme.q3(add--store postgresif that is your store).
See also
- briar agent: the coding agent that
plan runstarts for each card. - briar journal: read the decisions each run made.
- briar extract: build the
knowledge:acmeblobs that--with-knowledgeand the selector read. - Core concepts: Plans: the idea behind plans, selectors and writeback.