CLI Reference
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
Tip: Run
bb agent-sessions resumefrom 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.
Next steps
-
What's in a session, where it's stored, how resume actually works
-
The slash commands that ship in each pack