Jira API をコマンドラインから使う方法

atlassian-cli はコミュニティによる独立したオープンソースプロジェクトです。Atlassian と提携・関連しておらず、Atlassian による承認、推奨、後援のいずれも受けておらず、Atlassian が提供する公式 CLI（acli）でもありません。製品名は互換性を示す目的でのみ使用しています。

CLI ファーストのアプローチ

コマンドラインから Jira API を使う最速の方法は、API を直接呼び出さないことです。base64 の認証ヘッダー、JSON のリクエストボディ、手作業のページネーションを含む curl リクエストを書く代わりに、atlassian-cli の名前付きコマンドを実行し、生のレスポンスが必要なときだけ --format json を追加します。CLI は同じ REST エンドポイントをラップしているため、atlassian-cli jira issue search は内部的には GET /search であり、atlassian-cli jira issue create は POST /issue です。

重要な部分（JQL、課題キー、jq にパイプできる JSON 出力）はそのままに、作業を遅くする部分（認証まわりの下準備、ページネーションのループ、429 のバックオフ）を手放せるのが利点です。この記事では、Jira の読み取り、書き込み、スクリプト化を CLI ファーストで行う方法を解説します。生のエンドポイント、パス、ペイロードの形が必要な場合は、姉妹記事の Jira REST API ガイドをご覧ください。この記事はコマンドの層に留まります。

他との違い（と acli の位置づけ）

atlassian-cli は、コミュニティによる独立した MIT ライセンスのオープンソースプロジェクトです。Atlassian が提供する公式 CLI（acli）ではありませんし、Atlassian と提携・関連しておらず、Atlassian による承認、推奨、後援、保守のいずれも受けていません。ベンダーによる一次サポートが必要であれば、公式の acli を使ってください。Jira、Confluence、Bitbucket、Jira Service Management を横断し、すべてで一貫したフラグと機械可読な出力を備えた単一の無料 Rust バイナリが欲しい場合は、atlassian-cli を使ってください。

すべてのコマンドが同じ --format、--profile、--limit フラグを共有しているため、Jira API で身につけた操作感はそのまま Confluence の CQL 検索や Bitbucket のプルリクエストにも通用します。専用の curl スクリプトを集めたフォルダーではなく、ひとつのツールから API を扱う意味は、この一貫性にあります。

リクエストごとではなく一度だけ認証する

生の curl では、呼び出しのたびに Authorization ヘッダー（メールアドレスと Atlassian の API トークンを base64 エンコードしたもの）を付ける必要があります。CLI なら一度だけ認証し、認証情報を名前付きプロファイルに保存します。

# One-time login, stored as the "work" profile and set as default
atlassian-cli auth login \
  --profile work \
  --base-url https://your-site.atlassian.net \
  --email you@company.com \
  --token $TOKEN \
  --default

# Confirm the token works and see who you are
atlassian-cli auth whoami --profile work

API トークンは、REST 呼び出しのときとまったく同じく、Atlassian アカウントのセキュリティ設定から発行します。これ以降は、すべてのコマンドが保存済みの認証情報を再利用します。work や prod のように複数のプロファイルを持ち、コマンドごとに --profile で対象を切り替えられます。認証の全体像は認証とプロファイルのガイドをご覧ください。

データの読み取り: search と get

課題の読み取りは、GET /rest/api/3/search を置き換える部分です。startAt と maxResults を自分でループする代わりに、JQL の文字列を渡し、--limit で結果件数を制限します。

# Search with JQL (the API's GET /search endpoint)
atlassian-cli jira issue search \
  --jql "project = DEV order by created desc" \
  --limit 5

# Fetch a single issue (GET /issue/{key})
atlassian-cli jira issue get DEV-123

# List projects and inspect one
atlassian-cli jira project list
atlassian-cli jira project get DEV

読み取り系のコマンドはすべて --format json を受け付けるため、REST API が返すのと同じフィールド構造がそのまま得られ、jq にすぐ渡せます。API のペイロードに customfield_10010 として現れるカスタムフィールドの ID が必要なときは、推測せずに直接一覧表示しましょう。

# Discover custom field IDs used in API bodies
atlassian-cli jira fields list --format json | jq '.[] | {id, name}'

データの書き込み: 作成、更新、遷移、担当者の割り当て

書き込み系のエンドポイント（POST /issue、PUT /issue/{key}、そして遷移用のエンドポイント）は、4 つのコマンドに対応します。JSON のボディを手で組み立てる必要はありません。

# Create an issue (POST /issue)
atlassian-cli jira issue create \
  --project DEV \
  --issue-type Task \
  --summary "Investigate API latency"

