iw-jira-cli

iw-jira-cli は Jira Cloud REST API v3 を操作する CLI ツールです。setup / profile による接続情報管理、課題操作、メンション対応コメント、whoami による接続確認を一貫した CLI フローで提供します。AI エージェント連携向けのコンパクト出力にも対応しています。

Table of contents

• Overview
• Features
• Installation
  • Run with npx
  • Install globally
  • Run from source
• Quick start
• Profiles
• Environment variables
• Authentication check
• Credential precedence
• Usage
  • Show an issue
  • Attachments
  • Search issues
  • Create an issue
  • Update an issue
  • Transition an issue
  • Comments
  • User search
  • Project list
• Output format
• Formatting support
• Mention syntax
• Development
• License

Overview

iw-jira-cli は Jira 課題の取得、検索、更新、コメント、ステータス遷移を行うための CLI です。初回は iw-jira-cli setup で資格情報を保存し、その後は issue / project / user / whoami をそのまま使えます。

Features

• 課題の取得・検索（JQL 対応）・作成・更新
• 添付ファイル一覧の取得 / メタデータ取得 / ダウンロード（attachment get / attachment download）
• show / issue get の --full（description を切り詰めない）/ --rendered（HTML レンダリング済み description 付き）
• ステータス遷移（issue transitions / issue transition）
• コメントの取得・追加
• ユーザー検索（メンション用 accountId の確認）
• プロジェクト一覧
• setup / profile による接続情報管理
• 認証ユーザー情報の取得（whoami, myself）
• メンション記法: @[accountId] または @[email:[email protected]]
• 説明・コメントの Markdown 入出力（書き込み時は ADF に、読み出し時は Markdown にラウンドトリップ）
• パイプ・非 TTY 時の自動コンパクト出力（JIRA_CLI_COMPACT で制御可能）

Installation

Run with npx

npx @niiiiiiile/iw-jira-cli@latest

Install globally

npm install -g @niiiiiiile/iw-jira-cli

Run from source

git clone https://github.com/Niiiiile/jira-cli.git
cd iw-jira-cli
npm install
npm run build

Quick start

iw-jira-cli setup \
  --host your-company.atlassian.net \
  --email [email protected] \
  --api-token your-api-token-here

初回登録時は default プロファイルに保存され、自動でデフォルトになります。

API トークンは Atlassian アカウント設定 から発行できます。

Profiles

# work プロファイルを追加
iw-jira-cli profile add work \
  --host your-company.atlassian.net \
  --email [email protected] \
  --api-token your-api-token-here

# プロファイル一覧
iw-jira-cli profile list

# デフォルト切り替え
iw-jira-cli profile use work

Environment variables

.env.example をコピーして .env を作成し、各値を設定してください。

cp .env.example .env

JIRA_HOST=your-company.atlassian.net
[email protected]
JIRA_API_TOKEN=your-api-token-here

環境変数はシェルに直接設定することも可能です:

export JIRA_HOST=your-company.atlassian.net
export [email protected]
export JIRA_API_TOKEN=your-api-token-here

Authentication check

iw-jira-cli whoami

既存の iw-jira-cli myself も引き続き利用できます。

Credential precedence

1. コマンドフラグ（--host, --email, --api-token）
2. 設定ファイルのプロファイル（--profile または default）
3. 環境変数 / .env（JIRA_HOST, JIRA_EMAIL, JIRA_API_TOKEN）

Usage

npx @niiiiiiile/iw-jira-cli@latest --help

Show an issue

# キーで取得（show は issue get の短縮）
npx @niiiiiiile/iw-jira-cli@latest show PROJECT-123

# URL でも指定可
npx @niiiiiiile/iw-jira-cli@latest show https://your-company.atlassian.net/browse/PROJECT-123

# コンパクト出力時も description を切り詰めない
iw-jira-cli show PROJECT-123 --full

# 添付 + HTML レンダリング済み description も取得
iw-jira-cli show PROJECT-123 --full --rendered

グローバルインストール済みの場合は iw-jira-cli コマンドとして呼び出せます。

出力には常に添付ファイル一覧（attachments[]）が含まれます（id/name/size/mime/url など）。 --rendered を付けると Jira の expand=renderedFields が有効になり、 HTML にレンダリング済みの説明文が renderedDescription として追加されます。

Attachments

添付ファイルのメタデータ取得・ダウンロード:

# メタデータ取得
iw-jira-cli attachment get 24486

# テキスト系（markdown / text / json / yaml / ...）は標準出力へ
iw-jira-cli attachment download 24486 > report.md

