brig docs

Reference

Stability

On this page

Brig has not reached 1.0. You can write a script against the stable surfaces. Other parts can change without notice.

Version numbers #

Brig releases are tagged vMAJOR.MINOR.PATCH.

Kind Example What it can do
Minor release v0.3.0 to v0.4.0 Can remove a retired spelling, and can make other breaking changes.
Patch release v0.3.0 to v0.3.1 Carries fixes only. It is cut from a maintenance branch. It removes nothing and changes no stable surface.
Release candidate A preview of the minor release it names.
Main and experimental Homebrew channels These publish builds, not releases. Their versions promise nothing.

From 1.0, the stable surfaces change only with a new major version.

Stable surfaces #

Each stable surface changes only in two ways: through the deprecation rule, or as a breaking change that the release notes name.

Command grammar #

Every verb and flag that CLI teaches. A retired spelling is covered only until the release that removes it.

Documented settings #

Every BRIG_* variable in the environment variable table in CLI, read in the order that page gives.

A variable that is not in that table, BRIG_TEST_* for example, is internal to Brig. It can change or go without notice.

Profile schema #

The fields that the brig agent export header documents.

Brig refuses a profile file with a field it does not know. A removed field therefore causes an error. Brig does not ignore it silently.

--json envelope #

Within one apiVersion, the JSON only gains fields. It never renames or drops one. No field carries a credential value.

--json works on the read verbs. On run and sh it reports the agent's own exit status.

Exit codes #

script/smoke.sh pins the exit codes end to end. See CLI for the table. brigd reports the same codes for the same causes.

brigd protocol #

Within one protocol version, v, brigd can add a field, but it renames or removes none. A change that breaks a client is a new version, and brigd refuses a version it does not know.

brigd has the details.

File locations #

What Where
Your profiles $XDG_CONFIG_HOME/brig, default ~/.config/brig
Your policies The policies directory inside it
A guest home you name with --home or BRIG_WORKSPACE Where you put it. Brig never deletes it.
Secrets on macOS The login keychain, under the service name sh.brig.secret
Secrets on Linux The default collection of your Secret Service keyring, under the service name sh.brig.secret

The layout of one secret in that store is internal to Brig. Secrets describes it.

Not stable #

These parts can change without a deprecation cycle:

  • The layout of ~/.brig, Brig's state directory, and its session index. This includes the default guest home under ~/.brig/homes, which Brig creates and deletes for you.
  • Profile file fields other than those the current brig agent export header documents.
  • The wording of any human-readable output. Parse --json, not prose.
  • Anything marked "example profile" in brig agent ls.
  • The Go package github.com/brig-sh/brig/api/policy/v1alpha1, which holds the policy document types and their validation. It is alpha and carries no compatibility promise. A field can be added, renamed or removed in any release. It is public so that another program, such as a Kubernetes operator, can link the types without linking Brig.

Retired spellings #

A retired spelling keeps working. Each time you use it, Brig prints one line on stderr. The line names the replacement and the release that removes the spelling. Migration shows the notice, and lists every retired spelling with its replacement and the release that removed it.

Brig removes a spelling only in a minor release, and at least one release after its first notice. brig run is never removed.

Brig refuses a removed spelling, and each refusal names the replacement:

Removed What Brig does
A command or subcommand A usage error, with exit code 2
A run-line flag Before the ref, a usage error as above. After the ref, the flag is the agent's own.
A profile key The profile fails to load
A setting The run stops

v0.3.0 removed brig shell and the hostCredential: profile key. v0.4.0 removed none. v0.5.0 removed the rest of the retired spellings. Among them are the profile keys forward:, statePaths:, shell: and gui:, and the BRIG_TEMPLATE_DIR setting, which printed no notice at run time.

There are two exceptions:

Spelling Removal Notice at run time
brig exec Names no release. It stays until brig sh can pipe a command's output (issue 335). Its notice will then name a release at least one release ahead. Yes. The notice says it stays.
The flat form of a policy document v0.6.0. v0.5.0 is the first release that prints its notice. From brig policy check. See Policy documents.

Breaking changes #

The notes of each release list its breaking changes first, under "Breaking changes". Changelog carries the notes of every stable release. The list comes from the commits marked as breaking under Conventional Commits, which Contributing describes.

Before you upgrade across a minor release, read that section of the release notes.

For which computers Brig runs on, see Install.

Break reports #

If a new version breaks a script that used only the stable surfaces, that is a bug. Open an issue with the command, the version from brig version, and the output.

For anything security-related, follow the Security policy instead of opening a public issue.

Type a command, a flag or an error message.