`bb` — the ZeroShot CLI

Once installed, everything ZeroShot does on your machine runs through a single binary: bb. It’s small, scriptable, and stays out of your way until you call it.

bb                 # show top-level help
bb <command> -h    # show help for a specific command
bb --version       # print the installed version

Day-to-day commands

These are the commands you’ll actually type. The rest are below.

Command	What it does
`bb agent-sessions resume`	Pick a coding session to resume — yours or a teammate’s
`bb agent-sessions list`	Show sessions for the current branch / repo
`bb skills install <pack>`	Add a skill pack to your agent
`bb doctor`	Diagnose install, PATH, and agent integration issues
`bb login`	Sign in to sync sessions across machines

Sessions

The CLI tracks every session you have with a supported coding agent (Claude Code, Codex, Cursor, etc.) and indexes it by repo · branch · commit · author. See the Agent Sessions page for the full story; here’s the command surface.

bb agent-sessions resume                # interactive picker for the current branch
bb agent-sessions resume <session-id>   # resume a specific session
bb agent-sessions list                  # sessions in this repo
bb agent-sessions list --branch <name>  # filter by branch
bb agent-sessions list --author <user>  # filter by teammate
bb agent-sessions list --since 7d       # filter by time window
bb agent-sessions search "<query>"      # full-text search across sessions
bb agent-sessions show <session-id>     # print metadata + summary for one session
bb agent-sessions link <pr-number>      # attach the current session to a PR
bb agent-sessions delete <session-id>   # remove a single session
bb agent-sessions purge --repo .        # remove every session for this repo

Run bb agent-sessions resume from inside any git checkout. The CLI scopes the picker to the repo and branch you’re standing in, so the list is always short.

Skills

Skills are slash commands like /bb-specify and /trust-but-verify that get installed into your coding agent. They’re shipped as packs — see the Skills reference for what each one does.

bb skills install <pack>     # install a pack (spec-workflow, testing, core)
bb skills install --all      # install every pack
bb skills uninstall <pack>   # remove a pack
bb skills list               # show installed packs and individual skills
bb skills update             # pull the latest version of every installed pack
bb skills platforms          # show which agents are detected and where skills go

Account & sync

bb login            # browser-based sign-in to your free BuildBetter workspace
bb logout           # remove cached credentials
bb whoami           # show the signed-in user and workspace
bb sync             # force a sync of local sessions to the cloud
bb sync --status    # show last sync time and pending items

You can use the CLI fully offline — bb login is optional. Without it, sessions stay on disk and only resume on the same machine.

Diagnostics & maintenance

bb doctor           # check install, PATH, agent detection, sync health
bb doctor --fix     # attempt to repair common issues (PATH, shell rc, perms)
bb update           # update the bb binary and every installed skill pack
bb uninstall        # remove ~/.buildbetter/ and the binary

bb doctor is the first thing to run when something feels off. Sample output:

✓ bb 1.2.0 (latest)
✓ ~/.buildbetter/bin in PATH
✓ Signed in as spencer@buildbetter.app
✓ Claude Code  · skills installed at ~/.claude/skills
✓ Codex CLI    · skills installed at ~/.codex/skills
⚠ Cursor       · detected, skills directory missing — run `bb skills install --all`
✓ Last sync 2m ago — 0 pending sessions

Repo configuration

bb stores per-repo settings in .buildbetter/ at the repo root (it’s safe to commit). Use these to opt repos into different defaults — for example, a repo where sessions should never sync to the cloud.

bb config init                  # create .buildbetter/ in the current repo
bb config get <key>             # read a setting
bb config set <key> <value>     # write a setting
bb config list                  # show every setting (with where it comes from)

Common keys:

Key	Effect
`sync.enabled`	`false` keeps all sessions for this repo local-only
`sessions.exclude_branches`	Glob list of branches that should never be indexed (e.g. `secret/*`)
`pr.auto_link`	`false` disables automatic session-to-PR linking

Where things live

Path	What’s there
`~/.buildbetter/bin/bb`	The binary itself
`~/.buildbetter/skills/`	Installed skill packs (synced to your agent’s skills dir)
`~/.buildbetter/sessions/`	Local session cache (offline + pre-sync)
`~/.buildbetter/config.toml`	Global config and credentials
`~/.buildbetter/logs/bb.log`	CLI logs — attach this to bug reports
`<repo>/.buildbetter/`	Per-repo overrides (safe to commit)

Scripting `bb`

Most commands support --json for machine-readable output, which makes bb easy to wire into pre-commit hooks, PR templates, or CI:

# Print the most recent session ID for the current branch as JSON
bb agent-sessions list --branch "$(git branch --show-current)" --since 1d --json \
  | jq -r '.[0].id'

# Fail a pre-commit hook if there's no session attached to this branch
test -n "$(bb agent-sessions list --branch HEAD --json | jq '.[0]')" \
  || { echo "No agent session linked — run bb agent-sessions link"; exit 1; }

Exit codes are stable: 0 success, 1 user error, 2 not signed in, 3 network failure, 4 integrity / corrupted state.

Getting Started

Using the CLI

CLI Reference

`bb` — the ZeroShot CLI

Day-to-day commands

Sessions

Skills

Account & sync

Diagnostics & maintenance

Repo configuration

Where things live

Scripting `bb`

Next steps

Sessions deep dive

Skills

​bb — the ZeroShot CLI

​Day-to-day commands

​Sessions

​Skills

​Account & sync

​Diagnostics & maintenance

​Repo configuration

​Where things live

​Scripting bb

​Next steps

Sessions deep dive

Skills

`bb` — the ZeroShot CLI

Day-to-day commands

Sessions

Skills

Account & sync

Diagnostics & maintenance

Repo configuration

Where things live

Scripting `bb`

Next steps