bitbottle

bitbottle CLI

Bitbucket Server/DC と Cloud 向けの gh スタイルの CLI です。このファイルは各コマンドの参照先を案内し、安全性に関する不変のルールを定めています。コマンドの詳細については、該当するリファレンスを読み込んでください。このファイルの内容を暗記しないでください。正確な形式とフラグ一覧は bitbottle <cmd> -h で確認してください。 動作がこのドキュメントと異なる場合は、bitbottle --version を実行してください。バイナリの動作が優先されます。

どのリファレンスを読み込むか

タスク	開くファイル
認証、hosts.yml、環境変数、複数ホスト、auth migrate、auth doctor	references/auth.md
PR のライフサイクル（list/view/create/merge/merge-preview/approve/comment/activity/review/commits/files/participants/ready/unready/task/suggestion/comment-react/default-reviewer/reviewer-group/…）	references/pr.md
リポジトリ、ブランチ、タグ、ファイル／ツリー、公開範囲、編集、移管、ウォッチャー、リポジトリラベルの list/create/update/delete、リポジトリの pr-settings get、リポジトリの pr-settings set、リポジトリのダウンロード list/upload/get/delete、リポジトリのクローン（MCP：clone_repo）、リポジトリのフック list/view/enable/disable/settings get/set（Server/DC のみ）、リポジトリの Cloud フォーク同期（MCP：sync_repo）	references/repos.md
コミット（log、search、view/files/status/comment/comment-react）	references/commit.md
パイプライン、パイプライン設定 get/enable/disable、スケジュール、キャッシュ、ウォッチ、トリガー、テストレポート view、テストケース list、SSH キーペア、既知のホスト、OIDC 設定／キー（Cloud のみ）	references/pipeline.md
パイプラインランナー — list / create / delete（Cloud のみ）	references/runner.md
Code Insights のレポート／注釈（Cloud + Server/DC）、merge-check（Server/DC のみ）	references/code-insights.md
課題、コメント、添付ファイル（list/delete）、投票／投票取り消し、ウォッチ／ウォッチ解除、アクティビティ／変更ログ（Cloud のみ）	references/issues.md
課題のマイルストーン list/view（Cloud のみ）	references/milestone.md
課題のバージョン list/view/create/delete（Cloud のみ）	references/version.md
スニペットの list/view/create/delete、スニペットコメントの list/add/delete（Cloud のみ）	references/snippet.md
デプロイメント + 環境 + 変数（Cloud のみ）	references/deployment.md、references/variable.md
デプロイキー（両方）、ブランチルール（Cloud のみ）、ssh-keys（Cloud + Server/DC）	references/deploy-key.md、references/branch-rule.md、references/ssh-key.md
参照間の差分、diff REF1..REF2	references/diff.md
ブランチ比較（branch compare BASE..HEAD）— 先行／遅延数 + コミット一覧（Cloud + Server/DC）	references/branch.md
ワークスペース + Webhook + ワークスペースプロジェクトの CRUD + ワークスペースプロジェクトの権限 + ワークスペースの権限 + ワークスペースのパイプライン変数（Cloud のみ）、user view	references/workspace.md、references/user.md
ミラーサーバー（list/view/repo list）（Server/DC のみ）	references/mirror.md
名前付き認証情報プロファイル（profile create/use/list/delete）	references/profile.md
REST API の直接呼び出し、ページネーション、MCP サーバー設定	references/api.md
拡張機能（extension install/list/upgrade/remove/exec、拡張機能のひな形作成）	references/extension.md
グループ管理 — グループ list、グループ create、グループ delete、グループメンバー list、グループメンバー add、グループメンバー remove（Server/DC のみ）	references/groups.md
プロジェクトの CRUD — project server-list、project create、project view、project edit、project delete（Server/DC のみ）、project list WORKSPACE（Cloud のみ）	references/project.md
auth pat list/create/revoke（Server/DC のみ）	references/auth.md
ホスト情報 — バックエンドの種類、ベース URL、バージョン、機能一覧（host info [--json]）	references/host.md

タスクが複数の領域にまたがる場合は、両方を読み込んでください。必要性が不明な段階で読み込まないでください。

安全ルール（常に適用）

1. トークンを絶対に表示しないでください。 トークンは標準入力（--with-token）または BB_TOKEN 環境変数を介して渡してください。PAT/App Password をコマンドラインに 絶対に指定しないでください。シェルの履歴に残ります。
2. 破壊的な操作の前に確認してください。 repo delete、repo rename、 branch delete、tag delete、webhook delete、pr decline、 pr merge は取り消せません（repo rename は Cloud 上で既存のクローンの origin URL を無効にします）。正確なコマンドと解決済みの host/PROJECT/REPO、および PR/ブランチ/タグ名を表示してから、明示的な確認を待ってください。
3. 存在しないフラグを捏造しないでください。 bitbottle は gh に似た形式ですが、 gh と互換性のあるフラグではありません。bitbottle <cmd> -h にないフラグは 指定しないでください。よくある架空のフラグ：--author、--mine、--reviewer @me （「自分」を示す特別な値はありません。ユーザーのスラッグを指定してください）。
4. --json はフィールドセレクターではなく BOOLEAN フラグです。 --json は オブジェクト全体を JSON として出力します。絞り込むには --jq EXPR を使ってください。 --json title,body を渡すと、--json と位置引数 （title,body）として解析され、accepts N arg(s), received N+1 で失敗します。フィールド名を 確認するには、まず --json を指定して実行し、オブジェクトを調べてください。

