Pipeline Commands - Run and Inspect Bitbucket Pipelines

Manage Bitbucket Pipelines (CI/CD), list runs, inspect a run and its steps, trigger and stop runs, wait for a run to finish, and read or follow step logs.

Pipeline commands operate at repository scope. Run them inside a cloned Bitbucket repository, or pass -w, --workspace <workspace> and -r, --repo <repo> explicitly.

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

An <id> is either the build number from the UI (42) or the pipeline UUID with braces ({a1b2c3d4-...}). view, watch and logs take an optional [id]: without one they use the newest run on the current git branch, and ask for an id outside a git checkout or on a detached HEAD. --json output is wrapped in an envelope keyed by workspace and repoSlug; the # → comments below show each shape.

---

bb pipeline list

List pipeline runs, newest first.

bb pipeline list [options]

Options

Option	Description
--status <status>	Filter by status: PARSING, PENDING, PAUSED, HALTED, BUILDING, ERROR, PASSED, FAILED, STOPPED, UNKNOWN (case-insensitive)
--branch <branch>	Filter by target branch
--sort <attribute>	Sort attribute: created_on, run_creation_date, creator.uuid; prefix with - for descending (default: -created_on)
--limit <number>	Maximum number of runs (default: 25)
--all	List all runs (overrides --limit)

Examples

bb pipeline list
bb pipeline list --status FAILED
bb pipeline list --branch main --limit 50

# → { workspace, repoSlug, [status], [branch], sort, count, pipelines }
bb pipeline list --json

# Build numbers of recent failures, via built-in --jq
bb pipeline list --status FAILED --json --jq '.pipelines[].build_number'

Notes

• Columns: build number, status (colored), ref (shortened to fit the terminal; disable with --no-truncate), trigger, created date (relative on a terminal), and duration for completed runs.

• --limit is enforced across paginated responses. When results are capped the CLI prints Showing 25 pipelines. Use --limit <n> or --all to see more. (suppressed with --json).

• --status and --sort ignore case, so failed and FAILED both work.

• An invalid value lists the allowed ones and, when the input is close to a valid one, suggests it:

  --status must be one of: PARSING, PENDING, PAUSED, HALTED, BUILDING, ERROR, PASSED, FAILED, STOPPED, UNKNOWN
  (Did you mean FAILED?)

---

bb pipeline view

View run details and a per-step summary. [id] is a build number or UUID (default: the newest run on the current branch).

bb pipeline view [id] [options]

Examples

# Newest run on the current branch
bb pipeline view

bb pipeline view 42
bb pipeline view {a1b2c3d4-0000-0000-0000-000000000000}

# → { workspace, repoSlug, pipeline, steps }
bb pipeline view 42 --json

# Status name of the run
bb pipeline view 42 --json --jq '.pipeline.state.result.name // .pipeline.state.name'

Notes

• The human view shows number, UUID, status, ref, the custom pipeline selector when the run used one (Pipeline:), trigger, creator, created/completed timestamps, duration, and a step table (index, name, status, duration).
• The step index is the value you pass to bb pipeline logs --step.
• The step table and the JSON steps array are complete even on large runs; the CLI follows the steps endpoint’s pagination.
• An unknown id returns Pipeline 42 not found in acme/api.

---

bb pipeline run

Trigger a pipeline run on a branch.

bb pipeline run [options]

Options

Option	Description
-b, --branch <branch>	Branch to run on (default: current git branch)
--commit <hash>	Run against a specific commit on the branch
-p, --pipeline <name>	Custom pipeline definition from bitbucket-pipelines.yml
--var <key=value...>	Pipeline variable; repeatable, value may contain =
--dry-run	Print the write request instead of sending it (details)

Examples

# Run the default pipeline for the current branch
bb pipeline run

bb pipeline run --branch main
bb pipeline run --pipeline deploy-prod --var ENV=prod --var DRY_RUN=false
bb pipeline run --branch main --commit abc123def456

# → { workspace, repoSlug, pipeline }; grab the build number
bb pipeline run --branch main --json --jq '.pipeline.build_number'

Notes

• Outside a git repository, --branch is required (the error tells you so).
• --pipeline <name> selects a custom: pipeline defined in bitbucket-pipelines.yml.
• Variables are sent unsecured; secured variables must be configured in repository settings.
• On success the CLI prints the build number plus ready-to-paste bb pipeline view / bb pipeline logs commands.

---

bb pipeline stop

Stop a running pipeline. <id> is a build number or UUID.

bb pipeline stop <id> [options]

Options

