Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,15 @@ follow [semver][semver], with the caveat that everything below 1.0 may break.
[kac]: https://keepachangelog.com/en/1.1.0/
[semver]: https://semver.org/spec/v2.0.0.html

## [Unreleased]

### Added

- `pr create` with explicit title/base, optional head, draft, body-file/stdin,
JSON output and dry-run; `pr diffstat` reuses safe API pagination.
- Draft labels in PR lists and details; exact `pipeline list --custom` filtering
and visible selector names; an API hint on unknown commands.

## [0.2.0] - 2026-09-05

Everything a repository needs before strangers can read it, plus the onboarding
Expand Down
3 changes: 3 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,9 @@ One bash script. No build step, no runtime, no daemon.

```bash
bb-cli pr # open pull requests
bb-cli pr create --title "Change" --base main --body-file body.md --draft
bb-cli pr diffstat 42 # files and line counts
bb-cli pipeline list --custom "Unit specs" # exact custom selector
bb-cli pipeline 1234 failures # why did the build fail
npm test && bb-cli signoff # local CI: publish a green check
bb-cli api repositories/:repo -i # anything else
Expand Down
113 changes: 104 additions & 9 deletions bin/bb-cli
Original file line number Diff line number Diff line change
Expand Up @@ -638,7 +638,7 @@ print_pipeline_rows() {
else "\($s)s"
end;
def short_commit: (.target.commit.hash // "N/A") | if length > 12 then .[0:12] else . end;
def pipeline_type: (.target.selector.type // .target.type // "N/A");
def pipeline_type: (.target.selector.type // .target.type // "N/A") + (if .target.selector.pattern then " / " + .target.selector.pattern else "" end);
def trigger_type: (.trigger.type // .trigger.name // "N/A");
.values[] |
" \u001b[1;33m#\(.build_number)\u001b[0m \(status) • \(duration)",
Expand Down Expand Up @@ -989,7 +989,7 @@ cmd_pipeline() {

case "$action" in
list)
cmd_pipeline_list "$limit" "$branch" "$status" "$author" "$json_output"
cmd_pipeline_list "$limit" "$branch" "$status" "$author" "$json_output" "$custom"
;;
show)
cmd_pipeline_show "$pipeline_ref" "$json_output"
Expand Down Expand Up @@ -1024,10 +1024,11 @@ cmd_pipeline_list() {
local status="$3"
local author="$4"
local json_output="$5"
local custom="${6:-}"
local fetch_limit="$limit"
local params

if [[ -n "$branch" || -n "$status" || -n "$author" ]]; then
if [[ -n "$branch" || -n "$status" || -n "$author" || -n "$custom" ]]; then
fetch_limit=100
fi

Expand All @@ -1045,6 +1046,7 @@ cmd_pipeline_list() {
--arg branch "$branch" \
--arg status_filter "$status" \
--arg author "$author" \
--arg custom "$custom" \
--argjson limit "$limit" '
def normalized_status:
(.state.result.name // .state.name // .state.stage.name // "UNKNOWN")
Expand All @@ -1070,6 +1072,7 @@ cmd_pipeline_list() {
.values |= [
.[] |
select(branch_matches($branch)) |
select(($custom == "") or (.target.selector.type == "custom" and .target.selector.pattern == $custom)) |
select(($status_filter == "") or (normalized_status | contains($status_filter | ascii_downcase))) |
select(($author == "") or (author_text | contains($author | ascii_downcase)))
][: $limit]
Expand Down Expand Up @@ -1537,7 +1540,7 @@ Options:
-s, --status Filter list by pipeline status
-a, --author Filter list by creator/display name
-l, --limit Max pipelines in list (default: 20)
-c, --custom Custom pipeline name for trigger (e.g. "Unit specs")
-c, --custom Custom pipeline name for trigger or list filter (e.g. "Unit specs")
--log Show raw log for a step
--exit-status watch: exit non-zero when the pipeline fails (gh-style)
-j, --json Output raw JSON
Expand Down Expand Up @@ -1582,6 +1585,11 @@ cmd_pr() {
# Parse arguments
while [[ $# -gt 0 ]]; do
case "$1" in
create)
shift
cmd_pr_create "$@"
return $?
;;
view)
shift
if [[ $# -gt 0 && "$1" =~ ^[0-9]+$ ]]; then
Expand All @@ -1590,7 +1598,7 @@ cmd_pr() {
shift
fi
;;
edit | ready | comment)
edit | ready | comment | diffstat)
# gh pr edit|ready|comment. These own the rest of the line.
local verb="$1"
shift
Expand All @@ -1603,6 +1611,7 @@ cmd_pr() {
get_repo_info
check_credentials
case "$verb" in
diffstat) cmd_pr_diffstat "$pr_id" "$@" ;;
edit) cmd_pr_edit "$pr_id" "$@" ;;
ready) cmd_pr_ready "$pr_id" "$@" ;;
comment) cmd_pr_comment "$pr_id" "$@" ;;
Expand Down Expand Up @@ -1664,6 +1673,9 @@ cmd_pr() {
elif [[ "$1" != -* ]]; then
# String with non-numeric chars = branch filter
branch="$1"
else
echo "Unknown option: $1. For other API operations, run 'bb-cli api --help'." >&2
return 1
fi
shift
;;
Expand Down Expand Up @@ -1740,7 +1752,7 @@ cmd_pr() {

echo "$response" | jq -r '
.values[] |
" \u001b[1;33m#\(.id)\u001b[0m \(.title)",
" \u001b[1;33m#\(.id)\u001b[0m \(.title)\(if .draft then " [DRAFT]" else "" end)",
" \u001b[0;36m\(.source.branch.name)\u001b[0m → \(.destination.branch.name)",
" by \(.author.display_name) • \(.updated_on | split("T")[0])",
" \(.links.html.href)",
Expand Down Expand Up @@ -1809,6 +1821,11 @@ cmd_pr_show() {
updated_on=$(echo "$pr_response" | jq -r '.updated_on | split("T")[0]')
url=$(echo "$pr_response" | jq -r '.links.html.href')

local draft_label=""
if [[ "$(echo "$pr_response" | jq -r '.draft // false')" == true ]]; then
draft_label=" (DRAFT)"
fi

# Comments and activity are independent of each other, so they go out
# together rather than one after the other. On a normal connection that is
# the difference between roughly 600ms and roughly 300ms of waiting.
Expand Down Expand Up @@ -1845,7 +1862,7 @@ cmd_pr_show() {
[[ "$state" == "MERGED" ]] && state_color="${CYAN}"
[[ "$state" == "DECLINED" ]] && state_color="${RED}"

echo -e " State: ${state_color}${state}${NC}"
echo -e " State: ${state_color}${state}${draft_label}${NC}"
echo -e " Author: ${author}"
echo -e " Branch: ${CYAN}${source_branch}${NC} → ${dest_branch}"
echo -e " Created: ${created_on}"
Expand Down Expand Up @@ -2005,6 +2022,81 @@ bb_read_body() {
return 0
}

cmd_pr_create() {
local title="" body="" body_file="" base="" head="" draft=false json_output=false dry_run=false
while [[ $# -gt 0 ]]; do
case "$1" in
--title|--body|--body-file|--base|--head)
[[ $# -ge 2 ]] || { echo "Missing value for $1" >&2; return 1; }
case "$1" in
--title) title="$2" ;; --body) body="$2" ;; --body-file) body_file="$2" ;;
--base) base="$2" ;; --head) head="$2" ;;
esac
shift 2 ;;
--title=*) title="${1#*=}"; shift ;;
--body=*) body="${1#*=}"; shift ;;
--body-file=*) body_file="${1#*=}"; shift ;;
--base=*) base="${1#*=}"; shift ;;
--head=*) head="${1#*=}"; shift ;;
--draft) draft=true; shift ;;
--json|-j) json_output=true; shift ;;
--dry-run) dry_run=true; shift ;;
--help|-h) cmd_pr_help; return 0 ;;
*) echo "Unexpected argument: $1. For other API operations, run 'bb-cli api --help'." >&2; return 1 ;;
esac
done
[[ -n "$title" && -n "$base" ]] || { echo 'pr create requires --title and --base' >&2; return 1; }
if [[ -z "$head" ]]; then
head="$(git symbolic-ref --quiet --short HEAD 2>/dev/null)" || {
echo 'Detached or missing checkout: pass --head explicitly' >&2; return 1;
}
fi
bb_read_body "$body" "$body_file" || return 1
get_repo_info
local payload
payload="$(jq -nc --arg title "$title" --arg body "$BB_BODY_TEXT" --arg base "$base" --arg head "$head" --argjson draft "$draft" \
'{title:$title,description:$body,source:{branch:{name:$head}},destination:{branch:{name:$base}},draft:$draft}')"
if [[ "$dry_run" == true ]]; then
echo "POST https://api.bitbucket.org/2.0/repositories/${WORKSPACE}/${REPO}/pullrequests"
printf '%s' "$payload" | jq .
return 0
fi
check_credentials
local rc=0
api_request POST "https://api.bitbucket.org/2.0/repositories/${WORKSPACE}/${REPO}/pullrequests" \
-H 'Content-Type: application/json' --data-binary "$payload" || rc=$?
if [[ $rc -ne 0 ]] || api_status_is_error; then
api_report_error 'creating pull request'
api_cleanup
return 1
fi
if [[ "$json_output" == true ]]; then
cat "$API_BODY_FILE" | jq .
else
jq -r '.links.html.href // ("Created PR #" + (.id|tostring))' "$API_BODY_FILE"
fi
api_cleanup
}

cmd_pr_diffstat() {
local pr_id="$1" json_output=false response
shift
while [[ $# -gt 0 ]]; do
case "$1" in
--json|-j) json_output=true; shift ;;
--help|-h) cmd_pr_help; return 0 ;;
*) echo "Unexpected argument: $1. For other API operations, run 'bb-cli api --help'." >&2; return 1 ;;
esac
done
# Reuse the authenticated redirect and safe pagination path.
response="$(cmd_api "repositories/${WORKSPACE}/${REPO}/pullrequests/${pr_id}/diffstat" --paginate)" || return 1
if [[ "$json_output" == true ]]; then
printf '%s\n' "$response"
else
printf '%s\n' "$response" | jq -r '.values[] | "\(.status)\t+\(.lines_added // 0)\t-\(.lines_removed // 0)\t\(.new.path // .old.path)"'
fi
}

cmd_pr_edit() {
local pr_id="$1"
shift
Expand Down Expand Up @@ -2225,6 +2317,9 @@ Usage: bb-cli pr [<number>] [options]
Commands (mirroring gh):
pr [list] List pull requests
pr view <n> / pr <n> Show one, with its description
pr create --title T --base BRANCH [--head BRANCH] [--body-file F] [--draft]
--head defaults to the current branch; --dry-run writes nothing
pr diffstat <n> [--json] File changes, across all returned pages
pr checks <n> Build statuses on its head commit
pr edit <n> [--title T] [--body-file F]
pr ready <n> [--undo] Draft -> ready for review, or back
Expand Down Expand Up @@ -3903,7 +3998,7 @@ bb-cli ${BB_CLI_VERSION} - Bitbucket CLI
Usage: bb-cli <command> [options]

Core commands:
pr List, show, edit, comment on and check pull requests
pr Create, list, show, edit, diffstat, comment on and check pull requests
pipeline List/show pipelines, steps, logs, failures; trigger, rerun,
watch, cancel (aliased as 'run', gh's noun)
branch List branches
Expand Down Expand Up @@ -4088,7 +4183,7 @@ main() {
;;
*)
echo -e "${RED}Unknown command:${NC} $command" >&2
echo "Run 'bb-cli help' for usage." >&2
echo "Run 'bb-cli help' for usage; 'bb-cli api --help' covers other API operations." >&2
exit 1
;;
esac
Expand Down
12 changes: 12 additions & 0 deletions man/bb-cli.1
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,18 @@ includes comments. Subcommands mirror
.BR "ready <n>" ,
.BR "comment <n>" .
.TP
.B pr create --title T --base BRANCH [--head BRANCH] [--body-file FILE] [--draft]
Create a pull request. The head defaults to the current branch; detached checkouts
require an explicit head. A body-file of - reads stdin. --dry-run prints the
request without sending it; --json returns the response as JSON.
.TP
.B pr diffstat NUMBER [--json]
Read file changes and line counts across returned pages. Removed files use their
old path. Draft state is displayed by both pr list and pr view.
.TP
.B pipeline list --custom NAME
Filter by exact custom selector name. The list also displays selector names.
.TP
.B pr edit \fIn\fR [\fB\-\-title\fI t\fR] [\fB\-\-body\-file\fI f\fR]
Change a pull request's title, description, or both. The current values are read
first and both fields are sent, so changing one cannot blank the other. Use
Expand Down
10 changes: 10 additions & 0 deletions skills/bb-cli/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,16 @@ description: "Use bb-cli for anything on Bitbucket Cloud: pull requests, pipelin
`bb-cli` is to Bitbucket Cloud what `gh` is to GitHub. If a repository's remote
is `bitbucket.org`, this is the tool. `gh` will not work on it.

## Pull requests and pipeline selection

Use `bb-cli pr create --title T --base BRANCH --body-file FILE [--head BRANCH] [--draft]`.
The head defaults to the current branch; detached checkouts require `--head`.
`--body-file -` reads stdin, and `--dry-run` prints the request without sending it.
Use `pr diffstat NUMBER [--json]` for file changes across pages, and `pr edit NUMBER`
for title/description updates. Draft state appears in list and detail output.
`pipeline list --custom NAME` filters by the exact custom selector name; list rows
also display the selector so different pipelines are not compared accidentally.

## Before anything else

```bash
Expand Down
69 changes: 69 additions & 0 deletions tests/porcelain_test.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
#!/usr/bin/env bash
set -u
. "$(dirname "${BASH_SOURCE[0]}")/lib/fake_curl.sh"
harness_init
mkdir "$TMP/checkout"
git -C "$TMP/checkout" init -q -b feature
git -C "$TMP/checkout" remote add origin git@bitbucket.org:example/project.git
cd "$TMP/checkout"
cat > "$CURL_BODY" <<'JSON'
{"id":42,"title":"Example","state":"OPEN","draft":true,"description":"Body","author":{"display_name":"Author"},"source":{"branch":{"name":"feature"}},"destination":{"branch":{"name":"main"}},"created_on":"2026-01-01T00:00:00Z","updated_on":"2026-01-01T00:00:00Z","links":{"html":{"href":"https://bitbucket.org/example/project/pull-requests/42"}},"values":[],"participants":[]}
JSON
printf 'First line with "quotes" \nSecond line\n' > "$TMP/body.md"
run_bb pr create --title 'New "title"' --base main --body-file "$TMP/body.md" --draft
assert_eq 0 "$BB_RC" 'create succeeds'
assert_contains '-X POST' "$CURL_CALLS" 'create sends POST'
assert_contains '/repositories/example/project/pullrequests' "$CURL_CALLS" 'create targets selected repository'
assert_eq true "$(printf '%s' "$CURL_BODIES" | jq -r .draft)" 'draft is a boolean'
assert_eq feature "$(printf '%s' "$CURL_BODIES" | jq -r .source.branch.name)" 'head defaults to current branch'
assert_eq main "$(printf '%s' "$CURL_BODIES" | jq -r .destination.branch.name)" 'base is explicit'
assert_eq 'New "title"' "$(printf '%s' "$CURL_BODIES" | jq -r .title)" 'title escaping survives JSON'
assert_eq "$(cat "$TMP/body.md")" "$(printf '%s' "$CURL_BODIES" | jq -r .description)" 'multiline description and spaces survive JSON'
run_bb pr create --title Test --base main --head another --body-file - <<< 'stdin body'
assert_eq another "$(printf '%s' "$CURL_BODIES" | jq -r .source.branch.name)" 'explicit head used'
assert_eq 'stdin body' "$(printf '%s' "$CURL_BODIES" | jq -r .description)" 'stdin body supported'
assert_eq false "$(printf '%s' "$CURL_BODIES" | jq -r .draft)" 'default is ready'
run_bb pr create --title Test
assert_eq 1 "$BB_RC" 'missing base refused'
assert_eq '' "$CURL_CALLS" 'missing base sends nothing'
run_bb pr create --title Test --base main --body-file "$TMP/no-file"
assert_eq 1 "$BB_RC" 'unreadable body refused'
assert_eq '' "$CURL_CALLS" 'unreadable body sends nothing'
run_bb pr create --title Test --base
assert_eq 1 "$BB_RC" 'missing flag value refused'
run_bb pr create --title Test --base main --dry-run
assert_eq 0 "$BB_RC" 'dry run succeeds'
assert_eq '' "$CURL_CALLS" 'dry run writes nothing'
CURL_STATUS=403
run_bb pr create --title Test --base main
assert_eq 1 "$BB_RC" 'create HTTP denial propagates'
CURL_STATUS=200
run_bb pr 42
assert_contains DRAFT "$BB_OUT" 'draft visible in detail'
jq '{values:[.]}' "$CURL_BODY" > "$TMP/list.json"
cp "$TMP/list.json" "$CURL_BODY"
run_bb pr list
assert_contains '[DRAFT]' "$BB_OUT" 'draft visible in list'
cat > "$CURL_BODY" <<'JSON'
{"values":[{"status":"removed","old":{"path":"old.txt"},"new":null,"lines_added":0,"lines_removed":7},{"status":"added","old":null,"new":{"path":"new.txt"},"lines_added":4,"lines_removed":0}]}
JSON
run_bb pr diffstat 42
assert_eq 0 "$BB_RC" 'diffstat succeeds'
assert_contains '/pullrequests/42/diffstat' "$CURL_CALLS" 'diffstat uses correct endpoint'
assert_contains 'old.txt' "$BB_OUT" 'removed path is visible'
assert_contains 'new.txt' "$BB_OUT" 'new path is visible'
assert_not_contains '-X POST' "$CURL_CALLS" 'diffstat is read only'
run_bb pr diffstat 42 --json
assert_eq 2 "$(printf '%s' "$BB_OUT" | jq '.values | length')" 'diffstat JSON keeps values'
cat > "$CURL_BODY" <<'JSON'
{"values":[{"build_number":1,"target":{"ref_name":"main","selector":{"type":"custom","pattern":"Unit specs"}}},{"build_number":2,"target":{"ref_name":"main","selector":{"type":"custom","pattern":"Deploy"}}},{"build_number":3,"target":{"ref_name":"main","selector":{"type":"branches","pattern":"Unit specs"}}}]}
JSON
run_bb pipeline list --custom 'Unit specs' --json
assert_eq 0 "$BB_RC" 'custom list succeeds'
assert_eq '[1]' "$(printf '%s' "$BB_OUT" | jq -c '[.values[].build_number]')" 'custom filter requires type and exact selector name'
run_bb pipeline list --custom 'Unit specs'
assert_contains 'custom / Unit specs' "$BB_OUT" 'selector name appears in list'
run_bb frobnicate
assert_eq 1 "$BB_RC" 'unknown command fails'
assert_contains 'bb-cli api --help' "$BB_OUT" 'unknown command advertises API hatch'
summary
Loading