Skip to content

CLI reference

briar scaffold

Write a JSON config bundle that describes a whole agent flow: the model, the data sources, the tools, the agent, the steps, and what starts it. Another system (an agent orchestrator) loads this file and runs the flow. briar only writes the file.

What you get

A JSON file (or JSON on screen). It has these lists, and every name in it starts with your --prefix:

KeyWhat it holds
llm_modelsOne model: the name from --model and the provider key from --llm-provider-key.
sourcesOne entry per --source: where the agent reads issues, errors or cloud state, and how it logs in.
toolsThe actions the agent may take (comment, commit, open a draft PR, ...). The archetype decides which ones stay.
agentsOne agent: its role, goal, rules, tool list and step limit. With --company, its prompt also holds your extracted knowledge.
workflowsThe steps, set by --shape.
triggersWhat 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.

TemplateFlow--archetype--shape--trigger-kind
implementationAn 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.engineerplan-approve-actgithub_webhook
pr-fixesEvery hour, the agent reads review comments on open PRs, pushes fixes and replies. No person approves first.pr-fixerone-shotschedule_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.

ArchetypeJobTools it keepsMax steps
engineerMake the change a ticket asks for, commit, open a draft PR.All tools from the sources.8
pr-fixerAnswer open review comments with new commits.Comment on issue or PR, commit, open PR.12
pr-ci-fixerFix failing CI checks on open PRs, from the logs.Comment on issue or PR, commit.20
pr-conflict-resolverMerge the base branch into old PRs and fix the conflicts.Comment on issue or PR, commit.16
triagerLabel 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)

ShapeSteps
plan-approve-actThe 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-shotOne step. The agent reads, acts and writes a summary. No person in the loop.
triageOne 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)

TriggerStarts a run whenFlags
github_webhookGitHub sends an issue event and the issue has one of the labels.--webhook-events, --webhook-labels
bitbucket_webhookBitbucket sends an issue event and the issue has one of the labels.--bitbucket-webhook-events, --bitbucket-webhook-labels
schedule_cronThe cron time comes (top of every hour by default).--schedule
manualYou 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.