Option	Description
--dry-run	Print the write request instead of sending it (details)

Examples

bb pipeline stop 42

# → { workspace, repoSlug, pipelineId, stopped }
bb pipeline stop 42 --json --jq '.stopped'

Notes

• No --yes confirmation is required: stopping CI is reversible, rerun with bb pipeline run.

---

bb pipeline watch

Wait for a run to finish, printing each step’s status as it changes. Exits non-zero unless the run passes. [id] is a build number or UUID (default: the newest run on the current branch).

bb pipeline watch [id] [options]

Options

Option	Description
--interval <seconds>	Seconds between status checks (default: 10)

Examples

# Newest run on the current branch
bb pipeline watch

# Trigger, then block until the run passes
bb pipeline run && bb pipeline watch

# → { workspace, repoSlug, pipeline, steps }, same as `pipeline view`
bb pipeline watch 42 --json --jq '.pipeline.state.result.name'

Output:

Watching pipeline #42 on main
  1. Build: PENDING
  1. Build: IN_PROGRESS
  2. Test: PENDING
  1. Build: SUCCESSFUL
  2. Test: IN_PROGRESS
  2. Test: SUCCESSFUL
✓ Pipeline #42 SUCCESSFUL in 3m 12s

Notes

• A failed, stopped, errored or expired run exits 1 with error code 10001 CI_FAILED, after the final state is printed.
• A run paused on a manual step also ends the watch with 10001 (Pipeline #42 is paused, waiting for a manual step.): it has not passed, and it will not move until someone triggers the step.
• --json prints nothing while waiting, then the final { workspace, repoSlug, pipeline, steps } envelope. A failed run still exits 1, with the error envelope on stderr.
• Each poll makes at least two API calls (more for runs with over 10 steps). The 10 second default keeps a long watch well inside Bitbucket’s hourly rate limit.

---

bb pipeline logs

Print the raw log of a pipeline step. [id] is a build number or UUID (default: the newest run on the current branch).

bb pipeline logs [id] [options]

Options

Option	Description
-s, --step <uuid-or-index>	Step to fetch: a step UUID (braces optional) or a 1-based index
-f, --follow	Stream new output until the run finishes (every step unless --step)
--interval <seconds>	Seconds between log checks with --follow (default: 10)

Examples

# Single-step runs need no --step
bb pipeline logs 42

bb pipeline logs 42 --step 2
bb pipeline logs 42 --step {a1b2c3d4-0000-0000-0000-000000000000}
bb pipeline logs 42 --step a1b2c3d4-0000-0000-0000-000000000000

# → { workspace, repoSlug, pipelineId, stepUuid, log }
bb pipeline logs 42 --json --jq '.log'

# Stream every step of the newest run on this branch as it runs
bb pipeline logs --follow

# Stream one step; stops when that step finishes
bb pipeline logs 42 --follow --step 2

Notes

• With exactly one step, it is selected automatically.

• With several steps and no --step, the CLI lists the steps (index, name, status, UUID) instead of guessing. With --json it returns { workspace, repoSlug, pipelineId, count, steps } so scripts and agents can pick a step UUID and call again.

• Every step is selectable even on large runs, the CLI follows the steps endpoint’s pagination, so indexes and UUIDs beyond the API’s default page size of 10 work.

• The log is printed verbatim to stdout, so it pipes cleanly into grep or a file. On a terminal it opens in your pager (less -FRX unless BB_PAGER or PAGER says otherwise).

• --follow waits for a queued run to get steps, then prints each step’s log in order, fetching only new bytes on each poll. With several steps, each one starts with a ==> Step 2: Test header; parallel steps are printed one after another, not interleaved. It stops when the run finishes or pauses on a manual step, or, with --step, when that step finishes. It never opens the pager, so output appears as it is written. Use bb pipeline watch for the exit status.

• --follow cannot be combined with --json; use bb pipeline watch --json for the final state.

• Four failure modes, a queued run with no steps yet, an out-of-range --step index, a --step UUID that matches nothing, and a step that has produced no log yet, each get their own message, in that order:

  Pipeline 42 has no steps yet. It may still be queued — check with `bb pipeline view 42`.
  --step index 9 is out of range; the pipeline has 3 steps.
  No step matching 'abc' found. Available steps: 1 ({uuid-1}), 2 ({uuid-2}).
  No log found for step {uuid-2} of pipeline 42. The step may not have started yet.

---

See also

• Scripting & Automation, JSON envelopes, --jq, exit codes.
• CI/CD Integration, using bb inside pipelines.