引数の形式（よくある落とし穴）

bitbottle のリポジトリ指定方法は一貫していません。-h の記載に従ってください。

コマンドグループ	リポジトリ引数	備考
pr *（view/list/create/merge/…）	-R [HOST/]PROJECT/REPO フラグ	-R のみ使用可能。位置引数はありません
repo *、branch *、tag *、webhook *	位置引数 PROJECT/REPO	-R は継承されたフラグ一覧にありますが、黙って無視されます。PROJECT/REPO を位置引数として渡し、--hostname HOST は別に指定してください
commit view PROJECT/REPO HASH	位置引数、PROJ/REPO が先
commit files HASH [PROJECT/REPO]	位置引数、HASH が先	commit view とは逆です
commit cherry-pick HASH BRANCH [PROJECT/REPO]	位置引数、HASH、次に BRANCH	Server/DC のみ（branch-utils プラグイン）。--message/-m はコミットメッセージを上書きします
issue *、code-insights *	位置引数 [PROJECT/REPO] または -R	省略可能。デフォルトはチェックアウト先です

Bitbucket のチェックアウト先以外では、該当する位置引数/-R が必須です。

MCP ツールでは、正規のリポジトリ引数形式は 1 つです：{project, slug}（および 省略可能な hostname）。project は Server のプロジェクトキー、または Cloud のワークスペース スラッグ、slug はリポジトリのスラッグです。従来、単一の repo（WORKSPACE/REPO）文字列、または {project, repo} を受け取っていた一部のツール（compare_refs、 list_pr_commits、list_pr_files、get_repo_pr_settings、 set_repo_pr_settings）も、現在は {project, slug} を受け取ります。旧形式は 1 リリースの間は引き続き使用できますが、結果に非推奨の注記が含まれます。各ツールの tools/list エントリーには _meta.backends（["server"]、 ["cloud"]、または両方）も記載されています。Server 専用ツールを Cloud ホストに対して 呼び出した場合（またはその逆）は HTTP 通信の前に host.unsupported が返され、 不明な hostname の場合は、設定済みのホスト一覧を含む host.unknown が返されます。

リポジトリ指定と TLS

# Inside a Bitbucket checkout: host/project/repo auto-detected.
# Outside one (or to override):
bitbottle pr list      -R git.example.com/PROJ/repo
bitbottle repo view    PROJ/repo --hostname git.example.com
bitbottle repo edit    PROJ/repo --description "new description"

# Pin a default for the current checkout (writes .git/config):
bitbottle repo set-default HOST/PROJ/repo

Server/DC で自己署名 CA を使用していますか？ -k / --skip-tls-verify は すべてのコマンドに継承されるフラグです。永続的に設定するには、 hosts.yml のホストエントリーで skip_tls_verify: true を設定してください （references/auth.md を参照）。

Cloud と Server/DC

Cloud の自動マージは今回のリリースでは延期されています。pr merge --auto、 pr merge --auto-off、および auto=true を指定した MCP の merge_pr は、 HTTP リクエストを送信する前に、対処方法を示すヒントとともに pr.automerge.unavailable を返します。通常のマージ、スカッシュ、リベースは引き続き利用できます。Server/DC の自動マージの動作に変更はありません。DC は実環境で未検証です。

	Cloud（bitbucket.org）	Server/DC（セルフホスト）
認証コンテキストのフラグ	--email you@…	--username your.user
トークンの種類	アプリパスワード／API トークン	PAT（BBDC-…）
API ベースパス	2.0/…	rest/api/1.0/…
Cloud のみ	pipeline *（list/view/run/stop/trigger/watch/logs/steps/schedule/cache/variable/config/test-report/test-case）、runner list、runner create、runner delete、issue *（issue attachment list/delete、issue vote/unvote、issue watch/unwatch、issue activity を含む）、snippet list [--workspace W]、snippet view、snippet create、snippet delete、snippet comment list、snippet comment add、snippet comment delete、pr request-changes、pr comment resolve、branch-rule *、branch-model *、workspace *（workspace search、workspace perms *、workspace project perms *、workspace project default-reviewer * を含む）、search、project list WORKSPACE	—
Server のみ	—	admin user list/activate/deactivate/rename、admin license、admin cluster、admin secrets rotate、admin logging get/set、code-insights *、pr task *、pr suggestion apply、pr/commit comment react/unreact、pr reviewer-group *、repo pr-settings get、repo pr-settings set、group list、group create、group delete、group member list、group member add、group member remove、mirror list、mirror view、mirror repo list、project server-list、project create、project view、project edit、project delete、auth pat list、auth pat create、auth pat revoke、commit cherry-pick HASH BRANCH

カスタムホスト名の Bitbucket Data Center では、hosts.yml の backend_type: cloud|server でルーティングを指定します。

