ドキュメント

認証とプロファイル

Jira、Confluence、Bitbucket、JSM 向けに、API トークン、ベアラートークン、複数のプロファイルで atlassian-cli を認証する方法を解説します。

atlassian-cli は独立したオープンソースツールです。作成したトークンはお使いのマシン上にローカル保存されます。本プロジェクトおよび本サイトが Atlassian の認証情報を受け取ることはありません。

概要

atlassian-cli は3種類の認証方式に対応しています。いずれも auth コマンドグループだけで管理できます。

Atlassian Cloud の API トークン: Jira、Confluence、Jira Service Management 向けです。トークンはユーザー単位で発行され、id.atlassian.com/manage-profile/security/api-tokens で作成します。
Bitbucket のベアラートークン（OAuth アプリパスワード、アクセストークン、ワークスペースアクセストークン）。従来のアカウント向けに Basic 認証にも対応しています。
環境変数: プロファイルが未設定の場合や、CI で実行する場合に使います。

設定した各アカウントは、名前付きのプロファイルとして保存されます。プロファイルはいくつでも作成でき（例: personal、work、bb-ci）、フラグ1つで切り替えられます。

Atlassian Cloud の API トークン

Jira、Confluence、JSM で最も一般的な設定方法です。

1. API トークンを作成する

id.atlassian.com/manage-profile/security/api-tokens を開き、Create API token をクリックしてラベルを付け、表示された値をコピーします（値を確認できるのは1回だけです）。

トークンはあなた自身として認証されます。UI から Jira、Confluence、JSM でできる操作は、そのトークンを使えば CLI でも実行できます。

2. ログインする

atlassian-cli auth login \
  --profile work \
  --base-url https://your-domain.atlassian.net \
  --email you@company.com \
  --token $ATLASSIAN_API_TOKEN \
  --default

フラグの説明:

--profile: ローカルで付ける名前です。好きな名前を使えます。
--base-url: Atlassian Cloud の URL です。https:// を含めます。
--email: トークンを所有するアカウントのメールアドレスです。
--token: API トークンです。履歴に残らないよう、シェル変数を使ってください。
--default: --profile を省略したときに使うプロファイルにします。

3. 動作を確認する

atlassian-cli auth test --profile work
atlassian-cli jira issue search --jql "project = DEV" --limit 1

Bitbucket の認証

Bitbucket Cloud は2種類のトークンフローに対応しています。どちらも現行の方式です。アカウントの構成に合うほうを選んでください。

アプリパスワードは Atlassian により非推奨とされています。新規作成は2025年9月9日に停止され、既存のアプリパスワードは2026年6月9日に利用できなくなります。代わりに API トークン（Basic 認証）またはアクセストークン（Bearer 認証）を使ってください。

API トークン（Basic 認証）: 個人アカウント向け

id.atlassian.com/manage-profile/security/api-tokens で、Bitbucket にスコープを絞った Atlassian の API トークンを作成します（Bitbucket を選択）。アカウントのメールアドレスと組み合わせて使います。

atlassian-cli auth login \
  --profile work \
  --bitbucket \
  --email you@company.com \
  --token $BITBUCKET_TOKEN

アクセストークン（Bearer 認証）: CI や権限を絞りたい場合向け

アクセストークンはリポジトリ、プロジェクト、ワークスペース単位でスコープを設定できます。最小限の権限で運用したい CI パイプラインに最適です。

Bitbucket → ワークスペース / リポジトリ / プロジェクト → Settings → Access tokens
Create をクリックし、必要なスコープだけを付与します（例: repository:read、pullrequest:write）

atlassian-cli auth login \
  --profile bb-ci \
  --bitbucket --bearer \
  --token $BITBUCKET_TOKEN

Bearer 認証では --email は不要です。ログイン時のワークスペース指定は任意です。プロファイルに保存したい場合は --workspace を指定し、コマンドごとに指定する場合は --workspace <slug> を渡します。

動作を確認する

atlassian-cli auth test --bitbucket --profile bb-ci
atlassian-cli bitbucket whoami --profile bb-ci

プロファイル

プロファイルは、アカウントや環境ごとに認証情報を分離します。よくある使い分けは次のとおりです。

personal: 自分のサンドボックスインスタンス
work: 会社の本番インスタンス
bb-ci: CI パイプライン用にスコープを絞った Bitbucket トークン
staging / prod: 環境ごとに分けたプロファイル

プロファイルを一覧表示する