SourceReadsTools it addsLogin
githubOpen issues in one repo. Needs --owner and --repo.comment, open draft PR, commitOAuth, or a stored token with --auth-mode pat
bitbucketOpen issues and pull requests in one repo. Needs --bitbucket-workspace and --bitbucket-repo.comment, open draft PR, commitOAuth, or a stored app password with --auth-mode pat
jiraOpen issues in some or all projects.comment, change status, edit fieldsAtlassian OAuth, or a stored token if you pass --jira-secret-id
awsCloud state (default services: ec2, iam, logs). Read only.NoneAn IAM role the orchestrator assumes
sentryUnresolved errors in some projects. Needs --sentry-org and a --sentry-project.comment, resolve, assign, ignoreA 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 --archetype and --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
Text put at the start of every name in the bundle. Use something short and unique, like the company or repo. Example: --prefix acme gives acme-engineer, acme-workflow.
--out OUTdefault: stdout
Where to write the JSON. Without it, the JSON is printed. With it, briar writes the file and prints wrote acme.json to stderr. -o is the short form. Example: --out acme.json.
--source SOURCEdefault: github (when none is given)
awsbitbucketgithubjirasentry
A place the agent reads from. Repeat it for more than one. See sources. Example: --source github --source jira.
--archetype ARCHETYPEdefault: engineer (pr-fixes: pr-fixer)
engineerpr-ci-fixerpr-conflict-resolverpr-fixertriager
The agent's job, rules and tool list. See archetypes. Example: --archetype triager.
--shape SHAPEdefault: plan-approve-act (pr-fixes: one-shot)
one-shotplan-approve-acttriage
The steps of the workflow. See shapes. Example: --shape one-shot.
--trigger-kind KINDdefault: github_webhook (pr-fixes: schedule_cron)
bitbucket_webhookgithub_webhookmanualschedule_cron
What starts a run. See triggers. Example: --trigger-kind manual.
--llm-provider-key KEYdefault: anthropic
The name of the model provider config in your orchestrator. briar copies it into llm_models[0].provider_key. Example: --llm-provider-key openai.
--model MODELdefault: claude-sonnet-4-6
The model ID. The orchestrator passes it to LiteLLM as <provider>/<model>. A model under [agent] in .briar.toml also sets it. Example: --model gpt-4o.
--auth-mode MODEdefault: oauth
oauthpat
How the GitHub and Bitbucket sources log in. oauth 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
The ID of the secret, in your orchestrator, that holds a GitHub token. Needed with --auth-mode pat and --source github. Example: --github-secret-id 3f2b8c1e-5d4a-4f6b-9a7c-1e2d3c4b5a69.
--company COMPANYdefault: "" (or company in .briar.toml)
Read this company's extracted knowledge and put it in the agent's 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 STORE
Where to read that knowledge: file (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
Keep only issues written by these users. Example: --authors-allow alice --authors-allow bob.
--authors-block USER
Drop issues written by these users. Example: --authors-block "renovate[bot]".
--assignees-allow USER
Keep only issues assigned to one of these users. Example: --assignees-allow alice.
--assignees-block USER
Drop issues assigned to these users. Example: --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.

SourceFlags
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
The GitHub user or organization. Needed with --source github. It can also come from [repo] owner in .briar.toml or from the git origin remote. Example: --owner acme-co.
--repo REPO
The repo name only, without the owner. Needed with --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
The workspace: the part before / in a repo URL. Needed with --source bitbucket. Example: --bitbucket-workspace acme-co.
--bitbucket-repo REPO
The repo: the part after /. Needed with --source bitbucket. Example: --bitbucket-repo acme-app.
--bitbucket-secret-id UUID
The ID of the secret that holds a Bitbucket user name and app password together. Needed with --auth-mode pat. Example: --bitbucket-secret-id 3f2b8c1e-5d4a-4f6b-9a7c-1e2d3c4b5a69.

Jira source

--jira-project KEYdefault: all projects
A Jira project key to read. Repeat it for more. Without it, all projects are read. The first key also names the agent's target when no GitHub or Bitbucket source comes first. Example: --jira-project ACME.
--jira-jql JQL
An extra Jira search filter (JQL), on top of the project list. Example: --jira-jql "labels = agent".
--jira-secret-id UUID
The ID of a secret that holds an Atlassian token. With it, the source uses that token. Without it, it asks for Atlassian OAuth. Example: --jira-secret-id 3f2b8c1e-5d4a-4f6b-9a7c-1e2d3c4b5a69.

AWS source

--aws-role-arn ARN
The IAM role the orchestrator takes on to read your AWS account. Example: --aws-role-arn arn:aws:iam::123456789012:role/briar-read.
--aws-external-id ID
The external ID that the role's trust policy asks for. Example: --aws-external-id acme-briar.
--aws-region REGIONdefault: us-east-1
The AWS region to read. Example: --aws-region us-west-2.
--aws-services SERVICEdefault: ec2, iam, logs
An AWS service to read. Repeat it for more. Giving any value replaces the whole default list. Example: --aws-services ecs --aws-services rds.

Sentry source

--sentry-org ORG
The Sentry organization slug. Needed with --source sentry. Example: --sentry-org acme.
--sentry-project PROJECT
A Sentry project slug. Repeat it for more. At least one is needed. Example: --sentry-project acme-api.
--sentry-environment ENVdefault: all environments
Read only errors from this environment. Repeatable. Example: --sentry-environment production.
--sentry-query QUERY
A Sentry issue search. Example: --sentry-query "is:unresolved level:error".
--sentry-level LEVELdefault: all levels
fatalerrorwarninginfodebug
Read only errors at this level. Repeatable. briar does not check the value, so type it exactly. Example: --sentry-level error.
--sentry-secret-id UUID
The ID of the secret that holds a Sentry auth token. Always needed with --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
A GitHub event that starts a run. Repeatable. Giving any value replaces the default list. Example: --webhook-events issues.opened.
--webhook-labels LABELdefault: briar
Start a run only for issues with one of these labels. Repeatable. Note: briar 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
A Bitbucket event that starts a run. Repeatable. Giving any value replaces the default list. Example: --bitbucket-webhook-events issue:created.
--bitbucket-webhook-labels LABELdefault: briar
Start a run only for issues with one of these labels. Repeatable. As with GitHub, briar always stays and your values are added. Example: --bitbucket-webhook-labels agent-ready.

Cron timer (--trigger-kind schedule_cron)

--schedule CRONdefault: 0 * * * *
A standard 5-field cron string: minute, hour, day of month, month, day of week. The default runs at the top of every hour. briar copies it as is and does not check it. Example: --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, --repo and --model from 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 aws source, 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