Skip to content

CLI reference

Auth, secrets and telemetry

Three commands for your keys and your data. briar auth logs you in to GitHub, Jira, AWS and the rest, and saves the keys. briar secrets checks that the keys your runbooks need are set. briar telemetry shows and sets what usage data briar sends home.

How briar finds your keys

briar reads every key from an env var. An env var is a named value in your shell, like GITHUB_TOKEN. Most names hold your company name, so one machine can work for many companies. With --company acme, the Jira token is JIRA_ACME_TOKEN. briar puts the name in upper case and turns - into _, so acme-co becomes JIRA_ACME_CO_TOKEN. The GitHub token has no company part. It is always GITHUB_TOKEN.

You can set these vars by hand. Or you can let briar auth login ask for each value and save it for you. It saves into a store. A store is a place that keeps secrets. The default store is envfile: a plain text file with one NAME=value per line.

Where the env file lives

briar picks the first path that applies:

  1. The path in BRIAR_SECRETS_FILE, if you set it.
  2. /etc/briar/secrets.env, if that file exists. This is for servers.
  3. $XDG_CONFIG_HOME/briar/secrets.env. When XDG_CONFIG_HOME is not set, that is ~/.config/briar/secrets.env.

Each time you run a command, briar loads this file into its env first. A var you already set in your shell wins over the file. briar writes the file so only your user can read it (mode 600). It will not load a few risky names from the file, such as PATH, PYTHONPATH, LD_PRELOAD, the proxy vars and the SSL cert vars. Set those in your shell if you need them.

The four stores

StoreWhere the key goesWhat it needs
envfileThe env file above, plus the running process.Nothing. This is the default.
aws-secretsmanagerAWS Secrets Manager, one secret per key, named briar/GITHUB_TOKEN and so on.AWS access through the normal AWS chain (your profile, SSO, or a server role). The region comes from AWS_REGION or your AWS config.
ssmAWS SSM Parameter Store, as encrypted SecureString values named /briar/GITHUB_TOKEN and so on.AWS access, same as above.
vaultHashiCorp Vault, KV v2 at mount secret, path briar/GITHUB_TOKEN, field value.VAULT_ADDR and VAULT_TOKEN, plus pip install "briar-cli[vault]".

Which stores feed the real work

extract, agent, plan and runbook read keys from env vars. At start, briar loads the env file, then (since 1.1.92) every key of the store named by $BRIAR_DEFAULT_STORE when that is Vault, SSM or Secrets Manager. A key already in your shell or the env file wins. Keys in any other store are not loaded; get them into the env yourself.

briar auth

Logs you in to one service and saves the keys it gets. Each subcommand takes a target: the thing you log in to. It can also list and check the keys you have, and delete them.

Use it when

  • You set up briar on a new laptop or server.
  • A token expired and a command now fails with 401.
  • You add a new company or a new service, like Linear.
  • You want to see which keys are set without printing them.

The login targets

briar opens the right web page for you when it can. Over SSH it prints the link instead. It never prints a key value. The table uses --company acme.

