Bitbucket CLI

A powerful command-line interface for Bitbucket Cloud. Manage repositories, pull requests, issues, and pipelines directly from your terminal.

✨ Features

• 📁 Repository Management - List, view, clone, create, and manage repositories
• 🔀 Pull Requests - Create, review, merge, approve, and manage PRs
• 🐛 Issue Tracking - Create, view, comment on, and manage issues
• ⚡ Pipelines - Trigger, monitor, and manage CI/CD pipelines
• 🖥️ Interactive TUI - Beautiful terminal UI for browsing and managing resources
• 🔐 Secure Authentication - OAuth 2.0 preferred, API key fallback, with secure keyring storage

📦 Installation

Using Cargo (Recommended)

cargo install bitbucket-cli

Debian/Ubuntu

# Download the .deb package from releases
wget https://github.com/pegasusheavy/bitbucket-cli/releases/latest/download/bitbucket-cli_amd64.deb
sudo dpkg -i bitbucket-cli_amd64.deb

Red Hat/Fedora/CentOS

# Download the .rpm package from releases
wget https://github.com/pegasusheavy/bitbucket-cli/releases/latest/download/bitbucket-cli.x86_64.rpm
sudo rpm -i bitbucket-cli.x86_64.rpm
# or with dnf
sudo dnf install bitbucket-cli.x86_64.rpm

Arch Linux

# Download the package from releases
wget https://github.com/pegasusheavy/bitbucket-cli/releases/latest/download/bitbucket-cli-vX.X.X-x86_64.pkg.tar.zst
sudo pacman -U bitbucket-cli-vX.X.X-x86_64.pkg.tar.zst

# Or build from PKGBUILD
git clone https://github.com/pegasusheavy/bitbucket-cli.git
cd bitbucket-cli/packaging/arch
makepkg -si

Alpine Linux

# Download the tarball from releases
wget https://github.com/pegasusheavy/bitbucket-cli/releases/latest/download/bitbucket-cli-vX.X.X-alpine-x86_64.tar.gz
tar -xzf bitbucket-cli-vX.X.X-alpine-x86_64.tar.gz
sudo mv bitbucket /usr/local/bin/

Windows

Download the MSI installer from the Releases page and run it.

From Source

git clone https://github.com/pegasusheavy/bitbucket-cli.git
cd bitbucket-cli
cargo install --path .

Pre-built Binaries

Download pre-built binaries for your platform from the Releases page.

🚀 Quick Start

1. Authenticate

Option A: OAuth 2.0 (Recommended)

bitbucket auth login --oauth

You'll need to create an OAuth consumer first:

1. Go to your Bitbucket workspace settings
2. Set callback URL to ONE of these (the CLI will use the first available):
   • http://127.0.0.1:8080/callback
   • http://127.0.0.1:3000/callback
   • http://127.0.0.1:8888/callback
   • http://127.0.0.1:9000/callback
3. Select permissions:
   • Account (Read)
   • Repositories (Read)
   • Pull requests (Read, Write)
   • Issues (Read, Write)
   • Pipelines (Read, Write)
4. Copy the Key (Client ID) and Secret when prompted

Option B: API Key (For CI/Automation)

bitbucket auth login --api-key

You'll need to create an HTTP access token:

1. Go to Personal settings → HTTP access tokens
2. Create a new token with required permissions
3. Enter your username and token when prompted

Note: App passwords are deprecated by Atlassian. OAuth 2.0 is the preferred method.

2. Start Using

# List repositories
bitbucket repo list myworkspace

# View a repository
bitbucket repo view myworkspace/myrepo

# List pull requests
bitbucket pr list myworkspace/myrepo

# Create a pull request
bitbucket pr create myworkspace/myrepo --title "My PR" --source feature-branch

# Launch interactive TUI
bitbucket tui --workspace myworkspace

📖 Commands

🖥️ TUI Mode

Launch the interactive terminal UI for a visual way to browse and manage your Bitbucket resources:

bitbucket tui

Keyboard shortcuts:

• q - Quit
• 1-5 - Switch views (Dashboard, Repos, PRs, Issues, Pipelines)
• j/k or ↑/↓ - Navigate
• Enter - Select/Open
• r - Refresh

⚙️ Configuration

Configuration is stored in ~/.config/bitbucket/config.toml:

[auth]
username = "your-username"
default_workspace = "your-workspace"

[defaults]
branch = "main"

[display]
color = true
pager = true

📚 Documentation

Full documentation is available at pegasusheavy.github.io/bitbucket-cli

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

💖 Support

If you find this project useful, please consider:

• ⭐ Starring the repository
• 🐛 Reporting bugs
• 💡 Suggesting features
• 💰 Supporting on Patreon

Made with ❤️ by Pegasus Heavy Industries