Understanding Repository Context

Many commands in the Bitbucket CLI need to know which workspace and repository you’re working with. The CLI uses a sophisticated resolution system to determine this automatically, so you don’t always need to specify them explicitly.

Context Resolution Order

The CLI checks multiple sources in this order:

1. Command-line flags (--workspace and --repo)
2. Current Git repository (automatically detected from your git remote URL)
3. Config file defaults (defaultWorkspace setting)
4. Combinations of the above sources

Typical Local Layout

• Directoryprojects/

  • Directorymyworkspace-tools/

    • Directory.git/

      • …
    • Directorysrc/

      • Directorycommands/

        • …
      • Directoryservices/

        • …
    • README.md

When you run bb from myworkspace-tools/, the CLI reads the Bitbucket remote from .git/ and uses that workspace/repo as context.

Examples

Scenario 1: Inside a Git Repository

# You're in /projects/myrepo, which has a Bitbucket remote
cd /projects/myrepo
bb pr list  # ✅ Uses workspace/repo from git remote

The CLI reads your .git/config and extracts the workspace and repository from the remote URL.

Scenario 2: Using Command-Line Flags

# Explicit specification always takes precedence
bb pr list -w myworkspace -r myrepo  # ✅ Uses specified values

This works from anywhere, even outside a git repository.

Scenario 3: Using Config Defaults

# Set defaults once
bb config set defaultWorkspace myworkspace

# Then use commands without flags
bb repo list  # ✅ Uses defaultWorkspace from config

For PR commands, you still need repository context (from git remote or -r).

Scenario 4: Mixed Sources

# Inside a git repo with workspace "gitworkspace/gitrepo"
cd /projects/myrepo

# Override just the workspace
bb pr list -w anotherworkspace  # Uses "anotherworkspace/gitrepo"

# Override just the repo
bb pr list -r anotherrepo  # Uses "gitworkspace/anotherrepo"

Repository Argument Formats

Commands that accept a repository argument support multiple formats:

Full Format: workspace/repo

bb repo view myworkspace/myrepo
bb repo delete myworkspace/myrepo --yes

This explicitly specifies both workspace and repository.

Short Format: repo only

# Uses default workspace from config or git context
bb repo view myrepo

The CLI will:

1. Check if you set a default workspace via bb config set defaultWorkspace
2. Check if you’re in a git repository and use its workspace
3. Error if neither is available

Supported Remote URL Formats

When detecting context from git, the CLI supports these remote URL formats:

SSH Format

git@bitbucket.org:workspace/repo.git
git@bitbucket.org:workspace/repo

HTTPS Format

https://bitbucket.org/workspace/repo.git
https://bitbucket.org/workspace/repo
https://username@bitbucket.org/workspace/repo.git

Error Messages

”Could not determine repository”

This error appears when the CLI can’t figure out which workspace/repo to use.

Solutions:

1. Use explicit flags: -w myworkspace -r myrepo
2. Run from within a Bitbucket repository
3. Set defaults: bb config set defaultWorkspace myworkspace

”Repository not found”

The workspace/repo combination was determined but doesn’t exist.

Check:

1. Spelling of workspace and repository names
2. That you have access to the repository
3. That the repository exists in that workspace

Best Practices

For Daily Work

Set your default workspace if you primarily work with one:

bb config set defaultWorkspace myworkspace

Then work from within your git repositories - context will be automatic.

For Scripts

Always use explicit flags for reliability:

#!/bin/bash
WORKSPACE="myworkspace"
REPO="myrepo"

bb pr list -w "$WORKSPACE" -r "$REPO" --json

For Multi-Workspace Teams

Don’t set a default workspace. Instead, use explicit flags or work from within cloned repositories:

# Each repository is self-contained
cd project-a && bb pr list  # Uses project-a's workspace
cd ../project-b && bb pr list  # Uses project-b's workspace

Tips

• Use bb repo view with no arguments to see what context the CLI detected
• The --json flag works with most commands for scripting
• Global flags (--workspace, --repo, --json, --no-color) are available across commands
• The -w short flag always maps to --workspace globally