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 own workspaces. 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 has access to.

Terminal window
bb workspace list [options]

Options

Section titled “Options”
Option Description
--role <role> Filter by your role: owner, collaborator, or member
--limit <number> Maximum number of workspaces (default: 25)
--all List all workspaces (overrides --limit)
--json Output as JSON

Examples

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


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


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


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

Output

Section titled “Output”
SLUG           NAME           PRIVACY  UUID
-------------  -------------  -------  --------------------------------------
acme-corp      Acme Corp      private  {6f1e8a2c-9d34-4b7e-8f21-0c5a7d3e1b90}
side-projects  Side Projects  public   {b2c9e740-15af-4d63-9a08-3e6f2c81d475}
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 { filters, count, workspaces }. workspaces holds the workspace objects; filters echoes the active --role filter, and is an empty object when unfiltered.

Notes

Section titled “Notes”
  • Role semantics: owner = admin access, collaborator = write access to at least one repository, member = member of at least one group or repository.
  • 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”
Option Description
-w, --workspace <workspace> Workspace (used when no slug argument is passed)
--json Output as JSON

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”