CLI で Jira のタスクとサブタスクを管理する

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

ターミナルからのタスク運用

コマンドラインからの Jira のタスク管理とは、ターミナルを離れずに個々の課題を作成し、リンクし、遷移させ、更新することです。atlassian-cli なら、1つのコマンドで Jira のタスクを作成し、別のコマンドでサブタスクを紐付け、さらに別のコマンドでワークフローを進められます。マウスも、ブラウザーへの切り替えも不要で、どの手順もスクリプトに貼り付けられる1行です。

このガイドが扱うのは、開発者が Jira に費やす時間の大半を占める日常の操作です。タスクの起票、サブタスクへの分割、「blocks」や「relates to」のリンクの設定、ステータスを前に進めること、コメントの追加といった作業です。小さく反復的なこれらの操作が積み重なります。ターミナルで行えば集中を切らさずに済み、どの操作も再現できるようになります。

コマンドを実行する前に、atlassian-cli auth login で一度認証しておいてください（認証ガイドを参照）。以下の例はプロジェクトキーが DEV であることを前提にしています。ご自身のキーに置き換えてください。

タスクを作成する

中心となるコマンドは jira issue create です。最低限、プロジェクト、課題タイプ、要約が必要です。

# Minimal task
atlassian-cli jira issue create \
  --project DEV \
  --issue-type Task \
  --summary "Add rate-limit retry to the API client"

成功すると CLI は新しい課題キー（たとえば DEV-142）を表示します。同じ呼び出しでさらに多くのフィールドを埋められます。--description フラグは Markdown を受け付け、Jira のリッチテキスト形式である ADF に変換するため、見出し、リスト、太字、インラインコード、リンクがいずれも正しく表示されます。

# Fully specified task
atlassian-cli jira issue create \
  --project DEV \
  --issue-type Task \
  --summary "Add rate-limit retry to the API client" \
  --description "Retry on HTTP 429 with exponential backoff. See DEV-98 for the throttling report." \
  --assignee dev@example.com \
  --priority High

カスタムの「Team」や「Sprint」の選択リストのように、専用のフラグがないフィールドが必要なときは、繰り返し指定できる --field フラグに key=JSON のペアを渡します。フィールド ID は atlassian-cli jira fields list で調べられます。

atlassian-cli jira issue create \
  --project DEV \
  --issue-type Task \
  --summary "Instrument the retry path" \
  --field 'customfield_10010={"value":"Platform"}'

タスクができたら、jira issue get でいつでも読み出せます。

atlassian-cli jira issue get DEV-142

タスクをサブタスクに分解する

Jira のサブタスクは、サブタスク用の課題タイプと親を持つ通常の課題です。atlassian-cli には専用の --parent フラグがないため、親のキーを使って同じ汎用の --field の仕組みで親を設定します。

# Two subtasks under DEV-142
atlassian-cli jira issue create \
  --project DEV \
  --issue-type Sub-task \
  --summary "Write the backoff helper" \
  --field 'parent={"key":"DEV-142"}'

atlassian-cli jira issue create \
  --project DEV \
  --issue-type Sub-task \
  --summary "Add unit tests for 429 handling" \
  --field 'parent={"key":"DEV-142"}'

ここで大事な点が2つあります。1つめは、--issue-type にはプロジェクトに存在するサブタスク用のタイプを指定する必要があるという点です。Jira の既定は Sub-task ですが、インスタンスによっては名前が変更されています（たとえば Subtask）。2つめは、parent は予約キーではないため --field で渡すことができ、Jira の REST のフィールドにそのまま対応するという点です。

親の配下にあるすべてのサブタスクを見るには、JQL で検索します。JQL の parent フィールドが子を直接返します。

# List all subtasks of DEV-142
atlassian-cli jira issue search --jql "parent = DEV-142"

1つのタスクとそのサブタスクではなく、エピックやストーリーのような大きな構造をモデル化する場合は、1段上の階層を扱う Jira の課題階層: CLI から扱うエピック、ストーリー、サブタスクをお読みください。

タスク同士をリンクする

サブタスクは親子の分解を表します。課題のリンクは対等な関係を表します。このタスクがあのタスクをブロックしている、このバグは別のバグと重複している、このストーリーはスパイクに関連している、といった具合です。リンクは jira issue links create で作成し、リンク元のキー、リンク先のキー、リンクタイプを指定します。

# DEV-142 is blocked by DEV-98
atlassian-cli jira issue links create DEV-142 DEV-98 --link-type "is blocked by"

