CLI reference

briar scaffold

Emit a JSON config bundle that a downstream orchestrator (a hosted Briar deployment, a custom worker) consumes to wire up a full agent flow. The CLI doesn't execute the flow itself — it generates the bundle.

When to use it

Stand up a new agent flow against a fresh repo or company.
You want a JSON contract a downstream deployment can consume.
You want a default config you can hand-edit, version-control, or template across companies.

If you're running the agent directly on your machine, you don't need scaffold — briar agent implement / prfix are the direct path.

Two templates ship

Template	Shape
`implementation`	Issue → plan → human approval → implement / comment
`pr-fixes`	Read PR review comments → push fixes → reply (no human gate)

$ briar scaffold implementation

briar scaffold implementation --prefix NAME --source SRC
                            [--archetype ARCH] [--shape SHAPE]
                            [--trigger-kind KIND] [--auth-mode {oauth,pat}]
                            [<source-specific flags>] [--out FILE]

Most common: issue → plan → approve → implement.

$ briar scaffold implementation \
    --prefix acme \
    --source github --owner acme --repo widgets \
    --archetype engineer --shape plan-approve-act \
    --trigger-kind github_webhook \
    --auth-mode oauth \
    --out acme-implementation.json

$ briar scaffold pr-fixes

briar scaffold pr-fixes --prefix NAME --source SRC
                       [<same flags as implementation>] [--out FILE]

Same flag set as implementation; the template differs in the default shape and tool wiring.

$ briar scaffold pr-fixes \
    --prefix acme \
    --source github --owner acme --repo widgets \
    --auth-mode pat --github-secret-id <UUID> \
    --out acme-prfix.json

Multi-source bundles

Pass --source repeatedly to bundle multiple sources into one config — e.g. --source github --source jira --source aws.

Core flags

--prefix NAMErequired

Prefix prepended to every resource name in the emitted bundle.

--source {aws,bitbucket,github,jira,sentry}

awsbitbucketgithubjirasentry

Source kind(s) to gather context from. Repeat for multiple.

--archetype ARCHETYPEdefault: engineer

engineerpr-ci-fixerpr-conflict-resolverpr-fixertriager

Agent role + tool filter.

--shape SHAPEdefault: plan-approve-act

one-shotplan-approve-acttriage

Workflow graph shape. plan-approve-act includes a human checkpoint; one-shot skips it (good for the pr-fixer archetype on a cron).

--trigger-kind KIND

bitbucket_webhookgithub_webhookmanualschedule_cron

What kicks off a run.

--auth-mode {oauth,pat}default: oauth

oauthpat

GitHub auth mode. OAuth handshake or stored PAT. Sentry is always PAT.

--llm-provider-key KEY

LLMProvider config key in the downstream orchestrator.

--model MODEL

LLM model ID passed to LiteLLM as <provider>/<model>.

--company COMPANY

Company name whose extracted knowledge to splice into the agent's system prompt. Omit to emit a knowledge-aware persona without cached sections.

--knowledge-store STORE

Knowledge-store backend to read the splice from. Default: postgres if BRIAR_DATABASE_URL is set, else file.

--out PATH

Output path. Default: stdout. Short form: -o.

GitHub source flags

--owner OWNER

GitHub org / user. Required when --source github.

--repo REPO

GitHub repo name. Required when --source github.

--github-secret-id UUID

Secret UUID holding a GitHub PAT. Required with --auth-mode pat.

--github-authors-allow LOGIN

Only include issues whose creator is in this list. Repeatable.

--github-authors-block LOGIN

Exclude issues whose creator is in this list. Repeatable.

--github-assignees-allow LOGIN

Only include issues with an assignee in this list. Repeatable.

--github-assignees-block LOGIN

Exclude issues with an assignee in this list. Repeatable.

--webhook-events EVENTSdefault: issues.opened, issues.labeled

GitHub event names that fire the trigger.

--webhook-labels LABELSdefault: briar

Restrict to issues with any of these labels.

Bitbucket source flags

--bitbucket-workspace SLUG

Workspace slug (the part before / in a repo URL).

--bitbucket-repo SLUG

Repository slug (the part after /).

--bitbucket-secret-id UUID

Secret UUID holding a Bitbucket app-password (username + app_password stored together). Required with --auth-mode pat.

--bitbucket-authors-allow LOGIN

Reporter allowlist. Repeatable.

--bitbucket-authors-block LOGIN

Reporter blocklist. Repeatable.

--bitbucket-assignees-allow LOGIN

Assignee allowlist. Repeatable.

--bitbucket-assignees-block LOGIN

Assignee blocklist. Repeatable.

--bitbucket-webhook-events EVENTSdefault: issue:created, issue:updated

Bitbucket event names.

--bitbucket-webhook-labels LABELSdefault: briar

Restrict to issues with these labels.

Jira source flags

--jira-project KEY

Jira project key to include. Repeatable; defaults to all.

--jira-jql JQL

Optional JQL filter applied on top of the project list.

--jira-secret-id UUID

Secret UUID holding an Atlassian PAT (skip OAuth).

--jira-authors-allow USER

Reporter allowlist. Folds into JQL. Repeatable.

--jira-authors-block USER

Reporter blocklist. Folds into JQL. Repeatable.

--jira-assignees-allow USER

Assignee allowlist. Folds into JQL. Repeatable.

--jira-assignees-block USER

Assignee blocklist. Folds into JQL. Repeatable.

AWS source flags

--aws-role-arn ARN

IAM role ARN the worker assumes to read AWS resources.

--aws-external-id ID

External-id required by the trust policy on --aws-role-arn.

--aws-region REGION

Default AWS region for resource queries.

--aws-services LIST

Which AWS services to gather (e.g. ec2,s3,iam,logs).

Sentry source flags

--sentry-org SLUG

Sentry organization slug. Required when --source sentry.

--sentry-project SLUG

Sentry project slug to include. Repeatable; at least one required.

--sentry-environment ENV

Restrict to one or more environments. Repeatable.

--sentry-query QUERY

Sentry issue search query (e.g. is:unresolved level:error).

--sentry-level LEVEL

fatalerrorwarninginfodebug

Severity filter. Repeatable.

--sentry-secret-id UUID

Secret UUID holding a Sentry auth token. Required — PAT-only for now.

Schedule trigger flag

--schedule CRONdefault: 0 * * * *

Cron expression for the schedule_cron trigger. Default fires at the top of every hour.