Repo Commands - Clone, Create & Manage Bitbucket Repositories

Manage Bitbucket repositories.

See Global flags for JSON output, workspace/repository selection, and display options.

bb repo clone

Clone a Bitbucket repository.

bb repo clone <repository> [options]

Arguments

Argument	Description
repository	workspace/repo, a bare repository name, or a full clone URL

For a bare name, the workspace comes from BB_WORKSPACE, then the defaultWorkspace config key. The global -w is not honoured by this command.

Options

Option	Description
-d, --directory <dir>	Directory to clone into
--protocol <protocol>	ssh or https. Defaults to the gitProtocol config key, otherwise ssh

Examples

# Clone using workspace/repo format
bb repo clone myworkspace/myrepo

# Clone into a specific directory
bb repo clone myworkspace/myrepo -d my-local-dir

# Bare name — workspace comes from the environment
BB_WORKSPACE=myworkspace bb repo clone myrepo

# Clone over HTTPS (no SSH key needed)
bb repo clone myworkspace/myrepo --protocol https

# Make HTTPS the default for every clone
bb config set gitProtocol https

# Clone using full URL
bb repo clone [email protected]:myworkspace/myrepo.git

Notes

• For the workspace/repo and bare-name forms the CLI clones over SSH ([email protected]:<workspace>/<repo>.git) unless --protocol https or gitProtocol https picks https://bitbucket.org/<workspace>/<repo>.git. A full URL is cloned as given.
• Over HTTPS, git handles authentication itself (your credential helper or a password prompt); the CLI’s own login is not passed to git.
• git’s own progress and errors are shown as the clone runs, on stderr, so --json output on stdout stays parseable. There is no time limit; press Ctrl+C to stop a clone.
• A path with more than one / fails with Invalid repository format. Use workspace/repo or a full URL.
• --json emits { success, repository, path, cloneUrl }.

---

bb repo create

Create a new repository.

bb repo create <name> [options]

Arguments

Argument	Description
name	Name for the new repository

Options

Option	Description	Default
-d, --description <description>	Repository description
--private	Create a private repository	true
--public	Create a public repository
-p, --project <project>	Project key
--dry-run	Print the write request instead of sending it (details)

Examples

# Create a private repository
bb repo create my-new-repo -w myworkspace

# Create a public repository with description
bb repo create my-new-repo -w myworkspace --public -d "My awesome project"

# Create in a specific project
bb repo create my-new-repo -w myworkspace -p PROJ

Notes

• Visibility is private unless --public is passed. If both --private and --public are given, --public currently wins and no error is raised, unlike bb snippet create and bb project create, which reject the combination.
• --json emits the raw Bitbucket repository object, with no envelope.

---

bb repo list

List repositories in a workspace.

bb repo list [options]

Options

Option	Description	Default
--limit <number>	Maximum number of repositories	25
--all	List all repositories (overrides --limit)

Examples

# List repositories in a workspace
bb repo list -w myworkspace

# List more repositories
bb repo list -w myworkspace --limit 50

# List every repository in the workspace
bb repo list -w myworkspace --all

# List with JSON output for scripting
bb repo list -w myworkspace --json

# Project to specific fields (returns a flat array)
bb repo list -w myworkspace --json full_name,is_private,language

# Filter with built-in --jq — print just public repo names
bb repo list -w myworkspace --json --jq '.repositories[] | select(.is_private == false) | .full_name'

JSON output

The --json envelope is { workspace, count, repositories }, where repositories is the array of repository objects. --json <fields> drops the envelope and returns a flat array.

Notes

• --limit caps how many repositories come back, not the page size. The CLI walks pages (at most 50 per request) until the cap is reached. A value below 1 fails with --limit must be a positive integer.
• Long descriptions are shortened to fit the terminal width (disable with the global --no-truncate); --json always carries the full values.
• When the result is capped by --limit, a hint shows how many were listed; use a higher --limit or --all to see the rest (suppressed with --json).

---

bb repo view

View repository details.

bb repo view [repository] [options]

Arguments

Argument	Description
repository	workspace/repo, or a bare repository name paired with -w. Optional inside a repository directory.

Examples

# View current repository (from within repo directory)
bb repo view