# DEV-142 relates to a discovery spike
atlassian-cli jira issue links create DEV-142 DEV-150 --link-type "relates to"

リンクタイプの名前は、Jira インスタンスで設定されているものと一致している必要があります。よくある既定値は blocks、is blocked by、relates to、duplicates、is duplicated by、clones、is cloned by です。管理者がリンクタイプの名前を変更したり追加したりしている場合は、その名前をそのまま使ってください。

あとでリンクを外すときは、リンク ID を指定して削除します。

atlassian-cli jira issue links delete 10432

遷移、割り当て、コメント

日々の作業の多くは、タスクをワークフローに沿って進め、関係者に状況を伝えることです。タスクを遷移させるには、遷移先のステップ名を指定します。CLI は、その課題に対して今実際に利用できる遷移に対して名前を解決するため、指定するステップは現在のステータスから見て有効な次の移動先である必要があります。

# Move the task forward
atlassian-cli jira issue transition DEV-142 --transition "In Progress"

# ...and later, when it ships
atlassian-cli jira issue transition DEV-142 --transition "Done"

割り当てと割り当て解除は、それぞれ独立したコマンドです。

atlassian-cli jira issue assign DEV-142 --assignee dev@example.com
atlassian-cli jira issue unassign DEV-142

コメントは jira issue comments の配下にあります。--body で追加でき、同じ Markdown から ADF への変換が適用されるため、リンクやインラインコードを含められます。

atlassian-cli jira issue comments add DEV-142 \
  --body "Blocked until DEV-98 ships the throttle fix. Picking up the tests in the meantime."

# Read the thread back, full bodies
atlassian-cli jira issue comments list DEV-142 --full

担当者にならずにタスクを追いかけたいときは、自分や関係者をウォッチャーとして追加します。

atlassian-cli jira issue watchers add DEV-142 lead@example.com

スコープが変わったときは、jira issue update でフィールドをその場で編集します。変更されるのは渡したフラグの分だけです。

atlassian-cli jira issue update DEV-142 \
  --summary "Add rate-limit retry with jitter to the API client" \
  --priority Highest

日々のタスク管理ワークフロー

これらのコマンドは単体でも便利ですが、つなげれば多くのクリック操作を置き換えられます。次に示すのは、タスクを立ち上げ、2つのサブタスクに分割し、ブロッカーをリンクし、作業開始までを一度に行う小さなスクリプトです。

#!/bin/bash
# Spin up a task with subtasks and a blocker link
set -euo pipefail

PROJECT="DEV"

# 1. Create the parent task and capture its key from JSON output
PARENT=$(atlassian-cli jira issue create \
  --project "$PROJECT" \
  --issue-type Task \
  --summary "Add rate-limit retry to the API client" \
  --assignee dev@example.com \
  --format json | jq -r '.key')

echo "Created $PARENT"

# 2. Add subtasks under it
atlassian-cli jira issue create --project "$PROJECT" --issue-type Sub-task \
  --summary "Write the backoff helper" \
  --field "parent={\"key\":\"$PARENT\"}"

atlassian-cli jira issue create --project "$PROJECT" --issue-type Sub-task \
  --summary "Add unit tests for 429 handling" \
  --field "parent={\"key\":\"$PARENT\"}"

# 3. Record the blocker and start work
atlassian-cli jira issue links create "$PARENT" DEV-98 --link-type "is blocked by"
atlassian-cli jira issue transition "$PARENT" --transition "In Progress"

これをスクリプト化できる決め手は、--format json を jq にパイプすることです。どのコマンドも要求すれば機械可読な出力を返すため、新しい課題キーを受け取って次の手順に渡せます。自分の担当分を随時確認したいときは、JQL クエリで検索し、並べ替えは CLI に任せます。

# My open tasks, most recently updated first
atlassian-cli jira issue search \
  --jql "assignee = currentUser() AND statusCategory != Done ORDER BY updated DESC" \
  --limit 20

これをシェルのエイリアスにしておけば、キー1つで朝会用のレポートが出せます。1件ずつではなく表計算シートから数十件のタスクをまとめて作成したい場合は、CSV から Jira の課題を作成するをご覧ください。

コマンド早見表

タスク管理の全体像を一覧にしました。ここに挙げたのが実際のコマンドです。フラグの詳細はコマンドリファレンスをご覧ください。

同じコマンドを印刷できる早見表としてまとめ、検索と出力の例をさらに加えたものは Jira CLI コマンドチートシートにあります。

よくある質問

関連リソース