# 明示的に標準出力
iw-jira-cli attachment download 24486 --out -

# ファイルに保存（バイナリはこちら必須）
iw-jira-cli attachment download 24486 --out ./downloads/
iw-jira-cli attachment download 24486 --out ./report.md --force

ディレクトリを --out に指定すると、サーバー側の Content-Disposition から ファイル名を推測して保存します。既存ファイルの上書きは --force が必要です。

Search issues

# 自分にアサインされた未解決の課題（デフォルト）
iw-jira-cli issue search

# プロジェクトを指定
iw-jira-cli issue search PROJECT

# JQL で検索
iw-jira-cli issue search --jql "project = PROJECT AND status = 'In Progress'"

# 件数を指定
iw-jira-cli issue search PROJECT --limit 50

Create an issue

iw-jira-cli issue create \
  --project PROJECT \
  --summary "バグ修正: ログイン画面のエラー" \
  --type Bug \
  --description "再現手順: ..." \
  --assignee email:[email protected]

Update an issue

iw-jira-cli issue update PROJECT-123 \
  --summary "新しいタイトル" \
  --assignee email:[email protected] \
  --due-date 2026-04-30

Transition an issue

# 利用可能な遷移を確認
iw-jira-cli issue transitions PROJECT-123

# 遷移名で変更（部分一致）
iw-jira-cli issue transition PROJECT-123 --name "In Progress"

# 遷移 ID で変更
iw-jira-cli issue transition PROJECT-123 --id 21

Comments

# コメント一覧
iw-jira-cli issue comments PROJECT-123

# コメントを追加（メンション可）
iw-jira-cli issue comment PROJECT-123 --body "確認しました @[email:[email protected]]"

User search

# メンション用 accountId を確認
iw-jira-cli user search "田中"

Project list

iw-jira-cli project list
iw-jira-cli project list --query "my project"

Output format

デフォルトは TOON 形式（人間向け）。NDJSON に切り替えるには --format jsonl を指定します。

jira-cli issue search PROJECT --format jsonl

コンパクト出力

パイプや非 TTY 環境では自動的にコンパクト出力になります（AI エージェント向けのトークン削減）。

# 強制的にコンパクト出力
JIRA_CLI_COMPACT=1 iw-jira-cli issue search PROJECT

# 強制的にフル出力
JIRA_CLI_COMPACT=0 iw-jira-cli issue search PROJECT

Formatting support

issue create / issue update の --description は Markdown として解釈され、Jira の ADF（Atlassian Document Format）に変換されて投稿されます。issue get / show / issue comments で取得した description / コメントは ADF から Markdown に変換して出力します。

issue comment の --body は Jira Wiki Renderer 記法をそのまま投稿します。Markdown 変換は行いません。Jira の Wiki Renderer Help にある表、パネル、コードブロック、noformat、color、リンク、画像、添付、引用、リストなどの記法をそのまま使用できます。

代表的な Jira Wiki Renderer 記法:

| 用途 | Jira Wiki Renderer 記法 | |------|--------------------------| | 見出し | h2. Heading | | 太字 / 斜体 | *bold*, _italic_ | | 行内コード | {{code}} | | コードブロック | {code:js} ... {code} | | noformat | {noformat} ... {noformat} | | パネル | {panel:title=Title} ... {panel} | | 色 | {color:red} ... {color} | | 表 | ||heading 1||heading 2|| / |cell 1|cell 2| | | リンク | [text|https://example.com] | | 画像 | !attached-image.png! / !https://example.com/image.png! | | メンション | @[accountId] / @[email:[email protected]]（投稿時に [~accountid:...] へ解決） |

iw-jira-cli issue comment PROJECT-123 --body "$(cat <<'EOF'
h2. 調査結果

{panel:title=影響範囲}
* 対象: {{UserController}}
* 参照: [PR #42|https://github.com/org/repo/pull/42]
{panel}

||項目||結果||
|テスト|成功|
|確認者|@[email:[email protected]]|

{code:bash}
php artisan test --filter UserControllerTest
{code}
EOF
)"

Mention syntax

説明文・コメントで以下の記法でメンションを指定できます。

| 記法 | 説明 | |------|------| | @[712020:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx] | accountId で直接指定 | | @[email:[email protected]] | メールアドレスで指定（内部で accountId に解決） |

accountId は iw-jira-cli user search <名前> で確認できます。

Development

# 依存関係のインストール
npm install

# TypeScript のビルド
npm run build

# ビルドなしで直接実行（開発時）
npm run dev -- issue search

ライセンス

MIT