Skip to content
bbkt

CLI Reference

The bbkt CLI provides an interactive, terminal-native experience for managing Bitbucket workspaces, repositories, pipelines, issues, and pull requests.

Global flags (available on every command):

  • --profile <name> / -p <name> — credential profile to use (overrides active profile and BBKT_PROFILE)
  • --json — emit raw JSON instead of formatted tables

Inside a Bitbucket git clone, most commands infer workspace and repo from .git/config, so positional [workspace] [repo-slug] args can be omitted.

Authentication & Profiles

Section titled “Authentication & Profiles”

bbkt auth

Section titled “bbkt auth”

Set up credentials. Defaults to an Atlassian API token (Basic auth); use --oauth for the browser flow.

Terminal window
bbkt auth                          # API token, "default" profile
bbkt auth --profile work           # API token, "work" profile
bbkt auth --oauth                  # OAuth 2.0 browser flow

bbkt status

Section titled “bbkt status”

Show the active profile, auth type, token redaction, and scopes.

bbkt logout

Section titled “bbkt logout”

Remove stored credentials.

bbkt profile

Section titled “bbkt profile”

Manage credential profiles for multiple accounts.

Terminal window
bbkt profile                       # list profiles (active is marked)
bbkt profile list                  # same
bbkt profile use <name>            # set active profile
bbkt profile refresh               # refresh cached workspace list per profile
bbkt --profile work prs list       # one-shot override

MCP Server

Section titled “MCP Server”

bbkt mcp

Section titled “bbkt mcp”

Start the MCP server. Stdio by default; pass --port <n> for the HTTP Streamable transport.

Terminal window
bbkt mcp                           # stdio
bbkt mcp --port 8080               # HTTP Streamable on :8080
bbkt mcp --no-auth                 # no credentials (tools return auth-required)

Core Commands

Section titled “Core Commands”

bbkt workspaces

Section titled “bbkt workspaces”
Terminal window
bbkt workspaces list                                # all accessible workspaces
bbkt workspaces get <workspace>                     # specific workspace

bbkt repos

Section titled “bbkt repos”
Terminal window
bbkt repos list [workspace]                         # repos in a workspace
bbkt repos get [workspace] [repo-slug]
bbkt repos create [workspace] [repo-slug] [--description ...] [--private]
bbkt repos delete [workspace] [repo-slug]

bbkt prs

Section titled “bbkt prs”
Terminal window
bbkt prs list [workspace] [repo-slug]               # --state OPEN|MERGED|SUPERSEDED|DECLINED
bbkt prs get [workspace] [repo-slug] <pr-id>
bbkt prs create [workspace] [repo-slug] --title <t> --source <branch> [--destination <branch>]
bbkt prs merge [workspace] [repo-slug] <pr-id> [--strategy merge_commit|squash|fast_forward]
bbkt prs approve [workspace] [repo-slug] <pr-id>
bbkt prs decline [workspace] [repo-slug] <pr-id>

bbkt prs comments

Section titled “bbkt prs comments”
Terminal window
bbkt prs comments list [workspace] [repo-slug] <pr-id>
bbkt prs comments add [workspace] [repo-slug] <pr-id> -m <body> \
    [--file <path> --to <line> | --from <line>] [--parent <comment-id>]
bbkt prs comments resolve [workspace] [repo-slug] <pr-id> <comment-id>

bbkt pipelines

Section titled “bbkt pipelines”
Terminal window
bbkt pipelines list [workspace] [repo-slug]         # --status SUCCESSFUL|FAILED|INPROGRESS
bbkt pipelines get [workspace] [repo-slug] <pipeline-uuid>
bbkt pipelines trigger [workspace] [repo-slug] --ref-name <branch> [--ref-type branch|tag] [--pattern <custom-name>]
bbkt pipelines stop [workspace] [repo-slug] <pipeline-uuid>
bbkt pipelines steps [workspace] [repo-slug] <pipeline-uuid>
bbkt pipelines log [workspace] [repo-slug] <pipeline-uuid> <step-uuid>

bbkt issues

Section titled “bbkt issues”
Terminal window
bbkt issues list [workspace] [repo-slug]            # --kind bug|enhancement|proposal|task
bbkt issues get [workspace] [repo-slug] <issue-id>
bbkt issues create [workspace] [repo-slug] --title <t> [--content <md>] [--kind ...] [--priority ...]
bbkt issues update [workspace] [repo-slug] <issue-id> [--state ...] [--priority ...]

bbkt source

Section titled “bbkt source”
Terminal window
bbkt source read [workspace] [repo-slug] <path> [--ref <ref>]
bbkt source tree [workspace] [repo-slug] [path] [--ref <ref>] [--max-depth <n>]
bbkt source search [workspace] [repo-slug] <query>      # requires code-search-enabled workspace
bbkt source history [workspace] [repo-slug] <path>
bbkt source write [workspace] [repo-slug] <path> --content <text> [-m <msg>] [-b <branch>]
bbkt source delete [workspace] [repo-slug] <path> [-m <msg>] [-b <branch>]