Skip to content
Bitbucket CLIBitbucket CLI

Project Commands - Manage Bitbucket Projects

Projects are the grouping layer for repositories inside a workspace. Use these commands to discover the project keys you pass to bb repo create -p <KEY>.

Project commands run at workspace scope; no repository context is required. Unlike bb workspace view and the repo-scoped commands, they never infer the workspace from your git remote. Resolution is -w/--workspace → BB_WORKSPACE → defaultWorkspace. With none of those set, bb project list fails with No workspace specified. even inside a Bitbucket checkout — see Repository Context.

All three subcommands are non-interactive and accept the global flags, including --json [fields] and --jq <expression>.

bb project list

Section titled “bb project list”

List projects in a workspace.

Terminal window
bb project list [options]

Options

Section titled “Options”
Option Description
-w, --workspace <workspace> Workspace
--limit <number> Maximum number of projects (default: 25)
--all List all projects (overrides --limit)
--json Output as JSON

Examples

Section titled “Examples”
Terminal window
bb project list
bb project list -w my-workspace
bb project list --all


# Just key and name — a flat array, not the envelope
bb project list --json key,name


# Keys, one per line (JSON-quoted — the embedded jq has no -r)
bb project list --json --jq '.projects[].key'


# Unquoted keys for a shell loop — needs the jq binary
bb project list --json | jq -r '.projects[].key'

Output

Section titled “Output”
KEY       NAME               PRIVACY  DESCRIPTION                        UPDATED
--------  -----------------  -------  ---------------------------------  ------------------------
PLATFORM  Platform Services  private  Shared infrastructure and tooling  Jul 30, 2026 at 09:12 AM
WEB       Web Apps           private  Customer-facing web frontends      Jul 24, 2026 at 04:38 PM

An empty workspace prints No projects found in workspace <workspace>.

JSON output

Section titled “JSON output”

The envelope is { workspace, count, projects }, where projects is the array of project objects.

Notes

Section titled “Notes”
  • The DESCRIPTION column is truncated to 50 characters. Pass the global --no-truncate for the full text; --json always carries the full values.
  • When more results exist than --limit returned, the table is followed by Showing 25 projects. Use --limit <n> or --all to see more. This footer is never printed under --json.

bb project view

Section titled “bb project view”

View project details.

Terminal window
bb project view <key> [options]

Arguments

Section titled “Arguments”
Argument Description
key Project key (e.g. PROJ; lowercase input is uppercased automatically, so proj and PROJ resolve the same project)

Options

Section titled “Options”
Option Description
-w, --workspace <workspace> Workspace
--json Output as JSON

Examples

Section titled “Examples”
Terminal window
bb project view PROJ
bb project view PROJ -w my-workspace


# JSON is wrapped: { workspace, project }
bb project view PROJ --json --jq '.project.name'

Notes

Section titled “Notes”
  • An unknown key fails with Project <KEY> not found in workspace <workspace>. — exit code 1, and --json writes a structured error envelope to stderr.

bb project create

Section titled “bb project create”

Create a new project in a workspace.

Terminal window
bb project create [options]

Options

Section titled “Options”
Option Description
-w, --workspace <workspace> Workspace
-k, --key <key> Project key, e.g. PROJ (required; uppercased automatically)
-n, --name <name> Project name (required)
-d, --description <description> Project description
--private Create a private project (default)
--public Create a public project
--json Output as JSON

Examples

Section titled “Examples”
Terminal window
bb project create --key PROJ --name "My Project"
bb project create -k PROJ -n "My Project" -d "Team things" --public


# Then create repositories inside it
bb repo create my-repo -p PROJ


# The response is wrapped: { workspace, project }
bb project create -k PROJ -n "My Project" --json --jq '.project.key'

Notes

Section titled “Notes”
  • Projects are private by default. --private and --public cannot both be set. A private project cannot contain public repositories.
  • Keys must start with a letter and contain only letters, digits, and underscores. Bitbucket requires uppercase keys, so lowercase input is uppercased automatically; the CLI prints a note when it does, except under --json.
Section titled “Related”