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
  • Search issues
  • Create an issue
  • Update an issue
  • Transition an issue
  • Comments
  • User search
  • Project list
• Output format
• Markdown support
• Mention syntax
• Development
• License

Overview

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

Features

• 課題の取得・検索（JQL 対応）・作成・更新
• ステータス遷移（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

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

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

Markdown support

issue create / issue update の --description、issue comment の --body は Markdown として解釈され、Jira の ADF（Atlassian Document Format）に変換されて投稿されます。issue get / show / issue comments で取得した description / コメントは逆に ADF から Markdown に変換されて出力されるため、Jira Web UI とターミナル双方で書式が保たれます。

対応している記法:

| 記法 | 例 | |------|------| | 見出し | # H1, ## H2, ... ###### H6 | | 太字 / 斜体 | **bold**, *italic*, __bold__, _italic_ | | 取り消し線 | ~~strike~~ | | 行内コード | `code` | | コードブロック | ```ts ... ``` | | 箇条書き | - item / * item | | 番号付きリスト | 1. item | | チェックリスト | - [ ] todo / - [x] done | | 引用 | > quote | | 水平線 | --- / *** / ___ | | リンク | [text](https://example.com) | | 画像 | ![alt](https://example.com/img.png)（リンクとして挿入） | | メンション | @[accountId] / @[email:[email protected]] |

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

- **影響範囲**: `UserController`
- 修正方針は [PR #42](https://github.com/org/repo/pull/42) を参照
- @[email:[email protected]] レビューお願いします

```bash
php artisan test --filter UserControllerTest

EOF )"

## Mention syntax

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

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

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

## Development

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

# TypeScript のビルド
npm run build

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

ライセンス

MIT