jira-axi

jira-axi

Atlassian の acli を基盤とする、エージェントに使いやすい Jira CLI です。トークン効率に優れた TOON 出力と、自己完結型の認証（追加の認証情報設定は不要）を備えています。

jira-axi をインストールする必要はありません。デフォルトの方法である npx -y jira-axi@latest <command> を使って実行してください。 @latest を指定することで、常に公開済みの最新バージョンを実行できます。 jira-axi の出力に jira-axi で始まる後続のコマンドが表示された場合は、代わりに npx -y jira-axi@latest ... として実行してください。すでに PATH 上で jira-axi が解決される場合は、そのまま実行します。

グローバルインストール（npm i -g jira-axi）は、エージェントの SessionStart フック機能を使う場合の SECONDARY オプションです。setup hooks にはグローバルインストールが必要です。 フックが各セッションに追加する内容：acli: installed（必要な acli の前提条件がそろっているかどうか）、my_open_workitems[N]{key,summary,status}（自分の未完了作業項目）、および利用可能なコマンドを示す help[N] 行。 以下のコマンドは、どちらの方法でも同じように動作します。

使用する場面

作業項目の表示、作成、編集、チケットの別ステータスへの遷移、担当者の割り当てや再割り当て、コメントの読み取りや追加、JQL による検索またはプロジェクト・担当者・ステータスによる絞り込み、プロジェクトの一覧表示や確認、ボード・スプリント・プロジェクトの操作、スプリントの作成・更新・終了、保存済みフィルターの一覧表示や更新、ダッシュボードの一覧表示、カスタムフィールドの作成・更新・削除・復元など、Jira に関わるタスクには必ず jira-axi を使用してください。

ステータス

ダッシュボード、acli を基盤とする Jira コマンド（workitem、project、board、sprint、filter、dashboard、field）、setup hooks、および継承された update コマンドは、現在利用できます。 jira-axi は Atlassian の acli をシェルから呼び出します。まずインストールし（brew install acli）、acli jira auth login でログインしてください。 認証情報の設定は別途必要ありません。認証はすべて acli 自身のログインに委任されます。

コマンド

commands[9]:
  (none)=dashboard, workitem, project, board, sprint, filter, dashboard, field, setup
workitem:
  list, view <KEY> [--fields <a,b,c>], create, edit <KEY>, transition <KEY> --to <status>, assign <KEY> --assignee <user>, comment <KEY> --body <text>, search "<JQL>"
project:
  list, view <KEY>
board:
  list, view <ID>, list-sprints <ID>, list-projects <ID>
sprint:
  view <ID>, list-workitems <ID> --board <ID>, create --board <ID> --name <text>, update <ID>
filter:
  list, search, view <ID>, update <ID>
dashboard:
  list
field:
  create --name <text> --type <key>, update <ID>, delete <ID>, restore <ID>

グローバルフラグは jira-axi --help、コマンドごとの使い方は jira-axi <command> --help を実行して確認してください。 jira-axi setup hooks を実行すると、セッション開始時のアンビエントコンテキストをインストールできます（グローバルインストールが必要です）。

ヒント

• フラグはコマンドの後に指定します。jira-axi workitem list --project TEAM のように指定し、コマンドの前には置かないでください。
• 出力は TOON 形式でエンコードされ、トークン効率に優れています。
• 変更操作は冪等で、何が変更されたかを報告します。失敗した変更操作を再実行しても安全です（現在のステータスへの transition は何も変更せず成功します）。
• filter list に表示されるのはアカウントが所有するフィルターのみです。そのため、count: 0 でもフィルターが存在しないとは限りません。残りのフィルターを確認するには、filter list --favourite または filter search --name <substring> を使用してください。
• view <KEY> --full は本文全体を表示します。--comments を付けるとコメントが含まれます（件数行には実際の合計が表示されます。表示する行数は --limit <n> で増やせます）。--fields <a,b,c> を指定すると、それらのフィールドだけが表示されます（list/search/view で利用できます）。
• 長い自由記述テキストはサイズ表示付きで省略されます。--full を指定すると全文を表示できます。対象は workitem view の本文・コメント、filter view と project view の説明です。
• workitem list は --project/--assignee/--status から JQL を組み立てます。生の JQL を使う場合は --jql を指定するか、search を使用してください。
• workitem create/edit --body と comment --body では Markdown（見出し、リスト、インラインコード／ブロックコード、太字／斜体、リンク）を受け付け、Jira ADF として保存します。生の ADF JSON は変更せずに渡されます。
• ボード／スプリント／フィルターは ID で指定します。ボード ID は board list、スプリント ID は board list-sprints <BOARD_ID> で確認してください。
• sprint list-workitems には、スプリント ID と --board の両方が必要です（Jira Agile API の要件です）。
• sprint update <ID> --state closed でスプリントを終了できます（すでに終了している場合は何も変更せず成功します）。acli にはフィールドの list/view コマンドがないため、field で扱えるのはカスタムフィールドの作成／更新／削除／復元のみです。