> ## Documentation Index > Fetch the complete documentation index at: https://docs.buildbetter.ai/llms.txt > Use this file to discover all available pages before exploring further. # CLI Reference > Every bb command, what it does, and when you'd reach for it. # `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. ```bash theme={null} bb # show top-level help bb -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 ` | 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](/pages/ZeroShot/agent-sessions) page for the full story; here's the command surface. ```bash theme={null} bb agent-sessions resume # interactive picker for the current branch bb agent-sessions resume # resume a specific session bb agent-sessions list # sessions in this repo bb agent-sessions list --branch # filter by branch bb agent-sessions list --author # filter by teammate bb agent-sessions list --since 7d # filter by time window bb agent-sessions search "" # full-text search across sessions bb agent-sessions show # print metadata + summary for one session bb agent-sessions link # attach the current session to a PR bb agent-sessions delete # 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](/pages/ZeroShot/skills) for what each one does. ```bash theme={null} bb skills install # install a pack (spec-workflow, testing, core) bb skills install --all # install every pack bb skills uninstall # 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 ```bash theme={null} 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 ```bash theme={null} 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. ```bash theme={null} bb config init # create .buildbetter/ in the current repo bb config get # read a setting bb config set # 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 | | `/.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: ```bash theme={null} # 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