Trigger and Monitor Bitbucket Pipelines from the CLI

atlassian-cli is an independent, community open-source project, not affiliated with, endorsed by, or sponsored by Atlassian, and is not Atlassian's official CLI (acli). Product names are used only to identify compatibility.

To trigger and monitor Bitbucket Pipelines from the command line, use the bitbucket pipelines cli built into atlassian-cli: run atlassian-cli bitbucket pipeline trigger --ref-name main to start a build, then pipeline watch or pipeline status --wait to follow it to completion. No dashboard, no manual clicking, no polling a browser tab.

This post focuses on the operator's workflow: kicking off runs (including named custom pipelines from bitbucket-pipelines.yml), reading logs in your terminal, and wiring the results into scripts through real process exit codes. Every command below is copy-pasteable and matches the actual subcommands the binary ships.

How this differs from acli: atlassian-cli is an independent, community, MIT-licensed open-source project. It is not Atlassian's official CLI (acli) and is not affiliated with Atlassian. Use the official acli if you want first-party vendor support; use atlassian-cli if you want a single free Rust binary that spans Jira, Confluence, Bitbucket, and Jira Service Management with pipeline control included.

How the Bitbucket Pipelines CLI Works

Pipeline commands live under atlassian-cli bitbucket pipeline (the shorter bb alias works everywhere too). Each command needs to know two things: the workspace and the repository. You can pass them explicitly:

# Explicit workspace and repo
atlassian-cli bitbucket --workspace myteam --repo api-service \
  pipeline list

Or you can skip both. When you run inside a cloned repository, --repo is auto-detected from the git remote and the workspace resolves from your configured profile. So from a project directory the same command collapses to:

# Inside a cloned Bitbucket repo, both are inferred
cd api-service
atlassian-cli bb pipeline list --recent 5

Before any of this works you need to be authenticated. If you have not set up a profile yet, run atlassian-cli auth login once and follow the authentication guide. The examples below use the explicit --workspace/--repo form so they are unambiguous, but you can drop those flags whenever you are inside the repo.

Trigger a Pipeline

The core command is pipeline trigger. The only required flag is --ref-name, which names the branch or tag to build:

# Run the default branch pipeline on main
atlassian-cli bb --workspace myteam --repo api-service \
  pipeline trigger --ref-name main

By default the ref is treated as a branch. To build a tag instead, add --ref-type tag:

# Build a release tag
atlassian-cli bb --workspace myteam --repo api-service \
  pipeline trigger --ref-name v1.4.0 --ref-type tag

You can inject variables into the run with repeated --var KEY=VALUE flags. These behave like the variables you would normally set in the Bitbucket UI, but they are scoped to this single run. Add --secured to mark all of them as secret so they are masked in the logs:

# Pass build-time variables into a single run
atlassian-cli bb --workspace myteam --repo api-service \
  pipeline trigger --ref-name main \
  --var DEPLOY_ENV=staging \
  --var RELEASE_NOTES="hotfix 1.4.1"

Every trigger returns the new build number. That number (or the pipeline UUID) is the handle you pass to watch, logs, get, and stop.

Run a Custom Pipeline

Bitbucket lets you define named pipelines under the custom: section of bitbucket-pipelines.yml that never run automatically on a push. They exist to be invoked on demand: a nightly integration suite, a one-off data migration, a manual deploy gate. The --custom-pipeline flag runs exactly one of them by name.

# bitbucket-pipelines.yml
# pipelines:
#   custom:
#     s3-access-test:
#       - step:
#           script:
#             - ./scripts/check-s3.sh

# Trigger that custom pipeline against main
atlassian-cli bb --workspace myteam --repo api-service \
  pipeline trigger --ref-name main \
  --custom-pipeline s3-access-test

The selector name after --custom-pipeline must match a key under custom: exactly. You can combine it with --var and --secured in the same way as a normal trigger, which is how you parameterize a manual deploy without editing the YAML:

# Manual deploy pipeline, parameterized per run
atlassian-cli bb --workspace myteam --repo api-service \
  pipeline trigger --ref-name main \
  --custom-pipeline deploy \
  --var TARGET=production --secured

Watch a Run Until It Finishes

Triggering a build is only half the job. pipeline watch polls a run and prints its state until it reaches a terminal result, then exits. With no argument it follows the most recent pipeline; pass a build number to follow a specific one.

# Watch the latest run, refreshing every 10 seconds, with per-step status
atlassian-cli bb --workspace myteam --repo api-service \
  pipeline watch --interval 10 --steps

The poll interval defaults to 5 seconds. A few flags make watch useful in unattended contexts:

