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 #
Every brigd response carries the protocol version, v, which is 1 today.
Within one version, brigd can add a field, but it renames or removes none. A change that breaks a client is a new version. brigd refuses a request with 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 exportheader documents. - The wording of any human-readable output. Parse
--json, not prose. - Anything marked "example profile" in
brig agent ls.
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 and its replacement.
Brig removes a spelling only in a minor release, and at least one release after its first notice. brig run is never removed.
v0.4.0 removes the retired spellings that still work today. There are two kinds of exception:
| 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. |
Profile keys forward:, statePaths:, shell: and gui:, and the BRIG_TEMPLATE_DIR setting |
v0.4.0 | None. Migration says so for each. |
Breaking changes #
The notes of each release list its breaking changes first, under "Breaking changes". 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.