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
--limit <number> Maximum number of projects (default: 25)
--all List all projects (overrides --limit)

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  3 days ago
WEB       Web Apps           private  Customer-facing web frontends      last week

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”
  • Long NAME and DESCRIPTION values are shortened to fit the terminal width. 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”

Only global flags apply.

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
-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
--dry-run Print the write request instead of sending it (details)

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”