Get started

Install & first run.

Briar is a single Python package on PyPI. There is no SaaS account, no API key to provision, and no server to deploy. You install, you authenticate the providers you actually use, you run.

Requirements

Python 3.10 or newer (tested through 3.12). Check with python --version.
A POSIX shell (macOS / Linux / WSL). Native Windows is untested.
Optional: git on PATH if you plan to run agents that clone repos.
Optional: an LLM API key (Anthropic, OpenAI, Google Gemini, or AWS Bedrock credentials). Only needed when running briar plan build/run or briar agent.

Install from PyPI

$ pip install briar-cli

For an isolated environment (recommended for production hosts):

$ python3 -m venv ~/.local/briar-venv
$ ~/.local/briar-venv/bin/pip install -U pip
$ ~/.local/briar-venv/bin/pip install briar-cli
$ ln -s ~/.local/briar-venv/bin/briar ~/.local/bin/briar

Optional extras pull in SDKs only some setups need: openai, gemini, mcp (MCP tools, briar mcp serve, briar chat), vault, gcp, azure, or all.

$ pip install "briar-cli[mcp,openai]"
$ pip install "briar-cli[all]"

From source (contributors)

$ git clone https://github.com/iklobato/briar.git
$ cd briar
$ python3 -m venv .venv
$ .venv/bin/pip install -e ".[dev]"
$ .venv/bin/briar version

Verify the install

$ briar version

Prints the installed CLI version (e.g. briar-cli 1.1.56). If this fails, your shell is not finding the installed entry point — check $PATH.

Then run briar doctor. It checks Python, the project config, the git remote, an LLM key, GITHUB_TOKEN and the store, and tells you what is missing. Inside a repo, briar init --company demo writes a .briar.toml so later commands can drop --company and the repo flags (see Configuration).

Your first run

The shortest useful run is briar extract against a single GitHub repo. It mines public state and writes a markdown knowledge file without needing an LLM.

Generate a GitHub PAT with repo and read:org scope.
Run the auth flow:

$ briar auth login github-pat --company demo

Extract:

$ briar extract --company demo \
    --include pr-archaeology \
    --repo iklobato/briar \
    --max 25

Inspect the result:

$ briar context get knowledge:demo
# or open ./knowledge/knowledge/demo.md

No LLM key yet?

Most of briar extract works without one. You only need an LLM when running the selector (plan build/run) or the engineer agent (agent implement/prfix).

Where Briar puts things on disk

Path	Contents
`~/.config/briar/secrets.env`	Default envfile credential store (overridable with `BRIAR_SECRETS_FILE`; `/etc/briar/secrets.env` wins when it exists).
`~/.config/briar/telemetry.json`	Persisted telemetry tier.
`~/.config/briar/install_id`	Anonymous random install ID used by telemetry.
`./.briar.toml`	Optional project config written by `briar init`.
`./knowledge/`	Knowledge-blob root for the file store (override with `--root`).
`./journal/`	Decision-journal sessions (written by `scaffold` and `plan run`).
`$TMPDIR/briar-agent-*`	Throwaway worktrees the agent clones into. Removed after the run unless `--keep-worktree` is set or the agent run ended with an error.

Upgrade

$ pip install -U briar-cli
$ briar version

Releases follow semver. Read the release notes before bumping a major.

Uninstall

$ pip uninstall briar-cli
$ rm -rf ~/.config/briar

Your knowledge / journal files in the project directory are kept — delete them manually if you don't want them.