CLI reference
briar scaffold
What you get
A JSON file (or JSON on screen). It has these lists, and every name in it starts with your --prefix:
| Key | What it holds |
|---|---|
llm_models | One model: the name from --model and the provider key from --llm-provider-key. |
sources | One entry per --source: where the agent reads issues, errors or cloud state, and how it logs in. |
tools | The actions the agent may take (comment, commit, open a draft PR, ...). The archetype decides which ones stay. |
agents | One agent: its role, goal, rules, tool list and step limit. With --company, its prompt also holds your extracted knowledge. |
workflows | The steps, set by --shape. |
triggers | What starts a run: a webhook or a cron timer. Left out for --trigger-kind manual. |
Here is a short part of the output for a GitHub source:
{"version": 1,"llm_models": [{ "key": "acme-model", "name": "claude-sonnet-4-6", "provider_key": "anthropic", ... }],"sources": [{ "key": "acme-gh-issues", "kind": "github","config": { "owner": "acme-co", "repo": "acme-co/acme-app", "include": "open" },"credential_binding": { "kind": "oauth_connection", "provider": "github" } }],"tools": [{ "key": "acme-gh-comment", ... }, { "key": "acme-gh-open-pr", ... }, { "key": "acme-gh-commit", ... }],"agents": [{ "key": "acme-engineer", "role": "Senior implementation engineer for acme-co/acme-app", "max_iter": 8, ... }],"workflows": [{ "key": "acme-workflow", "graph": { "entry": "plan", "nodes": [ ... ] } }],"triggers": [{ "key": "acme-trigger", "kind": "github_webhook","filter_rules": { "events": ["issues.opened", "issues.labeled"], "labels_any": ["briar"] } }]}
Secrets never go in the file. A source or tool points to a secret by ID (credentials_ref) or asks for an OAuth login (credential_binding). The orchestrator fills them in.
When to use it
- You run agents in an orchestrator, not on your laptop, and it needs a config to load.
- You want a starting config you can edit by hand and keep in git.
- You want the same agent setup for many repos or companies, changing only a few flags.
- You want an agent prompt that already holds your extracted knowledge.
To run an agent on your own machine, you do not need scaffold. Use briar agent implement or prfix.
The two templates
Both templates take the same 39 parameters. They differ only in three defaults.
| Template | Flow | --archetype | --shape | --trigger-kind |
|---|---|---|---|---|
implementation | An issue comes in. The agent writes a plan. A person approves it. Then the agent makes the change and opens a draft PR, or comments if the plan was rejected. | engineer | plan-approve-act | github_webhook |
pr-fixes | Every hour, the agent reads review comments on open PRs, pushes fixes and replies. No person approves first. | pr-fixer | one-shot | schedule_cron (hourly) |
pr-fixes uses a cron timer because a GitHub issue webhook never fires on a PR review. Any default can be changed with its flag.
The building blocks
A bundle is made of four parts that you pick with flags: an archetype, a shape, a trigger and one or more sources.
Archetypes (--archetype)
An archetype is the agent's job. It sets the role and rules in its prompt, how many steps it may take, and which tools it keeps. A tool it does not keep is removed from the bundle, so the agent cannot use it.
| Archetype | Job | Tools it keeps | Max steps |
|---|---|---|---|
engineer | Make the change a ticket asks for, commit, open a draft PR. | All tools from the sources. | 8 |
pr-fixer | Answer open review comments with new commits. | Comment on issue or PR, commit, open PR. | 12 |
pr-ci-fixer | Fix failing CI checks on open PRs, from the logs. | Comment on issue or PR, commit. | 20 |
pr-conflict-resolver | Merge the base branch into old PRs and fix the conflicts. | Comment on issue or PR, commit. | 16 |
triager | Label new tickets and post a short summary comment. | Comment tools only (GitHub, Bitbucket, Jira, Sentry). | 5 |
The three PR archetypes also get fixed rules in their prompt: never force-push, do not open new PRs, do not edit CI workflow files, skip PRs that are approved and green. Every archetype is told to start its comments with [AI] .
Shapes (--shape)
| Shape | Steps |
|---|---|
plan-approve-act | The agent writes a plan. A person approves or rejects it. On approve, the agent makes the change and opens a draft PR. On reject, it comments on the issue. |
one-shot | One step. The agent reads, acts and writes a summary. No person in the loop. |
triage | One step with a triage prompt: label each item, comment once, do not commit. It does not remove tools by itself; pair it with --archetype triager for that. |
Triggers (--trigger-kind)
| Trigger | Starts a run when | Flags |
|---|---|---|
github_webhook | GitHub sends an issue event and the issue has one of the labels. | --webhook-events, --webhook-labels |
bitbucket_webhook | Bitbucket sends an issue event and the issue has one of the labels. | --bitbucket-webhook-events, --bitbucket-webhook-labels |
schedule_cron | The cron time comes (top of every hour by default). | --schedule |
manual | You start it in the orchestrator. The bundle has no triggers list. | None. |
Sources (--source)
Repeat --source to add more than one. Without any --source, briar uses github.
| Source | Reads | Tools it adds | Login |
|---|---|---|---|
github | Open issues in one repo. Needs --owner and --repo. | comment, open draft PR, commit | OAuth, or a stored token with --auth-mode pat |
bitbucket | Open issues and pull requests in one repo. Needs --bitbucket-workspace and --bitbucket-repo. | comment, open draft PR, commit | OAuth, or a stored app password with --auth-mode pat |
jira | Open issues in some or all projects. | comment, change status, edit fields | Atlassian OAuth, or a stored token if you pass --jira-secret-id |
aws | Cloud state (default services: ec2, iam, logs). Read only. | None | An IAM role the orchestrator assumes |
sentry | Unresolved errors in some projects. Needs --sentry-org and a --sentry-project. | comment, resolve, assign, ignore | A stored token only (--sentry-secret-id is required) |
$ briar scaffold implementation
briar scaffold implementation --prefix PREFIX [--source SOURCE ...]
[--archetype ARCHETYPE] [--shape SHAPE] [--trigger-kind KIND]
[source, filter and trigger flags] [--out OUT]Writes a bundle for the ticket flow: an issue arrives, the agent plans, a person approves, the agent makes the change and opens a draft PR.
Use it when
- You want an agent to pick up labeled issues and turn them into draft PRs.
- You want a person to approve each plan before code is written.
- You want a triage bot (change
--archetypeand--shape).
Examples
# Smallest bundle: GitHub issues, OAuth login, webhook on the "briar" label.$ briar scaffold implementation --prefix acme --source github --owner acme-co --repo acme-app
You get the JSON on screen: one GitHub source, three tools, an acme-engineer agent, a plan-approve-act workflow and a GitHub webhook trigger.
# Save to a file and log in with a stored GitHub token.$ briar scaffold implementation --prefix acme \--source github --owner acme-co --repo acme-app \--auth-mode pat --github-secret-id 3f2b8c1e-5d4a-4f6b-9a7c-1e2d3c4b5a69 \--out acme-implementation.json
You get acme-implementation.json. The source and tools point to that secret ID instead of OAuth.
# Put your extracted knowledge in the agent's prompt.$ briar scaffold implementation --prefix acme \--source github --owner acme-co --repo acme-app \--company acme --knowledge-store file
You get an agent whose system_prompt holds the sections it needs from knowledge:acme (filled by briar extract or a runbook).
# Bitbucket, stored app password, Bitbucket webhook.$ briar scaffold implementation --prefix acme \--source bitbucket --bitbucket-workspace acme-co --bitbucket-repo acme-app \--auth-mode pat --bitbucket-secret-id 3f2b8c1e-5d4a-4f6b-9a7c-1e2d3c4b5a69 \--trigger-kind bitbucket_webhook
You get a Bitbucket source, three Bitbucket tools and a trigger on issue:created and issue:updated.
# A triage bot for Jira and Sentry, every 30 minutes.$ briar scaffold implementation --prefix acme-triage \--source jira --jira-project ACME \--source sentry --sentry-org acme --sentry-project acme-api \--sentry-level error --sentry-level fatal \--sentry-secret-id 3f2b8c1e-5d4a-4f6b-9a7c-1e2d3c4b5a69 \--archetype triager --shape triage \--trigger-kind schedule_cron --schedule "*/30 * * * *"
You get an acme-triage-triager agent with only two tools (Jira comment, Sentry comment) and a cron trigger.
$ briar scaffold pr-fixes
briar scaffold pr-fixes --prefix PREFIX [--source SOURCE ...]
[same flags as implementation] [--out OUT]Writes a bundle for the review-fix flow. Every hour, the agent reads review comments on open PRs, pushes fixes as new commits and replies. No person approves first.
It takes the same flags as implementation. Three defaults differ: --archetype pr-fixer, --shape one-shot and --trigger-kind schedule_cron (hourly). The -h text shows these.
Use it when
- Reviewers leave comments and you want them answered with commits.
- You want a bot for failing CI (
--archetype pr-ci-fixer) or merge conflicts (--archetype pr-conflict-resolver).
Examples
# Hourly PR fixer for one GitHub repo, saved to a file.$ briar scaffold pr-fixes --prefix acme \--source github --owner acme-co --repo acme-app \--out acme-prfix.json
You get an acme-pr-fixer agent, a one-step workflow and an acme-cron trigger at 0 * * * *.
# Same, but every 30 minutes.$ briar scaffold pr-fixes --prefix acme \--source github --owner acme-co --repo acme-app \--schedule "*/30 * * * *"
You get the same bundle with "schedule_cron": "*/30 * * * *".
# A bot that fixes failing CI instead of review comments.$ briar scaffold pr-fixes --prefix acme-ci \--source github --owner acme-co --repo acme-app \--archetype pr-ci-fixer
You get an acme-ci-pr-ci-fixer agent with two tools (comment, commit) and up to 20 steps.
# Bitbucket repo, stored app password.$ briar scaffold pr-fixes --prefix acme \--source bitbucket --bitbucket-workspace acme-co --bitbucket-repo acme-app \--auth-mode pat --bitbucket-secret-id 3f2b8c1e-5d4a-4f6b-9a7c-1e2d3c4b5a69
You get the hourly PR fixer with Bitbucket tools.
Bundles with several sources
Repeat --source. Each source adds its own entry and tools. The agent's target name comes from the first source that has one (for example acme-co/acme-app).
# GitHub issues, Jira tickets and read-only AWS state.$ briar scaffold implementation --prefix acme \--source github --owner acme-co --repo acme-app \--source jira --jira-project ACME --jira-jql "labels = agent" \--source aws --aws-role-arn arn:aws:iam::123456789012:role/briar-read \--aws-external-id acme-briar --aws-region us-west-2 \--aws-services ecs --aws-services rds
You get three sources (acme-gh-issues, acme-jira, acme-aws) and six tools: three for GitHub, three for Jira. AWS adds none.
# Hide bot issues everywhere, but use a different assignee name in Jira.$ briar scaffold implementation --prefix acme \--source github --owner acme-co --repo acme-app \--source jira --jira-project ACME \--authors-block "renovate[bot]" --assignees-allow alice \--jira-assignees-allow alice.smith
You get authors_block on both sources. GitHub keeps assignees_allow: [alice]; Jira gets [alice.smith], because a per-source flag wins.
All parameters
Both templates take all 39 parameters below. A flag for a source you did not pick is ignored.
Core
--prefix PREFIXrequired--prefix acme gives acme-engineer, acme-workflow.--out OUTdefault: stdoutwrote acme.json to stderr. -o is the short form. Example: --out acme.json.--source SOURCEdefault: github (when none is given)awsbitbucketgithubjirasentry--source github --source jira.--archetype ARCHETYPEdefault: engineer (pr-fixes: pr-fixer)engineerpr-ci-fixerpr-conflict-resolverpr-fixertriager--archetype triager.--shape SHAPEdefault: plan-approve-act (pr-fixes: one-shot)one-shotplan-approve-acttriage--shape one-shot.--trigger-kind KINDdefault: github_webhook (pr-fixes: schedule_cron)bitbucket_webhookgithub_webhookmanualschedule_cron--trigger-kind manual.--llm-provider-key KEYdefault: anthropicllm_models[0].provider_key. Example: --llm-provider-key openai.--model MODELdefault: claude-sonnet-4-6<provider>/<model>. A model under [agent] in .briar.toml also sets it. Example: --model gpt-4o.--auth-mode MODEdefault: oauthoauthpatoauth asks the orchestrator for an OAuth login. pat uses a stored token, so you must also pass --github-secret-id or --bitbucket-secret-id. Jira and Sentry ignore it. Example: --auth-mode pat.--github-secret-id UUID--auth-mode pat and --source github. Example: --github-secret-id 3f2b8c1e-5d4a-4f6b-9a7c-1e2d3c4b5a69.--company COMPANYdefault: "" (or company in .briar.toml)system_prompt. briar reads blobs whose name starts with knowledge:<company> and keeps only the sections the archetype uses. Without it, the prompt has no knowledge. If the store cannot be opened, briar skips this step. Example: --company acme.--knowledge-store STOREfile (folder ./knowledge) or postgres. Default: postgres if BRIAR_DATABASE_URL is set, else file. Used only with --company. Example: --knowledge-store file.Person filters (all sources)
These limit which issues the agent sees, by who wrote them or who they are assigned to. They apply to the GitHub, Bitbucket and Jira sources. AWS and Sentry ignore them. Each is repeatable, and the default is no filter. An issue must pass the allow list and must not be in the block list.
--authors-allow USER--authors-allow alice --authors-allow bob.--authors-block USER--authors-block "renovate[bot]".--assignees-allow USER--assignees-allow alice.--assignees-block USER--assignees-block carol.Per-source filters (hidden from -h)
Each filter also has a version for one source. They do not show in -h, but they work. Use one when a person has a different user name in each system. For that source, it replaces the shared flag. All are repeatable.
| Source | Flags |
|---|---|
| GitHub | --github-authors-allow, --github-authors-block, --github-assignees-allow, --github-assignees-block |
| Bitbucket | --bitbucket-authors-allow, --bitbucket-authors-block, --bitbucket-assignees-allow, --bitbucket-assignees-block |
| Jira | --jira-authors-allow, --jira-authors-block, --jira-assignees-allow, --jira-assignees-block |
For Bitbucket and Jira, the author is the person who reported the issue.
GitHub source
--owner OWNER--source github. It can also come from [repo] owner in .briar.toml or from the git origin remote. Example: --owner acme-co.--repo REPO--source github. It can also come from .briar.toml or git. Example: --repo acme-app.Login for this source uses --auth-mode and --github-secret-id from Core.
Bitbucket source
--bitbucket-workspace WORKSPACE/ in a repo URL. Needed with --source bitbucket. Example: --bitbucket-workspace acme-co.--bitbucket-repo REPO/. Needed with --source bitbucket. Example: --bitbucket-repo acme-app.--bitbucket-secret-id UUID--auth-mode pat. Example: --bitbucket-secret-id 3f2b8c1e-5d4a-4f6b-9a7c-1e2d3c4b5a69.Jira source
--jira-project KEYdefault: all projects--jira-project ACME.--jira-jql JQL--jira-jql "labels = agent".--jira-secret-id UUID--jira-secret-id 3f2b8c1e-5d4a-4f6b-9a7c-1e2d3c4b5a69.AWS source
--aws-role-arn ARN--aws-role-arn arn:aws:iam::123456789012:role/briar-read.--aws-external-id ID--aws-external-id acme-briar.--aws-region REGIONdefault: us-east-1--aws-region us-west-2.--aws-services SERVICEdefault: ec2, iam, logs--aws-services ecs --aws-services rds.Sentry source
--sentry-org ORG--source sentry. Example: --sentry-org acme.--sentry-project PROJECT--sentry-project acme-api.--sentry-environment ENVdefault: all environments--sentry-environment production.--sentry-query QUERY--sentry-query "is:unresolved level:error".--sentry-level LEVELdefault: all levelsfatalerrorwarninginfodebug--sentry-level error.--sentry-secret-id UUID--source sentry: Sentry has no OAuth option yet. Example: --sentry-secret-id 3f2b8c1e-5d4a-4f6b-9a7c-1e2d3c4b5a69.Trigger flags
These only matter for the matching --trigger-kind. For other kinds they are ignored.
GitHub webhook (--trigger-kind github_webhook)
--webhook-events EVENTdefault: issues.opened, issues.labeled--webhook-events issues.opened.--webhook-labels LABELdefault: briarbriar always stays in the list. A value you pass is added to it, not used instead. Example: --webhook-labels agent-ready gives ["briar", "agent-ready"].Bitbucket webhook (--trigger-kind bitbucket_webhook)
--bitbucket-webhook-events EVENTdefault: issue:created, issue:updated--bitbucket-webhook-events issue:created.--bitbucket-webhook-labels LABELdefault: briarbriar always stays and your values are added. Example: --bitbucket-webhook-labels agent-ready.Cron timer (--trigger-kind schedule_cron)
--schedule CRONdefault: 0 * * * *--schedule "*/30 * * * *" (every 30 minutes).Good to know
- Nothing in briar reads the bundle back. Your orchestrator must know this format.
- Missing required flags fail before anything is written. For example:
--source github requires --owner AND --repo, or--source sentry requires --sentry-secret-id. - In a folder with a
.briar.toml, briar fills--company,--owner,--repoand--modelfrom it. So the bundle may hold your knowledge even if you did not pass--company. A flag on the command line always wins. - With only an
awssource, there is no repo to name the agent after. briar uses the prefix and logs a warning. - Each run is saved as a session in the decision journal. See it with
briar journal list.
See also
- Plugin registries: every archetype, shape, trigger and source name.
- briar agent: run an agent on your own machine, no orchestrator needed.
- briar runbook: keep the knowledge that
--companyreads up to date.