Skip to content
Bitbucket CLIBitbucket CLI

Workspace Commands - Discover Bitbucket Workspaces

Find the workspace slugs you pass to -w, --workspace, to bb config set defaultWorkspace, and to bb repo create.

Workspace commands run at account scope. bb workspace list needs no context at all, it lists your workspace memberships. bb workspace view falls back to the resolved workspace context when you pass no slug.

Both accept the global flags, including --json [fields], --jq <expression>, and -w, --workspace.

bb workspace list

Section titled “bb workspace list”

List the workspaces the authenticated user is a member of.

Terminal window
bb workspace list [options]

Options

Section titled “Options”
Option Description
--limit <number> Maximum number of workspaces (default: 25)
--all List all workspaces (overrides --limit)

Examples

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


# Only the columns you need — a flat array, not the envelope
bb workspace list --json workspace.slug,administrator


# Slugs, one per line (JSON-quoted — the embedded jq has no -r)
bb workspace list --json --jq '.workspaces[].workspace.slug'


# Bare slugs for a shell loop, via the jq binary
bb workspace list --json | jq -r '.workspaces[].workspace.slug'

Output

Section titled “Output”
SLUG           UUID                                    ADMIN
-------------  --------------------------------------  -----
acme-corp      {6f1e8a2c-9d34-4b7e-8f21-0c5a7d3e1b90}  yes
side-projects  {b2c9e740-15af-4d63-9a08-3e6f2c81d475}  no
Use a slug with -w <slug> or set a default: bb config set defaultWorkspace <slug>

That last line prints after every non-JSON bb workspace list.

JSON output

Section titled “JSON output”

The envelope is { count, workspaces }. Each workspaces entry is a membership record: { administrator, workspace: { slug, uuid, ... } }.

Notes

Section titled “Notes”
  • The list comes from GET /2.0/user/workspaces, so it shows the workspaces you are a member of (with an ADMIN column for admin access), not every workspace that exists.
  • Workspace name and privacy are not part of the membership payload; use bb workspace view <slug> for the full workspace object.
  • When more results exist than --limit returned, the table is followed by Showing 25 workspaces. Use --limit <n> or --all to see more. This footer is never printed under --json.

bb workspace view

Section titled “bb workspace view”

View workspace details.

Terminal window
bb workspace view [slug] [options]

Arguments

Section titled “Arguments”
Argument Description
slug Workspace slug (optional; defaults to the resolved workspace context)

Options

Section titled “Options”

Only global flags apply.

Examples

Section titled “Examples”
Terminal window
# Resolved workspace: -w, the current repository's remote,
# BB_WORKSPACE, then defaultWorkspace
bb workspace view


bb workspace view my-workspace


# JSON is wrapped: { workspace: { ... } }
bb workspace view my-workspace --json --jq '.workspace.uuid'

Notes

Section titled “Notes”
  • Without a slug, the workspace resolves in this order: the -w flag, the current repository’s Bitbucket remote, the BB_WORKSPACE environment variable, then the configured defaultWorkspace.
  • An unknown or inaccessible slug fails with Workspace <slug> not found (or you do not have access to it)., exit code 1, and --json writes a structured error envelope to stderr. Because that message already names the missing workspace, the generic 404 “check the slug” hint is suppressed.
Section titled “Related”