• --timeout <seconds> caps how long you will wait. If the run has not finished in time, the command exits with code 2 so you can treat a hung build as a failure.
• --on-complete <command> runs a shell command the moment the pipeline finishes. It receives the environment variables PIPELINE_STATUS, PIPELINE_BUILD_NUMBER, PIPELINE_UUID, and PIPELINE_REF_NAME.
• --log switches to one line per poll with no ANSI escape codes, which is what you want when the output is captured to a file. It is enabled automatically when stdout is not a terminal.

# Watch build 412, notify on completion, give up after 30 minutes
atlassian-cli bb --workspace myteam --repo api-service \
  pipeline watch 412 \
  --timeout 1800 \
  --on-complete 'echo "Build #$PIPELINE_BUILD_NUMBER finished: $PIPELINE_STATUS"'

Because --on-complete gets the status and build number as environment variables, it is a natural hook for a Slack message, a desktop notification, or triggering a downstream step.

Stream and Filter Logs

When a build breaks you want the log, not a browser tab. pipeline logs prints the step output for a run directly in your terminal. With no positional argument it targets the latest pipeline; pass a build number to pick one.

# Print logs for the latest run
atlassian-cli bb --workspace myteam --repo api-service pipeline logs

# Logs for a specific build
atlassian-cli bb --workspace myteam --repo api-service pipeline logs 412

Full logs from a multi-step build get long fast, so there are flags to narrow them down. --failed-only skips the steps that passed, --step matches a step by name, and --grep filters individual log lines (add -i for case-insensitive matching):

# Only the failed steps of a broken build
atlassian-cli bb --workspace myteam --repo api-service \
  pipeline logs 412 --failed-only

# Just the error lines, case-insensitive
atlassian-cli bb --workspace myteam --repo api-service \
  pipeline logs 412 --grep "error" -i

# Logs from a single named step
atlassian-cli bb --workspace myteam --repo api-service \
  pipeline logs 412 --step "Run tests"

Combining --failed-only with --grep is the fastest way to answer "why did the last build fail?" without scrolling through a green build's worth of noise first.

Status and Exit Codes for CI

The reason the pipeline commands are scriptable is that they map pipeline state onto meaningful process exit codes. pipeline status prints the latest run as JSON and exits with a code you can branch on:

Add --wait to block until the run reaches a terminal state before returning, polling on the --interval you set (default 10 seconds). That gives you a single command that both waits for the build and reports its verdict through $?:

# Wait for the latest run, then act on the result
atlassian-cli bb --workspace myteam --repo api-service \
  pipeline status --wait --interval 15

if [ $? -eq 0 ]; then
  echo "Pipeline green, promoting build"
else
  echo "Pipeline not green, aborting" >&2
  exit 1
fi

Because the exit code is real, you rarely need the if at all. Under set -e, a non-zero status halts the script on its own. And since status emits JSON, you can also pull specific fields with jq when you need more than the exit code:

# Extract the build number of the latest run
atlassian-cli bb --workspace myteam --repo api-service \
  pipeline status --format json | jq '.build_number'

Inspect and Re-run Failed Builds

Alongside triggering and watching, the CLI covers the inspect-and-retry loop. pipeline list shows recent runs, pipeline latest jumps straight to the newest run on a branch, and pipeline get shows one run in detail. Add --steps to any of them to include per-step status.

# Five most recent runs with step summaries
atlassian-cli bb --workspace myteam --repo api-service \
  pipeline list --recent 5 --steps

# Latest run on a specific branch
atlassian-cli bb --workspace myteam --repo api-service \
  pipeline latest --branch main --steps

# Full detail of one run by build number
atlassian-cli bb --workspace myteam --repo api-service \
  pipeline get 412 --steps

pipeline list also filters by --branch, by time window with --since and --before (accepting values like 24h, 7d, or an ISO timestamp), and by pull request with --pr. When a flaky run needs another attempt, pipeline rerun re-runs the same commit:

# Re-run a specific build on the same commit
atlassian-cli bb --workspace myteam --repo api-service \
  pipeline rerun 412

# Re-run only the failed steps of a PR's latest pipeline
atlassian-cli bb --workspace myteam --repo api-service \
  pipeline rerun --pr 128 --failed-only

And to abort a run that is going nowhere, pipeline stop takes the same build-number or UUID handle:

atlassian-cli bb --workspace myteam --repo api-service \
  pipeline stop 412

Command Reference

The full set of pipeline subcommands and their most useful flags:

For the complete flag list across every Bitbucket command, see the commands reference, and for the wider Bitbucket workflow (repos, branches, pull requests, permissions) start at the Bitbucket CLI hub.

FAQ

Related Resources