bitbucketdc-cli

Command-line interface for Bitbucket Data Center. 51 commands across 11 domains — pull requests, commits, comparisons, files, branches, tags, projects, repositories, code search, users, and access tokens.

Install

npm install -g bitbucketdc-cli

Setup

export BITBUCKET_URL="https://bitbucket.example.com"   # Base URL of your Bitbucket instance
export BITBUCKET_TOKEN="your-personal-access-token"     # HTTP Access Token from Bitbucket

The token commands are the exception: token management uses basic auth, not the PAT.

export BITBUCKET_BASIC_USERNAME="your-username"
export BITBUCKET_BASIC_PASSWORD="your-password"   # or pass --basic-username / --basic-password

Argument conventions

• One positional, and it is the group's subject — the pull request id for pr, the repository slug for repo, the commit hash for commit, the file path for file.
• Scope is a flag — --project <key> and --repo <slug>, mandatory wherever the API needs them.
• Sub-entities are entity-qualified flags — a comment is --comment-id <n>, never a positional.
• Prose is --body, and every prose flag has a --<name>-file <path|-> companion that reads a file or stdin.
• Pagination is --limit (default 25) + --start (a 0-based offset).

Commands

All commands output JSON. Add --pretty to pretty-print.

pr

Every command here takes mandatory --project <key> and --repo <slug>, except pr inbox.

| Command | Description | | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | bitbucketdc pr inbox | Pull requests waiting on you as a reviewer, across every repository | | bitbucketdc pr get <prId> | One pull request — state, refs, reviewers, approval status | | bitbucketdc pr changes <prId> | The files the pull request touches, with their change type | | bitbucketdc pr diff <prId> | The diff. --format text\|json, --path for one file, --context, --whitespace show\|ignore-all, --since/--until for a commit range | | bitbucketdc pr activities <prId> | Comments, approvals, rescopes and merges in order. --types filters | | bitbucketdc pr activity-diff <prId> | What changed since --since <iso> — new comments (including nested replies, which never surface as new activities), new commits, and other events | | bitbucketdc pr create | Opens a pull request from --from <branch> to --to <branch> with --title. Default reviewers are fetched and added; --reviewers overrides, --draft marks it | | bitbucketdc pr update <prId> | Changes --title and/or --description | | bitbucketdc pr review <prId> | Sets your review --status APPROVED\|NEEDS_WORK\|UNAPPROVED | | bitbucketdc pr can-merge <prId> | Whether it can merge, and which vetoes stand in the way | | bitbucketdc pr merge <prId> | Merges it. --strategy <id>, --comment for the merge message, --delete-source-branch | | bitbucketdc pr decline <prId> | Declines it without merging | | bitbucketdc pr delete <prId> | Deletes the pull request outright | | bitbucketdc pr linked-issues <prId> | Jira issues Bitbucket has formally linked to the PR — not regex-parsed from the title |

pr comment

create is one command for all three comment kinds: general by default, file-level with --path, and inline with --path --line --line-type --file-type. Replies pass --parent-id.

| Command | Description | | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | bitbucketdc pr comment create <prId> | Posts a comment from --body/--body-file and returns its id | | bitbucketdc pr comment get <prId> | The comment named by --comment-id, plus its reply subtree. Bitbucket carries no upward link — use pr activities for parent context | | bitbucketdc pr comment update <prId> | Rewrites the comment named by --comment-id | | bitbucketdc pr comment delete <prId> | Deletes the comment named by --comment-id | | bitbucketdc pr comment react <prId> | Adds --emoji thumbsup\|thumbsdown\|heart\|thinking_face\|laughing to --comment-id | | bitbucketdc pr comment unreact <prId> | Removes that reaction |

commit

| Command | Description | | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | bitbucketdc commit list | Commit history on a ref. --until <ref> picks the branch, --since <ref> bounds it, --path scopes to one file, --merges include\|exclude\|only | | bitbucketdc commit get <hash> | Metadata for one commit — author, message, parents | | bitbucketdc commit changes <hash> | The files that commit touched | | bitbucketdc commit diff <hash> | Its diff. --format text\|json, --path, --context, --whitespace | | bitbucketdc commit build-status <hash> | CI build results posted against the hash. Needs no project or repository — the build-status API is keyed by the hash alone |

compare

Both take mandatory --project, --repo, --from <ref> and --to <ref>.