TargetWhat it asks forEnv vars it writes
github-patA GitHub personal token you paste. Make a classic token with the repo and read:org scopes. No company needed.GITHUB_TOKEN
github-deviceNothing to paste. You open github.com/login/device and type a short code. It asks for repo and read:org. It needs BRIAR_GITHUB_CLIENT_ID: the client ID of a GitHub OAuth app with device flow turned on. No company needed.GITHUB_TOKEN
bitbucket-app-passwordYour Bitbucket workspace, your user name (not your email) and an app password. Give the app password read and write on repos and pull requests.BITBUCKET_ACME_WORKSPACE, BITBUCKET_ACME_USERNAME, BITBUCKET_ACME_APP_PASSWORD
aws-staticAn IAM user's access key ID, its secret key, and a region (default us-east-1). The key only needs read rights.AWS_ACME_ACCESS_KEY_ID, AWS_ACME_SECRET_ACCESS_KEY, AWS_ACME_REGION
aws-ssoYour SSO start URL and SSO region. You approve in the browser. If you can use more than one account or role, you pick one. The keys are short lived; briar prints when they expire.AWS_ACME_ACCESS_KEY_ID, AWS_ACME_SECRET_ACCESS_KEY, AWS_ACME_SESSION_TOKEN, AWS_ACME_REGION
jira-tokenYour Jira URL (like https://acme.atlassian.net), your Atlassian email, and an API token.JIRA_ACME_URL, JIRA_ACME_EMAIL, JIRA_ACME_TOKEN, and JIRA_ACME_AUTH_KIND=token
jira-sessionYour Jira URL and the tenant.session.token cookie, copied from your browser's dev tools. Use it when your site does not let you make an API token. briar prints when the cookie expires.JIRA_ACME_URL, JIRA_ACME_TENANT_SESSION_TOKEN, and JIRA_ACME_AUTH_KIND=session
linear-api-keyA Linear personal API key you paste.LINEAR_ACME_TOKEN
firefliesA Fireflies API key, from Settings, then the Developer Settings tab.FIREFLIES_ACME_API_KEY

Parameters every auth subcommand shares

TARGETrequired
github-devicegithub-patbitbucket-app-passwordaws-staticaws-ssojira-tokenjira-sessionlinear-api-keyfireflies
The thing you log in to. It is a plain word after the subcommand, not a flag. auth list is the only subcommand without it. Example: briar auth login jira-token.
--company COMPANY
Your name for the company. It goes into the env var names. All targets need it except github-pat and github-device. Without it, login stops with an error, and status and logout find nothing to check. The company line in .briar.toml or BRIAR_COMPANY fills it in for you. Example: --company acme.
--cred-store STOREdefault: envfile
envfileaws-secretsmanagerssmvault
Which store to read or write. The default is the value of BRIAR_DEFAULT_STORE when it names a store, else envfile. The old name --store still works and prints a note. Example: --cred-store vault.

$ briar auth login

briar auth login TARGET [--company COMPANY] [--cred-store STORE]

Walks you through one login and saves the keys. It shows the steps, asks for each value, and hides what you paste. Then it prints each env var name with ok or FAIL.

Examples

# Save a GitHub token. No company needed.
$ briar auth login github-pat

You get GITHUB_TOKEN in your env file.

# Jira with an API token, for the company acme.
$ briar auth login jira-token --company acme

You get JIRA_ACME_URL, JIRA_ACME_EMAIL, JIRA_ACME_TOKEN and JIRA_ACME_AUTH_KIND.

# Jira when your site blocks API tokens: use the browser cookie.
$ briar auth login jira-session --company acme

You get the Jira URL and the session cookie, and its end date.

# AWS through SSO in the browser.
$ briar auth login aws-sso --company acme

You get short-lived AWS keys for the account and role you pick.

# The rest of the targets.
$ briar auth login github-device
$ briar auth login bitbucket-app-password --company acme
$ briar auth login aws-static --company acme
$ briar auth login linear-api-key --company acme
$ briar auth login fireflies --company acme

Each one asks for what the table lists, and writes those env vars.

# Save into Vault instead of the env file.
$ briar auth login github-pat --cred-store vault

You get the token in Vault at secret/briar/GITHUB_TOKEN. Read the warning in The four stores first.

Good to know

  • It needs a terminal. With no input it stops with a clear error. You can pipe the answers in on stdin.
  • Running it again replaces the old value. It does not add a second line.
  • It exits with 1 when a key could not be saved. The output says why.

$ briar auth logout

briar auth logout TARGET [--company COMPANY] [--cred-store STORE] [--yes]

Deletes the keys that login would write for this target. It lists them and asks first.

Examples

# See what would go, then answer y or n.
$ briar auth logout jira-token --company acme

You get the four JIRA_ACME_* names, then a prompt.

# No prompt, for scripts.
$ briar auth logout github-pat --yes

You get GITHUB_TOKEN removed from the env file.

# Remove from SSM instead.
$ briar auth logout aws-static --company acme --cred-store ssm --yes

You get the three AWS parameters under /briar/ deleted.

Parameters

--yes
Skip the yes or no question and delete right away. Off by default. Without it, any answer but y or yes stops with exit code 1. Example: --yes.

It also takes TARGET, --company and --cred-store, as above.

Secrets Manager has no undo

With aws-secretsmanager, logout deletes the secret with no recovery window. You cannot get it back.

$ briar auth refresh

briar auth refresh TARGET [--company COMPANY] [--cred-store STORE]

Meant to renew keys without asking you again. No target supports it yet. Every target prints credential expired: ... with the login command to run, and exits with code 2.

Examples

# Today this tells you to log in again.
$ briar auth refresh aws-sso --company acme

You get a line that says to run briar auth login aws-sso --company acme.

# So, when a key expires, run login again.
$ briar auth login aws-sso --company acme

It takes TARGET, --company and --cred-store, as above.

$ briar auth list

briar auth list [--company COMPANY] [--cred-store STORE]

Lists the names of the keys a store holds. It never prints values. It takes no target.

Examples

# Every key name briar knows about in your env.
$ briar auth list
store=envfile 3 entry(ies):
GITHUB_TOKEN
JIRA_ACME_EMAIL
JIRA_ACME_URL

You get one name per line. For envfile this is every briar key name in the current env: from your shell and from the env file.

# Only names that hold the company part ACME.
$ briar auth list --company acme

You get JIRA_ACME_URL and the like, but not GITHUB_TOKEN.

# What is saved in Vault.
$ briar auth list --cred-store vault

You get every key name under briar/.

Parameters

--company COMPANY
Keep only the names that hold this company part. Off by default, but .briar.toml or BRIAR_COMPANY can set it. Pass --company "" to see all. Example: --company acme.

--cred-store works as above.

$ briar auth status

briar auth status TARGET [--company COMPANY] [--cred-store STORE]

Checks one target for one company. For each env var that login would write, it prints ok or MISS.

Examples

$ briar auth status jira-token --company acme
auth-status: target=jira-token company=acme store=envfile
ok JIRA_ACME_URL
ok JIRA_ACME_EMAIL
MISS JIRA_ACME_TOKEN
MISS JIRA_ACME_AUTH_KIND

You get exit code 1, because two names are missing. With all ok it exits with 0, so it works in CI.

$ briar auth status github-pat
$ briar auth status aws-sso --company acme --cred-store aws-secretsmanager

You get one line for GITHUB_TOKEN, then four lines for the AWS keys in Secrets Manager.

It takes TARGET, --company and --cred-store, as above. It does not test the key against the service. It only checks that a value is there.

briar secrets

Two helpers for keys. doctor reads your runbooks and tells you which keys are missing. bootstrap loads the env file on demand, so you can see what it holds.

$ briar secrets doctor

briar secrets doctor [--examples DIR] [--cred-store STORE]

Reads each runbook YAML in a folder. For each company, it checks the keys that every scheduled extractor needs, and every messages: channel. It prints names and ok or X. It never prints values.

Use it when

  • You wrote a new runbook and want to know what to log in to.
  • A scheduled run failed and you suspect a missing key.
  • You want a check in CI before you deploy a runbook.

Examples

# Check the runbooks in runbooks/ against your env.
$ briar secrets doctor --examples runbooks/

You get a === acme (acme.yaml) === header for each company. Under it is one line per extractor and per channel. A line starts with ok, or with X and the names of the missing keys. The exit code is 1 when any key is missing, else 0.

# Check against Secrets Manager instead of the env.
$ briar secrets doctor --examples runbooks/ --cred-store aws-secretsmanager

You get the same report, but each key is looked up in AWS.

# No flag: uses ./examples if that folder exists.
$ briar secrets doctor

With no ./examples folder you get no runbooks to check and exit code 0.

Parameters

--examples DIRdefault: ./examples
The folder with your runbook YAML files. It reads files that end in .yaml, not .yml, and not in sub folders. A folder you name that does not exist gives exit code 1. Example: --examples runbooks/.
--cred-store STOREdefault: envfile
envfileaws-secretsmanagerssmvault
Where to look for each key. envfile means the current env, with the env file loaded. Unlike auth, this one ignores BRIAR_DEFAULT_STORE. The old name --store still works. Example: --cred-store ssm.

Good to know

  • A YAML that fails to load is reported and skipped. An unknown extractor or channel kind gets a ?.
  • For Jira, the list depends on the login kind. A token needs the URL, email and token. A browser session needs the URL and one session cookie, but doctor lists both cookie names. If one of them is set, an X for the other is safe to ignore.
  • For AWS it asks for AWS_ACME_ACCESS_KEY_ID and AWS_ACME_SECRET_ACCESS_KEY. If you use a ~/.aws profile or a server role instead, that X is safe to ignore.

$ briar secrets bootstrap

briar secrets bootstrap [--kind envfile] [--dry-run]

Loads keys into the env, the same way briar does at the start of every command. Today the only loader is envfile: it reads the env file. Because briar already does this on each run, you mostly use this command to debug: to see which keys the file holds.

Examples

# Show which names the env file would set. Sets nothing.
$ briar secrets bootstrap --dry-run
bootstrap envfile: would write 0 env vars (preserved 3 already-set)

You get a count. "Preserved" means the name was already set, so the file does not change it. Here all three names in the file are preserved, because briar loaded the file when this command started. That is normal. A name that the file could still set is listed after keys:.

# Force the envfile loader, and fail if there is no file.
$ briar secrets bootstrap --kind envfile

With no env file you get not configured and exit code 1.

Parameters

--kind KIND
envfile
Run one loader by name. If it is not set up, it stops with exit code 1. Leave it out to run every loader that is set up. With no env file, that is none, and it exits with 0. Example: --kind envfile.
--dry-run
Read the keys, but do not set them. It prints only the names, never the values. Off by default. Example: --dry-run.

briar telemetry

Telemetry is the usage data briar sends to its makers. It goes to Sentry, an error tracking service. It is on by default (the full level). These six subcommands show it, preview it and turn it down or off.

What is sent

Use it when

  • You want to read the exact data before you trust it.
  • Your company does not allow usage data.
  • You run briar in CI or on a server and want no extra calls out.

briar sends one event per command. When the command fails, that event is an error event. An event holds:

  • The top command name, like extract or plan.
  • The result (ok, error or interrupt), the time it took, and the exit code when there is one.
  • An install ID. briar makes a random ID once and sends only the first 16 hex digits of its SHA-256 hash.
  • The briar version, the Python version, and the OS name and release.
  • The names of the flags you set. Never their values.
  • For an error: the error type and the error message, cleaned first.

What is cleaned or never sent

  • briar never hands prompts, model replies or file contents to telemetry. Flag values are never sent, only flag names.
  • Any field not on a fixed allow list is dropped before sending.
  • A value that looks like a secret becomes <redacted-secret>. That covers AWS keys, GitHub tokens, Anthropic and OpenAI keys, Slack tokens, private keys and JWT-like strings.
  • A full file path becomes <path>. Each value is cut at 1024 characters.
  • The Sentry client runs with its personal data option off, with no local variables in stack traces, and with no breadcrumbs.
  • briar -h and briar --version start no telemetry at all.

Error messages can name your things

The cleaner removes secrets and paths, not names. If an error message names a repo, a blob or a ticket, that text is sent with the error. If that matters to you, use off.

The three levels

LevelWhat is sent
fullError events and one usage event per command. The default.
errors-onlyError events only.
offNothing.

Which setting wins

  1. DO_NOT_TRACK=1 turns it off, always. The value must be exactly 1.
  2. BRIAR_TELEMETRY set to off, errors-only or full. It counts for that run only. A bad value is ignored with a warning.
  3. The level you saved with briar telemetry off and friends. It lives in ~/.config/briar/telemetry.json (or under $XDG_CONFIG_HOME/briar/).
  4. Else full.

The first time you run a command, briar prints a short notice about this on stderr, once. It skips the notice when the level comes from DO_NOT_TRACK or BRIAR_TELEMETRY. Two more env vars: BRIAR_SENTRY_DSN sends events to your own Sentry project, and BRIAR_ENV sets the environment tag (default production).

# Off for one run only.
$ BRIAR_TELEMETRY=off briar doctor
# Off for this shell, and for every tool that honors DO_NOT_TRACK.
$ export DO_NOT_TRACK=1

With DO_NOT_TRACK=1 or BRIAR_TELEMETRY=off, briar also skips its daily check for a newer version on PyPI.

$ briar telemetry status

briar telemetry status

Prints the level in use and where it came from. It takes no flags of its own.

$ briar telemetry status
$ briar telemetry status --format yaml
tier: full
source: config-file
enabled: true
install_id_hashed: 1d197c728ec6246b
dsn_configured: true
default_dsn_set: true
state_path: /home/dana/.config/briar/telemetry.json
install_id_path: /home/dana/.config/briar/install_id
config_dir: /home/dana/.config/briar

You get the level (tier) and its source: do-not-track, env, config-file or default. You also get the hashed ID that is sent, and the file paths.

$ briar telemetry preview

briar telemetry preview [--for-command NAME]

Prints the JSON event briar would send for a command. It sends nothing itself. Use it to read the payload before you decide.

$ briar telemetry preview --for-command extract
{
"command": "extract",
"duration_ms": 0,
"error_message": "",
"error_type": "",
"kind": "command",
"outcome": "preview",
"tags": {
"briar_version": "1.1.75",
"command": "extract",
"install_id": "1d197c728ec6246b",
"os_name": "darwin",
"os_release": "23.6.0",
"python_version": "3.11.7"
}
}

You get the event shape. A real run also adds the flag names, the time and the result.

--for-command NAMEdefault: (preview)
The command name to put in the event. Any text works. Real events use the top command name, like extract or plan. Example: --for-command plan.

$ briar telemetry off

briar telemetry off

Saves the off level. From the next command on, briar sends nothing. It prints the level and the file it wrote.

$ briar telemetry off
{
"tier": "off",
"state_path": "/home/dana/.config/briar/telemetry.json"
}

An env var still wins over this file. If BRIAR_TELEMETRY=full is set, events are sent.

$ briar telemetry errors-only

briar telemetry errors-only

Saves the errors-only level. briar sends error events, and no usage events.

$ briar telemetry errors-only

$ briar telemetry full

briar telemetry full

Saves the full level: errors and usage. This is the default, so you only need it to undo off or errors-only.

$ briar telemetry full

$ briar telemetry reset

briar telemetry reset

Deletes your install ID and makes a new one. Events from now on cannot be linked to your old ones. It prints the new hashed ID.

$ briar telemetry reset
{
"rotated": true,
"install_id_hashed": "12b57c4c45c0d9fa",
"install_id_path": "/home/dana/.config/briar/install_id"
}

Output format

status, off, errors-only, full and reset print JSON by default. Add the global --format yaml for YAML. preview always prints JSON. Each telemetry command is itself a command run, so it sends its own event under the level in use when it starts.

See also