atlassian-cli auth list

コマンドごとにプロファイルを切り替える

atlassian-cli jira issue search --profile personal --jql "project = PERS"
atlassian-cli jira issue search --profile work --jql "project = DEV"

デフォルトを変更する

デフォルトにしたいプロファイルに対して、auth login に --default を付けて再実行します。

atlassian-cli auth login --profile work --base-url https://x.atlassian.net --email you@x.com --default

または、default_profile: を ~/.atlassian-cli/config.yaml 内で直接編集します。

プロファイルを削除する

atlassian-cli auth logout --profile bb-legacy                    # remove credentials, keep profile entry
atlassian-cli auth logout --profile bb-legacy --remove-profile   # remove profile entirely
atlassian-cli auth logout --profile work --bitbucket             # only remove the Bitbucket token

環境変数と CI/CD

CI では通常、シークレットを永続化したくありません。atlassian-cli は次の環境変数で保存済みのトークンを上書きします。確認する順序は記載のとおりです。

Jira / Confluence / JSM

ATLASSIAN_CLI_TOKEN_<PROFILE>: プロファイル単位の上書きです（プロファイル名は大文字にします）。例: ATLASSIAN_CLI_TOKEN_WORK。
ATLASSIAN_API_TOKEN: 有効なプロファイルが使用するフォールバック用のトークンです。

Bitbucket

ATLASSIAN_CLI_BITBUCKET_TOKEN_<PROFILE>: プロファイル単位の Bitbucket トークンです。
ATLASSIAN_BITBUCKET_TOKEN: Bitbucket 全般のフォールバックです。
BITBUCKET_TOKEN: こちらも認識されます（短く、GitHub Actions や Jenkins でよく使われます）。

--base-url、--email、ワークスペース（Bitbucket の場合）を設定したプロファイルは引き続き必要です。環境変数が上書きするのはトークンだけです。CI では、最小限の ~/.atlassian-cli/config.yaml をコミットするか、セットアップ手順でダミーのトークンを使って auth login を実行し、プロファイルが存在する状態にします。そのうえで、実行時に実際のトークンを環境変数で渡します。

# GitHub Actions example: token via env, profile metadata from config.yaml
- name: Sync Jira
  env:
    ATLASSIAN_API_TOKEN: ${{ secrets.ATLASSIAN_API_TOKEN }}
  run: |
    atlassian-cli auth login \
      --profile ci --base-url https://mycompany.atlassian.net \
      --email bot@mycompany.com --default
    atlassian-cli jira issue search --jql "project = REL" --format json

CI の完全な例は、Jira 一括遷移ランブックを参照してください。

認証情報の保存場所

ログインすると、atlassian-cli は認証情報を ~/.config/atlassian-cli/credentials（Linux / macOS）または %APPDATA%\atlassian-cli\credentials（Windows）に書き込みます。値は AES-256-GCM で暗号化されます。マシンごとの鍵は ~/.config/atlassian-cli/key にあります。

プロファイルのメタデータ（名前、ベース URL、デフォルトプロファイル）は ~/.atlassian-cli/config.yaml にあります。必要であれば手動で編集できます。リポジトリ内の configs/config.example.yaml を参照してください。

認証情報が平文のままディスクに保存されることはありません。Linux と macOS では、設定ディレクトリはデフォルトで chmod 700 になります。

トラブルシューティング

401 Unauthorized

多くの場合、トークンが誤っているか期限切れであるか、メールアドレスがトークンの所有者と一致していません。id.atlassian.com/manage-profile/security/api-tokens で再発行してください。

403 Forbidden

認証は成功していますが、権限が不足しています。Jira と Confluence では、プロジェクトやスペースのロールを確認してください。Bitbucket のベアラートークンでは、アクセストークンのスコープを確認してください。

"No default profile configured"

atlassian-cli auth list を実行します。何も表示されない場合は auth login を実行してください。プロファイルはあるがデフォルトが未設定の場合は、対象のプロファイルに対して auth login --default を再実行するか、default_profile: を ~/.atlassian-cli/config.yaml 内で編集します。

CI で認証情報ファイルが見つからない

CI では通常、認証情報ファイルではなく環境変数を使います。上記の環境変数と CI/CDを参照してください。

curl では動くのに atlassian-cli では動かない

--base-url にスキーム（https://）が含まれていること、末尾にスラッシュがないことを確認してください。--debug を付けて実行すると、リクエストの全体を確認できます。

次: コマンドリファレンス →