The CLI

bscope works with repositories, changes and code graphs from a terminal or a script. Every command prints readable text, or the API's own JSON with --json.

cd cli && go build -o bscope ./cmd/bscope

Signing in#

bscope auth login                       # opens the browser; approve, and this computer gets a token
bscope auth login --with-token < tok    # no browser: paste a token
bscope auth status
bscope auth setup-git                   # plain git push/clone use your bscope token
bscope auth logout                      # forgets the token here (revoke it with token revoke)

CI skips login: --token bsc_pat_…, or BRANCHSCOPE_TOKEN and BRANCHSCOPE_HOST in the environment.

Agents on this machine#

An agent such as Claude Code signs in once, under its own name, and the CLI keeps its credentials fresh (they last an hour):

bscope agent login --name claude-code       # opens the browser; you approve, and choose its repositories
bscope agent setup-git --name claude-code   # in its clone (or --global): git pushes as the agent
bscope agent token --name claude-code       # a fresh access token, for MCP clients and scripts
bscope agent list
bscope agent logout --name claude-code      # revokes it, and forgets it here

Pushes, changes and comments made with these credentials are marked as the agent's, acting for you. See Agents.

Choosing the host: --host, then $BRANCHSCOPE_HOST, then the last login, then http://127.0.0.1:3300. The CLI learns the API and git URLs from <host>/.well-known/branchscope.

Choosing the repository: inside a clone, commands use its origin; -R owner/name overrides.

Commands#