# Update fields (PUT /issue/{key})
atlassian-cli jira issue update DEV-123 --summary "Updated summary"

# Transition through the workflow by name
atlassian-cli jira issue transition DEV-123 --transition "In Progress"

# Assign to a user
atlassian-cli jira issue assign DEV-123 --assignee user@example.com

カスタムフィールドも必要なときに使えます。jira fields list で調べた ID を使い、--field で生のフィールド JSON を渡します。

atlassian-cli jira issue create \
  --project DEV \
  --issue-type Task \
  --summary "cf test" \
  --field 'customfield_10010={"value":"Internal"}'

課題を数値 ID ではなく名前で遷移させられるのは小さな違いに見えますが、生の API で必要な手順をひとつ丸ごと省けます。生の API では、POST の前にまず GET で利用可能な遷移を取得し、正しい ID を探す必要があります。

スプリントへの所属も、CLI が API の面倒さを隠してくれる場面です。生の Agile API では、スプリントのカスタムフィールドの ID を知ったうえで、それをボディに含める必要があります。CLI なら、作成時でも既存の課題に対してでも、数値のスプリント ID をそのまま渡せます。

# Put an existing issue into a sprint by numeric ID
atlassian-cli jira issue update DEV-123 --sprint 25446

# Or create it straight into the sprint
atlassian-cli jira issue create \
  --project DEV --issue-type Task \
  --summary "In sprint" --sprint 25446

JSON 出力と jq: API レスポンスの層

ここが CLI ファーストのアプローチの真価を発揮する場面です。どのコマンドも --format json（または -f json）でクリーンな JSON を出力し、jq で実用的なクエリを組み立てられます。

# Just the issue keys
atlassian-cli jira issue search --jql "project = DEV" \
  --format json | jq '.[].key'

# Count bugs grouped by priority
atlassian-cli jira issue search \
  --jql "project = DEV AND type = Bug" \
  --format json | jq 'group_by(.fields.priority.name)
    | map({priority: .[0].fields.priority.name, count: length})'

行データとあわせて総件数が欲しいときは、--envelope を付けるとリスト出力が {"data": [...], "count": N} の形にラップされます。CI でのゲート判定には、終了コードだけを返す --format quiet が便利です。

# Envelope form for downstream parsing
atlassian-cli jira issue search --jql "project = DEV" \
  --format json --envelope | jq '.count'

# Exit-code-only check, useful in a pipeline gate
atlassian-cli auth test --profile prod --format quiet && echo OK

JSON 以外にも、同じデータを csv、yaml、markdown、あるいは人が読みやすい table として出力できます。--output issues.csv を使えば、スプレッドシートですぐ開けるファイルを直接書き出せます。呼び出しをデバッグしたいときは --debug を追加すると、内部の HTTP リクエストとレスポンスがログに記録され、生の API 通信を眺めるのに最も近い形になります。

atlassian-cli と生の Jira API の比較

同じ作業を、生の REST API で行った場合と CLI で行った場合とで並べます。内部で呼ばれるエンドポイントは同じです。変わるのは、自分で書く下準備のコード量だけです。

実務のワークフローをスクリプト化する

CLI が認証と出力を引き受けてくれるので、シェルスクリプトは短く読みやすい API 呼び出しの並びになります。次の例では、curl のヘッダーを一切書かずに、トリアージ用のレポートを取得し、担当者のいないバグを割り当て直します。

#!/bin/bash
# Daily triage: report open bugs, claim unassigned ones
set -euo pipefail

PROFILE="work"

# How many open bugs are there right now?
open_bugs=$(atlassian-cli jira issue search \
  --profile "$PROFILE" \
  --jql "project = DEV AND type = Bug AND status != Done" \
  --format json | jq 'length')
echo "Open bugs: $open_bugs"

# Assign unowned bugs to the triage lead (bulk endpoint)
atlassian-cli jira bulk assign \
  --profile "$PROFILE" \
  --jql "project = DEV AND type = Bug AND assignee is EMPTY" \
  --assignee triage-lead@company.com \
  --dry-run

jira bulk のサブコマンドは、ひとつの論理的な操作を数百件の課題へ展開するための仕組みです。プレビュー用の --dry-run と、並列リクエスト数を調整する --concurrency を受け付け、結果セット全体を自動でページングします。手作業ではなくスケジュールやイベントをきっかけに変更を実行したい場合は、Jira 自動化ガイドで、これらのコマンドを cron や CI に組み込む方法を解説しています。

すべてのフラグとサブコマンドについて、コピーしてすぐ使える構文はコマンドリファレンスにまとめています。別タブで開いておくと便利です。

よくある質問

関連リソース