# View specific repository using workspace/repo format
bb repo view myworkspace/myrepo

# View with explicit workspace option
bb repo view myrepo -w myworkspace

# Get repository details as JSON
bb repo view --json

Notes

• Resolution order: the positional argument wins, then the global -w/-r flags, then the git remote of the current directory.
• --json emits the raw Bitbucket repository object, with no envelope.

---

bb repo cat

Print a file’s contents from Bitbucket without cloning the repository.

bb repo cat <path> [options]

Arguments

Argument	Description
path	File path relative to the repository root (leading and trailing / are ignored)

Options

Option	Description	Default
--ref <ref>	Branch, tag, or commit to read from	the repository main branch

Examples

# Print a file from the main branch
bb repo cat README.md

# Read from another branch, tag, or commit
bb repo cat src/index.ts --ref develop
bb repo cat CHANGELOG.md --ref v1.2.0

# Pipe it anywhere; output is the file's exact bytes
bb repo cat package.json | jq .version
bb repo cat assets/logo.png --ref v1.0.0 > logo.png

# Content plus metadata as JSON
bb repo cat package.json --json

JSON output

--json emits { workspace, repoSlug, ref, commit, path, size, encoding, content }. commit is the resolved commit hash. encoding is utf-8 when the file is valid UTF-8 text, otherwise base64 and content holds the base64-encoded bytes.

Notes

• When stdout is piped or redirected the file is written byte-for-byte, with no trailing newline added. When printing to a terminal, control sequences are stripped like all other output.
• A directory path fails with a pointer to bb repo ls. A missing path or ref fails with Path '<path>' not found at ref '<ref>' in <workspace>/<repo>.
• Branch names containing / (such as feature/x) are resolved to their head commit first, because Bitbucket’s source endpoint cannot address them by name.

---

bb repo ls

List a directory’s files and subdirectories without cloning.

bb repo ls [path] [options]

Arguments

Argument	Description
path	Directory path relative to the repository root. Omit to list the root.

Options

Option	Description	Default
--ref <ref>	Branch, tag, or commit to list	the repository main branch
--limit <number>	Maximum number of entries	25
--all	List every entry (overrides --limit)

Examples

# List the repository root
bb repo ls

# List a subdirectory on another branch
bb repo ls src/commands --ref develop

# Every entry, as JSON paths
bb repo ls docs --all --json --jq '.entries[].path'

JSON output

The --json envelope is { workspace, repoSlug, ref, path, count, entries }. Each entry is Bitbucket’s tree entry object: type is commit_file or commit_directory, path is relative to the repository root, and files carry size and attributes.

Notes

• The table shows TYPE (dir or file), SIZE in bytes, and PATH. Directories end in /.
• Listing is not recursive. Pass a directory path to go deeper.
• A file path fails with a pointer to bb repo cat.

---

bb repo delete

Delete a repository.

bb repo delete <repository> [options]

Arguments

Argument	Description
repository	workspace/repo, or a bare repository name when the workspace comes from -w, BB_WORKSPACE or the defaultWorkspace config key

Options

Option	Description
-y, --yes	Skip the confirmation prompt (required when not in an interactive terminal)
--dry-run	Print the write request instead of sending it (details)

Examples

# Delete a repository without being asked to confirm
bb repo delete myworkspace/myrepo --yes

# Delete using explicit workspace option
bb repo delete myrepo -w myworkspace --yes

--json emits { success, workspace, repoSlug }.

Danger

Deletion is permanent. All repository data, including code and pull requests, is destroyed. In an interactive terminal the command asks Continue? (y/N) when --yes is missing. Anywhere else (pipes, CI, --json, --no-input) it exits with This will permanently delete <workspace>/<repo>. followed by Use --yes to confirm.

---

bb repo default-reviewers

See repository default reviewers for options and examples.

bb repo default-reviewers list

bb repo default-reviewers list.

bb repo default-reviewers add

bb repo default-reviewers add.

bb repo default-reviewers remove

bb repo default-reviewers remove.

bb repo downloads

See repository downloads for options and examples.

bb repo downloads list

bb repo downloads list.

bb repo downloads upload

bb repo downloads upload.

bb repo downloads delete

bb repo downloads delete.