ホットパス環境変数

変数	効果
BB_TOKEN	トークンの上書き（CI での使用）
BB_HOST	--hostname のデフォルト値
BB_REPO	-R [HOST/]PROJECT/REPO のデフォルト値
BB_PROMPT_DISABLED	プロンプトを表示せずに失敗する（非対話モード）
BB_CONFIG_DIR	設定ディレクトリを上書きする（デフォルトは $XDG_CONFIG_HOME/bitbottle）

エラー発生時のヒント

メッセージ	対処方法
not authenticated; run bitbottle auth login	ホストが設定されていません。auth login を実行してください。
multiple hosts configured; specify hostname	--hostname HOST または -R HOST/PROJ/repo を指定してください。
no git remotes found; pass [HOST/]PROJECT/REPO	チェックアウトの外にいます。位置引数または -R を指定してください。
--json … の後に accepts N arg(s), received N+1 と表示される	--json field1,field2 と記述しています。bitbottle の --json はブール値です。フィールド一覧を削除し、--jq を使用してください。
warning: token found in hosts.yml — run bitbottle auth migrate	トークンを OS のキーリングに移行するまで、すべてのコマンドで表示されます。bitbottle auth migrate を一度実行してください。
code-insights … unsupported on host	Server/DC 専用の機能です。bitbottle context でホストを確認してください。
Cloud の認証に失敗する	通常は --email の指定漏れ、または誤りが原因です。アプリパスワードにはユーザー名ではなく、Atlassian のメールアドレスが必要です。
Server/DC の認証に失敗する	--username の指定漏れ、または HTTPS 専用 PAT に --git-protocol ssh を使用したことが原因です。
認証情報／キーリング／TLS／プロキシに関する問題	bitbottle auth doctor [--hostname HOST] は、キーリングのバックエンド、トークンの有無と形式、ベース URL への到達性、認証の成否を報告します。トークンを出力することはありません。

パイプラインのライフサイクル（Cloud のみ）

# Trigger, watch, stop, view
bitbottle pipeline trigger WORKSPACE/REPO --branch main
bitbottle pipeline watch WORKSPACE/REPO UUID
bitbottle pipeline stop UUID WORKSPACE/REPO --confirm
bitbottle pipeline rerun UUID WORKSPACE/REPO
bitbottle pipeline view UUID WORKSPACE/REPO

# Pipeline config (Cloud only)
bitbottle pipeline config get WORKSPACE/REPO
bitbottle pipeline config enable WORKSPACE/REPO
bitbottle pipeline config disable WORKSPACE/REPO

# List and download step artifacts
bitbottle pipeline artifact list PIPELINE_UUID WORKSPACE/REPO --step STEP_UUID
bitbottle pipeline artifact download PIPELINE_UUID WORKSPACE/REPO \
  --step STEP_UUID --name build.tar.gz [--out PATH|-] [--clobber]

# Test report and test cases (Cloud only)
bitbottle pipeline test-report view PIPELINE_UUID WORKSPACE/REPO --step STEP_UUID
bitbottle pipeline test-case list PIPELINE_UUID WORKSPACE/REPO --step STEP_UUID [--status FAILED|PASSED|SKIPPED] [--limit N]

# Pipeline SSH configuration (Cloud only)
bitbottle pipeline ssh key-pair view [WORKSPACE/REPO]
bitbottle pipeline ssh key-pair regenerate [WORKSPACE/REPO] [--bits 2048|4096] [--confirm]
bitbottle pipeline ssh known-hosts list [WORKSPACE/REPO]
bitbottle pipeline ssh known-hosts view UUID [WORKSPACE/REPO]
bitbottle pipeline ssh known-hosts add HOSTNAME [WORKSPACE/REPO] [--key KEY] [--key-type rsa|ecdsa|ed25519]
bitbottle pipeline ssh known-hosts delete UUID [WORKSPACE/REPO] [--confirm]

# Pipeline OIDC configuration (Cloud only)
bitbottle pipeline oidc config WORKSPACE [--json]
bitbottle pipeline oidc keys WORKSPACE [--json]

# Branch compare (Cloud + Server/DC)
bitbottle branch compare main..feature WORKSPACE/REPO
bitbottle branch compare main..feature WORKSPACE/REPO --json

ダッシュボード

# Open PRs (author + reviewer) across a repo, or globally with --hostname
bitbottle status [PROJECT/REPO]
bitbottle pr status [PROJECT/REPO]

# Open a Bitbucket page in the browser
bitbottle browse [PROJECT/REPO]              # repo home
bitbottle browse [PROJECT/REPO] 42           # PR #42
bitbottle browse [PROJECT/REPO] abc1234      # commit
bitbottle browse [PROJECT/REPO] src/main.go  # file

インストール／バージョン

npm install -g @proggarapsody/bitbottle を実行すると、CLI がインストールされ、 このスキルが自動登録されます。npm 以外でインストールした場合（Homebrew、Go、単体 バイナリ）は、bitbottle skill install（更新）、skill path（場所の確認）、 skill remove（アンインストール）を使用してください。