| Command | Description | | ----------------------------- | ------------------------------------------ | | bitbucketdc compare changes | The files that differ between the two refs | | bitbucketdc compare diff | The diff between them, as structured JSON |

file

All three take mandatory --project and --repo.

| Command | Description | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | bitbucketdc file list | Directory contents at --path, on the ref given by --at (defaults to the default branch) | | bitbucketdc file get <path> | Raw file content on stdout, at the ref given by --at | | bitbucketdc file update <path> | Writes the file on --branch and returns the new commit. Content from --body/--body-file, message from --comment; --source-branch creates the branch |

branch

| Command | Description | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | bitbucketdc branch list | Branches in --project/--repo. --filter matches by name, --order-by ALPHABETICAL\|MODIFICATION, --details adds each branch's latest commit and ahead/behind counts |

tag

| Command | Description | | ---------------------- | ----------------------------------------------------------------------------------------- | | bitbucketdc tag list | Tags in --project/--repo, with --filter and --order-by ALPHABETICAL\|MODIFICATION |

project

| Command | Description | | ------------------------------- | ----------------------------------------------------------------------- | | bitbucketdc project list | Projects you can see. --name filters, --permission narrows by grant | | bitbucketdc project get <key> | One project — id, key, name, description, visibility, browse url |

repo

Everything but list takes a mandatory --project <key>.

| Command | Description | | ---------------------------------------- | -------------------------------------------------------------------------------------------------- | | bitbucketdc repo list | Repositories, filtered by --project, --project-name, --name, --visibility and --archived | | bitbucketdc repo get <slug> | Full repository metadata, including defaultBranch, project and links | | bitbucketdc repo default-branch <slug> | Just the configured default branch (read-only) | | bitbucketdc repo create | Creates a repository --name in --project, with --default-branch, --public, --no-forkable | | bitbucketdc repo update <slug> | Changes only the settings you pass — name, description, default branch, visibility, forkability | | bitbucketdc repo delete <slug> | Deletes it (Bitbucket removes it asynchronously) | | bitbucketdc repo clone <slug> | Clones it to --path using token authentication |

repo attachment

| Command | Description | | ----------------------------------------------------- | --------------------------------------------------------------- | | bitbucketdc repo attachment upload | Uploads the files in --files and returns their attachment ids | | bitbucketdc repo attachment download <attachmentId> | Writes one attachment to --output |

search

| Command | Description | | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | bitbucketdc search code <query> | Full-text code search across every repository the token can read. Each hit collapses to {project, repo, path, url, hunks}. --project, --repo, --lang, --ext and --path fold into Bitbucket's native search modifiers |

--repo requires --project. --lang is validated against Bitbucket's language set — TypeScript has no lang: token, so use --ext ts. A --project/--repo that does not resolve is a usage error, not an empty result.

user

| Command | Description | | --------------------------------- | -------------------------------------------------------- | | bitbucketdc user me | The profile behind BITBUCKET_TOKEN | | bitbucketdc user get <username> | One user by exact username | | bitbucketdc user search [query] | Users matching part of a username, display name or email |

token

These four authenticate with basic auth (see Setup). --user <slug> manages another user's tokens if you have permission.

| Command | Description | | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | | bitbucketdc token list | Token names, ids, permissions and expiry — never the secrets | | bitbucketdc token create | Mints a token with --name, --permissions <list> and --expiry-days <n>. The secret is returned exactly once | | bitbucketdc token modify <tokenId> | Changes a token's --name or --permissions | | bitbucketdc token revoke <tokenId> | Revokes one token |

Pagination

List commands take --limit <n> (default 25) and --start <offset>. Responses carry nextPage — pass it back as --start for the next page; when it is null, there are no more results. pr changes and pr activity-diff are single-page and take --limit only.

Examples

# Check your review inbox
bitbucketdc pr inbox

# Read a pull request and its diff
bitbucketdc pr get 42 --project PROJ --repo my-repo
bitbucketdc pr diff 42 --project PROJ --repo my-repo --context 5

# Diff a single file within a PR, structured
bitbucketdc pr diff 42 --project PROJ --repo my-repo --path src/index.ts --format json

# What has happened on the PR since I last looked
bitbucketdc pr activity-diff 42 --project PROJ --repo my-repo --since 2026-06-01T09:00:00Z

# Approve, or ask for changes
bitbucketdc pr review 42 --project PROJ --repo my-repo --status APPROVED
bitbucketdc pr review 42 --project PROJ --repo my-repo --status NEEDS_WORK

