Bitbucket CLI (bkt)

bkt は Bitbucket Data Center と Bitbucket Cloud の統合CLI です。gh のエルゴノミクスをミラーリングし、オートメーション用に構造化されたJSON/YAML出力を提供します。

依存関係の確認

bkt コマンドを実行する前に、CLIがインストールされていることを確認してください:

bkt --version

コマンドが失敗したり bkt が見つからない場合は、以下のいずれかの方法を使用してインストールしてください:

プラットフォーム	コマンド
macOS/Linux	brew install avivsinai/tap/bitbucket-cli
Windows	scoop bucket add avivsinai https://github.com/avivsinai/scoop-bucket && scoop install bitbucket-cli
Go	go install github.com/avivsinai/bitbucket-cli/cmd/bkt@latest
バイナリ	GitHub Releases からダウンロード

インストールが成功したことを確認してから、bkt コマンドを実行してください。

認証

# Data Center (ブラウザを開いてPATを作成)
bkt auth login https://bitbucket.example.com --web

# Data Center (直接指定)
bkt auth login https://bitbucket.example.com --username alice --token <PAT>

# Bitbucket Cloud
bkt auth login https://bitbucket.org --kind cloud --web

# 認証状態を確認
bkt auth status

Bitbucket Cloud トークン要件:

• 「スコープ付きAPIトークン」を作成してください(一般的なAPIトークンではなく)
• アプリケーションとして Bitbucket を選択してください
• 必須スコープ: Account: Read (read:user:bitbucket)
• 必要に応じて追加スコープ: Repositories、Pull requests、Issues

コンテキスト

コンテキストはホスト、プロジェクト/ワークスペース、デフォルトリポジトリの設定を保存します:

# Data Center 用のコンテキストを作成
bkt context create dc-prod --host bitbucket.example.com --project ABC --set-active

# Cloud 用のコンテキストを作成
bkt context create cloud-team --host bitbucket.org --workspace myteam --set-active

# コンテキストを一覧表示し、切り替え
bkt context list
bkt context use cloud-team

クイックコマンドリファレンス

タスク	コマンド
リポジトリを一覧表示	bkt repo list
リポジトリを表示	bkt repo view <slug>
リポジトリをクローン	bkt repo clone <slug> --ssh
リポジトリを作成	bkt repo create <name> --description "..."
PRを一覧表示	bkt pr list --state OPEN
PRを表示	bkt pr view <id>
PRを作成	bkt pr create --title "..." --source feature --target main
PRをマージ	bkt pr merge <id>
PRチェック	bkt pr checks <id> --wait
ブランチを一覧表示	bkt branch list
ブランチを作成	bkt branch create <name> --from main
ブランチを削除	bkt branch delete <name>
課題を一覧表示 (Cloud)	bkt issue list --state open
課題を作成	bkt issue create -t "Bug title" -k bug
ウェブフック	bkt webhook list
パイプラインを実行	bkt pipeline run --ref main
API エスケープハッチ	bkt api /rest/api/1.0/projects

リポジトリ操作

bkt repo list --limit 20
bkt repo list --workspace myteam          # Cloud ワークスペースをオーバーライド
bkt repo view platform-api
bkt repo create data-pipeline --description "Data ingestion" --project DATA
bkt repo browse --project DATA --repo platform-api
bkt repo clone platform-api --ssh

プルリクエストワークフロー

# 一覧表示と表示
bkt pr list --state OPEN --limit 10
bkt pr list --mine                        # あなたが作成したPR
bkt pr view 42
bkt pr view 42 --web                      # ブラウザで開く

# 作成と編集
bkt pr create --title "feat: cache" --source feature/cache --target main --reviewer alice
bkt pr edit 123 --title "New title" --body "Updated description"

# レビューとマージ
bkt pr approve 42
bkt pr comment 42 --text "LGTM"
bkt pr merge 42 --message "merge: feature/cache"
bkt pr merge 42 --strategy fast-forward

# CI/ビルドステータス
bkt pr checks 42                          # ビルドステータスを表示
bkt pr checks 42 --wait                   # ビルドの完了を待機
bkt pr checks 42 --wait --timeout 5m      # タイムアウト付き
bkt pr checks 42 --fail-fast              # 最初のエラーで終了

# ローカルでチェックアウト
bkt pr checkout 42                        # pr/42 ブランチにフェッチ

ブランチ管理

bkt branch list
bkt branch list --filter "feature/*"
bkt branch create release/1.9 --from main
bkt branch delete feature/old-stuff
bkt branch set-default main               # DC のみ
bkt branch protect add main --type fast-forward-only  # DC のみ

課題追跡 (Bitbucket Cloud のみ)

bkt issue list --state open --kind bug
bkt issue view 42 --comments
bkt issue create -t "Login broken" -k bug -p major
bkt issue edit 42 --assignee "{uuid}" --priority critical
bkt issue close 42
bkt issue reopen 42
bkt issue comment 42 -b "Fixed in v1.2.0"
bkt issue status                          # あなたが割り当てられた/作成した課題

課題の種類: bug、enhancement、proposal、task 優先度: trivial、minor、major、critical、blocker

ウェブフック

bkt webhook list
bkt webhook create --name "CI" --url https://ci.example.com/hook --event repo:refs_changed
bkt webhook delete <id>
bkt webhook test <id>

パイプライン (Cloud)

bkt pipeline run --ref main --var ENV=staging
bkt pipeline list                         # 最近の実行
bkt pipeline view <uuid>                  # パイプラインの詳細
bkt pipeline logs <uuid>                  # ログを取得
bkt status pipeline <uuid>                # 代替: ステータス確認

権限 (DC)

bkt perms project list --project DATA
bkt perms project grant --project DATA --user alice --perm PROJECT_WRITE
bkt perms repo list --project DATA --repo platform-api
bkt perms repo grant --project DATA --repo api --user alice --perm REPO_WRITE

Raw API アクセス

まだラップされていないエンドポイントの場合:

bkt api /rest/api/1.0/projects --param limit=100 --json
bkt api /repositories --param workspace=myteam --field pagelen=50

出力モード

すべてのコマンドが構造化出力をサポートします:

bkt pr list --json                        # JSON 出力
bkt pr list --yaml                        # YAML 出力
bkt pr list --json | jq '.pull_requests[0].title'

グローバルオプション

• --json / --yaml — 構造化出力
• --context <name> — 特定のコンテキストを使用
• --project <key> — プロジェクトをオーバーライド (DC)
• --workspace <name> — ワークスペースをオーバーライド (Cloud)
• --repo <slug> — リポジトリをオーバーライド

環境変数

• BKT_CONFIG_DIR — 設定ディレクトリをオーバーライド
• BKT_ALLOW_INSECURE_STORE — ファイルベースの認証情報ストレージを許可
• BKT_KEYRING_TIMEOUT — キーリング操作のタイムアウト (例: 2m)

参考資料

• 完全なコマンドリファレンス: references/commands.md を参照してください