Command	What it does
init [[owner/]name] [-C|--directory dir] [--remote r] [--description d] [--public] [--readme] [--gitignore t] [--license id] [--push]	Make this folder (or --directory) a Branchscope repository: creates it (named after the folder), adds it as origin (or --remote) and lets git sign in for it; a new project can start with a README, .gitignore and license, and one with commits can --push
repo list / view / create [owner/]name [--public] / clone owner/name	Repositories
repo import <url> [--owner o] [--name n] [--public] [--token-stdin] [--wait [--timeout 35m]]	Import from GitHub, GitLab or a git URL, once
change list [--state open|merged|closed|all]	Changes
change view <n> / diff <n>	A change, and its textual diff
change create -t <title> [-b <body>] [--head b] [--base b]	Open a change from the branch you're on
change merge <n> [--squash|--rebase] [-m message]	Merge with the repository's default method, or squash or rebase; the push guard decides
change close / reopen <n>	Close, reopen
commit view <sha> [--no-diff]	A commit: its message, author, committer, parents and diff
log [--ref r] [-- path]	Commits, newest first; with a path, a file's history (following renames) or a folder's
blame <path> [--ref r]	Which commit last changed each line of a file
change review <n> [--wait [--timeout 15m]] [--fail-on deny|review] [--against e]	The graph review: its branchscope/review check, findings, renames, other repositories (--against an environment: as deployed there) and every diagram as text
change conflicts <n> [--wait [--timeout 15m]]	The conflict map: what both sides did to the elements both touched, conflicting files and semantic conflicts
graph status / build / download [-o|--output file] [--ref r]	A branch's graph
graph view architecture|data-flow [--project id]	Views as text
comment list <n> / add <n> --body b [--reply-to id] / status <n> <status> <text>	A change's discussion; status is for agents (working, pushed, blocked, done)
check list <n> [--fail-on-required]	A change's checks, and whether the required ones passed
run list [--change n] [--trigger t] / view <id> / log <id> [--job j] [--follow]	Workflow runs, and a job's log, followed live with --follow
run artifacts <id|url> [--download name] [--job j] [--output dir]	A run's artifacts: name, job, size and expiry; --download saves one to --output (the current folder by default) as <name>.tar.gz, and --job picks the job when several kept one of that name
run start <workflow> [--ref b] / cancel <id> / rerun <id> / approve <id>	Run a workflow by hand (it needs on: manual), cancel a run, run it again; give a run its withheld secrets, so its jobs that name them run (repository admins)
release list / view <tag>	Releases, newest first (drafts too, with write access); one release, its notes and its change map's state
release create <tag> [--target r] [-t title] [-n notes | -F file | --generate-notes] [--previous tag | --no-previous] [--draft] [--prerelease]	Publish a release, making a new tag at --target through the push guard; agents must pass --draft, and a person publishes it
release publish <tag> / edit <tag> [-t title] [-n notes | -F file] [--prerelease[=false]] / delete <tag>	Publish a draft, making its tag through the push guard if it's new (people only); change a release's title, notes or pre-release; delete a release, leaving its tag
ruleset list [--kind branch|tag]	A repository's rulesets, oldest first (repository admins); read-only: change them in the web app or the API
deploy list [--environment e] [--limit n] / record <environment> --ref r [--status s] [--url u] [-m|--description text] / status <id> <status> [--url u] [-m|--description text]	List a repository's deployments, newest first; record one made outside Branchscope's actions, and set its status
deploy approve <id> / reject <id> [-m comment], with run/<id> for a run's deployments (--environment e)	Approve or reject a deployment waiting for your review, as one of its environment's reviewers
runner list --org o	An organization's runners
task list [--open] / create --agent a (--change n | --base b) <instructions> / cancel <id>	Tasks for agent apps
agent login / setup-git / token / list / logout --name a	Agents signed in on this machine
token list / create / revoke <id>	Personal tokens; create is approved in the browser
ssh-key list / add [file] / remove <id>	SSH keys; add is approved in the browser
webhook list / create --url u [--event e] / delete <id>	Webhooks of a repository, or an organization's with --org o; create prints the secret once
webhook ping <id> / deliveries <id> / redeliver <id> <delivery>	Test a webhook, see its deliveries, send one again
secret list / set NAME [--kind k] < value / delete NAME	Secrets for runs of a repository, an environment's with --env e, or an organization's with --org o (--repos limits one to some repositories); the value is read from standard input
integration list / add --service s [--url -] [--events e] [--channel c] / remove <id> / test <id>	Integrations of a repository, or an organization's with --org o: Slack, Discord, Teams or Mattermost with --url - (the webhook URL read from standard input), or Sentry with --sentry-org o --sentry-projects p [--sentry-url u] and its token on standard input; only their host and last 4 characters are shown
ai-key list / set <app> <provider> [--cap €] < key / remove <app> <provider>	AI provider keys for installed apps, a repository's or an organization's with --org o; the key is read from standard input, and --cap alone (euros, or none) changes only the monthly cap
linear status --org o	An organization's Linear connection: how it's connected, events from Linear, its workspace, automations and each team's states (read-only)
mirror list / add URL [--token id] [--refs p] / sync ID / remove ID	Mirrors of a repository: add with an SSH URL prints the deploy key to add on the other host; an https:// URL takes --token, the id of one of your external tokens
admin guard status / deny-all on|off [--message m]	The push guard (site admins)

--timeout is how long --wait waits before giving up.

Options for token create and ssh-key add:

• --read-only
• --repo owner/name (repeatable)
• --expires-in-days <n>

Exit codes#

Code	Meaning
0	success
1	an error (the message is on stderr)
2	bad usage: unknown command or flag, wrong arguments
3	change review --fail-on … found violations of that effect; check list --fail-on-required: a required check hasn't passed; run log --follow: the job didn't pass
4	not signed in, or not allowed

Examples#

# Gate a CI job on the review of the change for this branch
bscope change review "$CHANGE" --wait --fail-on deny

# What does main look like?
bscope graph view architecture
bscope graph view data-flow --json | jq '.diagrams[0].summary'

# A read-only token for one repository, for 30 days
bscope token create --name "docs bot" --read-only --repo acme/web --expires-in-days 30

# Hand the agent app "fixer" a task on change 7
bscope task create --agent fixer --change 7 "Address the review findings"