# Comment: general, on a file, and inline on a line
bitbucketdc pr comment create 42 --project PROJ --repo my-repo --body "Ship it"
bitbucketdc pr comment create 42 --project PROJ --repo my-repo --path src/index.ts --body "This file needs a test"
bitbucketdc pr comment create 42 --project PROJ --repo my-repo --path src/index.ts --line 15 --line-type ADDED --file-type TO --body "Rename this variable"

# Reply to a comment, then react to it
bitbucketdc pr comment create 42 --project PROJ --repo my-repo --parent-id 9 --body "Agreed"
bitbucketdc pr comment react 42 --project PROJ --repo my-repo --comment-id 9 --emoji thumbsup

# A long description from a file, or from stdin
bitbucketdc pr create --project PROJ --repo my-repo --from feature-x --to main --title "Add feature X" --description-file ./pr.md
cat pr.md | bitbucketdc pr create --project PROJ --repo my-repo --from feature-x --to main --title "Add feature X" --description-file -

# Merge with a strategy
bitbucketdc pr merge 42 --project PROJ --repo my-repo --strategy squash

# Browse and read files without cloning
bitbucketdc file list --project PROJ --repo my-repo --path src/ --at develop
bitbucketdc file get src/config.ts --project PROJ --repo my-repo --at main

# Repository metadata
bitbucketdc repo list --project PROJ --name tool
bitbucketdc repo get my-repo --project PROJ
bitbucketdc repo default-branch my-repo --project PROJ

# Branches, tags, commits
bitbucketdc branch list --project PROJ --repo my-repo --filter release/
bitbucketdc tag list --project PROJ --repo my-repo --order-by MODIFICATION
bitbucketdc commit list --project PROJ --repo my-repo --until main --limit 10
bitbucketdc commit build-status a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0

# Compare two refs
bitbucketdc compare changes --project PROJ --repo my-repo --from release/1.2 --to main

# Search code
bitbucketdc search code "getClient" --project PROJ --ext ts

Breaking changes in this release

• file show <path> is now file get <path> — get is the read verb for every noun in the suite. Same flags, same output, and there is no show alias.
• New: project get <key>, so one project can be read without paging project list.
• repo list --project-key renamed to --project (matching every other command).
• file list / file get — the --branch alias has been removed. Use --at <ref>.
• pr file-diff has been removed. Use pr diff <prId> --path <path> --format json.

Renamed in 2.0.0

The argument surface was unified across the whole CLI suite. There are no deprecation shims. Three patterns cover almost all of it:

A — the pull request is the subject of the pr group.

| Before | Now | | ----------------------------------------------------------- | --------------------------------------- | | pr get\|changes\|diff\|activities\|activity-diff --id <n> | pr <verb> <prId> --project P --repo R | | pr review\|update\|merge\|decline\|delete --id <n> | pr <verb> <prId> --project P --repo R | | pr can-merge\|linked-issues --id <n> | pr <verb> <prId> --project P --repo R |

B — subject-as-positional for the other repo-scoped groups.

| Before | Now | | --------------------------------------------------------------- | -------------------------------------------------------------- | | repo get\|update\|delete\|default-branch\|clone --repo <slug> | repo <verb> <slug> --project P | | repo attachment download --id <attachmentId> | repo attachment download <attachmentId> --project P --repo R | | commit get\|changes\|diff --commit <hash> | commit <verb> <hash> --project P --repo R | | commit build-status --hash <sha> | commit build-status <hash> | | file edit --path <p> --content <c> --message <m> | file update <p> --body <c> --comment <m> | | token modify\|revoke --id <tokenId> | token modify\|revoke <tokenId> |

C — the flat comment and reaction verbs became the pr comment sub-group.

| Before | Now | | ------------------------------------------------- | -------------------------------------------------------------------- | | pr comment --id <n> --body … | pr comment create <prId> --body … | | pr file-comment / pr line-comment | pr comment create <prId> --path … [--line --line-type --file-type] | | pr get-comment | pr comment get <prId> --comment-id <c> | | pr edit-comment | pr comment update <prId> --comment-id <c> | | pr delete-comment | pr comment delete <prId> --comment-id <c> | | pr reaction-add\|reaction-remove --emoticon <e> | pr comment react\|unreact <prId> --comment-id <c> --emoji <e> |

Plus pr comment create --parent <n> → --parent-id <n>, and pr merge --message <text> → --comment <text>.