CLI reference
briar runbook
What a runbook is
A runbook is a YAML file. You usually keep one file per company. It holds your settings, so you do not have to type a long briar extract command each time.
A runbook says:
- What to extract: which extractors to run, with which settings. An extractor reads one source (pull requests, tickets, cloud setup) and writes a short markdown summary.
- How often: each schedule has a name and a timer, like
"hour"or"day at 03:17". - Where to save: the knowledge store, which is a folder of files or a Postgres database.
- Where agents may post: the
messages:block names the Jira, GitHub, Bitbucket, Slack or Telegram channels an agent may write to. - Which MCP servers agents get. MCP servers are extra tool servers, for example a GitHub or Sentry server.
- Who agents commit as: a git name and email.
briar runbook uses the first three. The last three are read by briar agent and briar plan run when you pass --runbook. Here is a small runbook:
version: 1companies:acme:knowledge:store: filename: knowledge:acmeschedules:- task: nightlyevery: "day at 03:17"extract:- name: pr-archaeologyargs:repo: [acme-co/acme-app]- task: ticketsevery: "hour"extract:- name: active-ticketsargs:tracker: jiraticket_project: [ACME]
This file has two jobs for the company acme. The nightly job studies past pull requests once a day. The tickets job reads open Jira tickets every hour. Every key is explained on the runbook YAML reference.
When to use it
- You run the same
briar extractcommand again and again. Put it in a file and keep the file in git. - You want fresh knowledge every hour or every night, without cron.
- You look after several companies or repos from one machine.
- You want agents to post to fixed channels, use MCP servers, or commit with a set name.
The three subcommands
| Command | What it does | Use it for |
|---|---|---|
| runbook extract | Runs the jobs in one file, once, now. | Testing a file. Refreshing one company by hand. |
| runbook sweep | Runs every job in every *.yaml file in a folder, once, now. | Refreshing all companies at once. |
| runbook serve | Stays running and starts each job when its timer is due. | A server that keeps knowledge fresh all day. |
All three write the result to the knowledge store named in the file. None of them runs an agent.
$ briar runbook extract
briar runbook extract [--task TASK] FILERuns the jobs in one runbook file, one time, and then exits. Without --task it runs every job of every company in the file.
Use it when
- You just wrote or changed a runbook and want to try it.
- You need fresh knowledge now and cannot wait for the timer.
- You want to run one job, like
tickets, by hand.
Examples
# Run every job in the file, once.$ briar runbook extract runbooks/acme.yaml
You get one row per company and job. Each row shows if briar wrote the result, skipped it, or failed.
# Run only the job named "tickets".$ briar runbook extract runbooks/acme.yaml --task tickets
You get fresh ticket knowledge. The other jobs in the file do not run.
# Print the result rows as JSON (handy in scripts).$ briar runbook extract runbooks/acme.yaml --task nightly --format json
You get a JSON list with company, task, status and output for each row.
# Check the file only. No job has this name, so nothing runs.$ briar runbook extract runbooks/acme.yaml --task check-only
briar loads and checks the whole file. If a key, extractor name or message kind is wrong, you get an error that points at it. If the file is fine, you get an empty table.
All parameters
FILE PATHrequired.yaml or .yml are read as YAML. Any other file is read as JSON. Example: runbooks/acme.yaml.--task TASKdefault: (empty: run every job)task: name matches. It runs that job for every company in the file that has it. The simple extract: list of a company is the job named extractors. Example: --task tickets.--format FORMATdefault: tabletablejsonyamlcsvquiet--format json.What the status column means
| Status | Meaning |
|---|---|
wrote N bytes via store=file | The summary changed, so briar saved the new version. |
skipped (unchanged, ...) | The summary is the same as last time. briar did not write it again. |
empty (no sections) | No extractor returned anything. Often this means credentials are missing. |
failed (...) | briar could not open or write the knowledge store. This also sends a failure alert. |
skipped (no schedule) | The company has no jobs at all. |
The output column is the name of the knowledge blob (saved summary) that the job wrote.
$ briar runbook sweep
briar runbook sweep DIRECTORYRuns runbook extract on every *.yaml file in a folder, one file after another. Every job in every file runs once.
Use it when
- You set up a new machine and want all knowledge filled in now.
- You changed many runbooks and want to refresh them all.
- You start
runbook serveand do not want to wait for the first timers.
Examples
# Run every runbook in the runbooks/ folder, once.$ briar runbook sweep runbooks/
You get a --- acme.yaml --- header and a result table for each file.
# Same, but print each file's rows as JSON.$ briar runbook sweep runbooks/ --format json
You get one JSON list per file, after its header line.
All parameters
DIRECTORY PATHrequired.yaml, sorted by name. It does not look in sub-folders. Example: runbooks/.--format FORMATdefault: tabletablejsonyamlcsvquietrunbook extract.Good to know
- A file that fails to load does not stop the sweep. briar logs the error, moves to the next file, and exits with code 1 at the end.
- Files ending in
.ymlare skipped. Rename them to.yaml. - An empty folder is not an error. briar prints
sweep: no *.yaml under runbooksand exits 0.
$ briar runbook serve
briar runbook serve [--tick TICK] DIRECTORYStarts a scheduler that keeps running. It reads every *.yaml file in the folder, sets a timer for each company and job, and runs each job when its timer is due. It stops only when you press Ctrl-C or stop the service.
Use it when
- You want knowledge refreshed all day, on a server.
- You do not want to manage cron jobs.
- You run briar as a system service (for example with systemd).
Examples
# Start the scheduler for every runbook in runbooks/.$ briar runbook serve runbooks/
You get one registered company=... task=... every=... log line per job, then a scheduler starting: N job(s) line. After that, a log line each time a job starts and ends.
# Fill everything in now, then keep it fresh.$ briar runbook sweep runbooks/$ briar runbook serve runbooks/
You get full knowledge right away. The scheduler waits for each job's first time, so the sweep fills the gap.
# Check the timers less often (every 5 seconds).$ briar runbook serve runbooks/ --tick 5
You get the same jobs. Each one may start up to 5 seconds late.
All parameters
DIRECTORY PATHrequired*.yaml files are read. Example: runbooks/.--tick TICKdefault: 1--tick 5.Run it as a service
briar runbook serve as a systemd service and the dashboard next to it.How the scheduler works
runbook serve has its own scheduler inside the briar process. You do not need cron.
- At start, briar reads each
*.yamlfile in the folder. It makes one timer per company and job. - A job with a clock time (
"day at 03:17") runs at that time. Clock times are UTC. - A job without a clock time (
"hour","4 hours") gets a fixed offset inside its period. The offset comes from the company and job name, so it is the same after every restart. Two companies on"hour"do not hit GitHub at the same minute. - Every
--tickseconds, briar checks for due jobs and runs them. It runs one job at a time, so a slow job delays the next one. - When a job runs, briar reads the YAML file again. So a change to an extractor's
args:works at the next run. A new job or a new timer needs a restart. - If a job fails, briar logs the error and keeps going. The other jobs still run.
Timer strings for every:
The every: value of a schedule accepts these forms. Case does not matter.
| Form | Examples | Runs |
|---|---|---|
| a unit | minute, hour, day, week | Once per unit, at the fixed offset. |
| a number and a unit | 5 minutes, 4 hours, 2 days, 2 weeks | Once per that many units, at the fixed offset. |
| a weekday | monday to sunday | Once a week. Add a time (next row) so it lands on that day. |
day or weekday at HH:MM | day at 03:17, 2 days at 06:00, monday at 09:00 | At that UTC time. The hour needs two digits. |
hour at :MM | hour at :15, 2 hours at :15 | At that minute past the hour. |
minute at :SS | minute at :30 | At that second of each minute. |
These do not work: daily, every day, day at 3:17 (one-digit hour), week at 09:00, 2 mondays, and hour at 15. Also, an hour time like hour at 00:15 means 0 minutes and 15 seconds. Use hour at :15. The full list with more examples is in the runbook YAML reference.
Only serve checks the timer strings
runbook extract and sweep ignore every:. A bad value shows up only when runbook serve starts, and then serve exits with an error.Failure alerts (BRIAR_NOTIFY_SINKS)
briar can tell you when a job fails. Set BRIAR_NOTIFY_SINKS to a comma-separated list of places to send the alert. This works for extract, sweep and serve.
$ export BRIAR_NOTIFY_SINKS=slack,email
The alert title is briar: acme / tickets failed. The body holds the reason and the start of the error.
| Sink | Env vars it needs (company acme) |
|---|---|
slack | SLACK_ACME_WEBHOOK_URL (a Slack incoming webhook) |
telegram | TELEGRAM_BOT_TOKEN and TELEGRAM_ACME_CHAT_ID |
email | SMTP_HOST and EMAIL_ACME_TO (comma-separated addresses). Optional: SMTP_PORT (default 587), SMTP_USER, SMTP_PASSWORD, SMTP_STARTTLS (default true), EMAIL_FROM (default: the SMTP user). |
pagerduty | PAGERDUTY_ACME_ROUTING_KEY |
- A sink with missing env vars is skipped. An unknown sink name is logged and skipped. A sink that fails never stops the job.
- An alert goes out when a job cannot open or write its knowledge store. One extractor that fails, or has no credentials, is logged and skipped. That does not send an alert.
- Alerts are not the same as the runbook
messages:block.messages:is where agents may post. Alerts are for you.
Good to know
- Credentials come from env vars and never go in the runbook. Most are per company, like
JIRA_ACME_TOKEN. To list what is missing, run the command below. See Configuration for every name. - Missing credentials do not fail the job. The extractor is skipped with a warning in the log. If every extractor is skipped, the status is
empty (no sections). - Each company's job runs only that company, so two companies in one file can share a task name. Before 1.1.90,
serveran a shared task for every company each time any company's job fired (twice per period with two companies). - All three subcommands log progress at INFO level to stderr, even though other briar commands are quiet. Add
--verbosefor debug logs. - briar compares the new summary with the saved one. If nothing changed, it does not write it again.
briar runbookworks in the Docker imageiklob1/briar. So do agents: the image hasgitandgh. See Agents in Docker.
# List the env vars your runbooks need but do not have.$ briar secrets doctor --examples runbooks/
You get one line per company, extractor and message channel, with ok or the names of the missing env vars. It never prints the values.
See also
- Runbook YAML reference: every key, with examples.
- briar extract: the same extractors, run from the command line.
- briar agent: reads
messages:,mcp:andgit_identity:with--runbook. - Recipes: full setups from start to end.