atlassian-cli

Atlassian CLI (acli)

概要

Atlassian CLI（acli）を使うと、コマンドラインから Jira、Confluence、その他の Atlassian 製品にアクセスできます。基本原則： 認証を必ず最初に確認し、正しいコマンド構造を使用して、バッチ操作を活用してください。

使用する場面

• Jira 課題の作成、検索、更新
• スプリント、ボード、プロジェクトの管理
• Confluence スペースの操作
• 複数アイテムに対する一括操作
• CSV／JSON 形式でのレポート生成
• Atlassian ワークフローの自動化

使用しない場面：

• Web UI のほうが適切な場合（一度限りの視覚的な操作など）
• API トークン／インテグレーションがすでに利用可能な場合

認証 — 必ず最初に実施

digraph auth_check {
    "User requests acli command" [shape=doublecircle];
    "Check auth status" [shape=box];
    "Authenticated?" [shape=diamond];
    "Run acli command" [shape=box];
    "Explain: acli auth login" [shape=box];

    "User requests acli command" -> "Check auth status";
    "Check auth status" -> "Authenticated?";
    "Authenticated?" -> "Run acli command" [label="yes"];
    "Authenticated?" -> "Explain: acli auth login" [label="no"];
}

acli の操作を行う前に、必ず：

# Check if authenticated
acli auth status

# If not authenticated, login first
acli auth login

コマンド構造

形式： acli <product> <entity> <action> [flags]

--action フラグを使う旧式の構文は使用しないでください。

# ❌ WRONG - old syntax that doesn't work
acli jira --action getIssueList --jql "..."

# ✅ CORRECT - modern syntax
acli jira workitem search --jql "..."

クイックリファレンス

主な製品

• auth - 認証管理
• jira - Jira Cloud コマンド
• confluence - Confluence Cloud コマンド
• admin - 管理者操作

Jira のエンティティとアクション

エンティティ	主なアクション	例
workitem	search、create、create-bulk、edit、view、transition、assign、delete	acli jira workitem search --jql "project = TEAM"
project	list、view、create、update、delete、archive	acli jira project list
sprint	create、update、view、delete、list-workitems	acli jira sprint view 123
board	search、get、create、delete、list-sprints	acli jira board list-sprints --board 42
workitem comment	create、list、update、delete	acli jira workitem comment create --key KEY-1 --comment "text"

Confluence のエンティティ

エンティティ	アクション	例
space	list、view、create、update、archive、restore	acli confluence space list

バッチ操作

JQL、フィルター、またはキーのリストを使って複数のアイテムを操作します：

# Edit multiple issues with JQL
acli jira workitem edit --jql "project = MOBILE AND status = 'In Review'" --assignee "[email protected]" --yes

# Transition multiple issues
acli jira workitem transition --jql "assignee = currentUser() AND status = 'To Do'" --status "In Progress" --yes

# Search with filter
acli jira workitem search --filter 10001 --csv

# Multiple keys
acli jira workitem assign --key "KEY-1,KEY-2,KEY-3" --assignee "@me"

バッチフラグ：

• --jql - 複数アイテム用の JQL クエリ
• --filter - 保存済み検索のフィルター ID
• --key - カンマ区切りの課題キー
• --yes / -y - 確認プロンプトをスキップ
• --ignore-errors - エラーが発生しても続行（一括操作に便利）

出力形式

用途に合った出力形式を選択してください：

# CSV for spreadsheets
acli jira workitem search --jql "sprint = 42" --csv

# JSON for scripts/automation
acli jira workitem search --jql "project = API" --json

# Web browser for viewing
acli jira workitem view KEY-123 --web

# Custom fields (default includes key, summary, status, etc.)
acli jira workitem search --jql "..." --fields "key,summary,assignee,priority"

主なフラグ：

• --csv - CSV 出力（--outputFormat 999 ではありません）
• --json - JSON 出力
• --web - Web ブラウザーで開く
• --fields - 表示するフィールドを指定（--columns ではありません）
• --count - 件数のみを表示
• --paginate - すべての結果を取得

一括作成

類似する課題を複数作成する場合：

# Generate JSON template
acli jira workitem create --generate-json

# Create from JSON file
acli jira workitem create --from-json workitem.json

# Bulk create multiple issues
acli jira workitem create-bulk

# Use file for description
acli jira workitem create --summary "Bug title" --project API --type Bug --from-file description.txt

# Use editor for interactive creation
acli jira workitem create --editor

create-bulk または --from-json が使える場合は、個別の作成コマンドを10個実行する Bash ループを作成しないでください。

よく使う JQL パターン

# Current user's issues
--jql "assignee = currentUser()"

# Specific project and status
--jql "project = TEAM AND status = 'In Progress'"

# Multiple criteria
--jql "project = API AND type = Bug AND status != Done"

# Sprint issues
--jql "project = TEAM AND sprint = 42"

# Recent updates
--jql "project = WEBAPP AND updated >= -7d"

よくある間違い

間違い	問題となる理由	正しい方法
認証確認を省略する	認証なしではコマンドが失敗します	必ず最初に acli auth status を実行する
--action フラグを使う	旧式の構文は現在の acli では動作しません	acli <product> <entity> <action> を使う
--outputFormat 999	フラグが間違っています	--csv を使う
--columns パラメーター	存在しません	--fields を使う
作成に Bash ループを使う	効率が悪く、組み込み機能が用意されています	create-bulk または --from-json を使う
1件ずつ編集する	一括操作には時間がかかります	編集／トランジションで --jql または --filter を使う
コマンドを推測する	時間を浪費します	acli <product> <entity> --help を実行して確認する

危険信号 — 停止してスキルを確認

次の項目は、間違いを犯そうとしている兆候です。

• 認証チェックを省略する
• コマンドで --action を使用する
• 一括操作に Bash のループを書く
• --csv ではなく --outputFormat を提案する
• --fields ではなく --columns を使用する
• --help を確認せずにコマンド名をでっち上げる
• 「古い構文でもおそらくまだ動く」
• 「おそらくすでに認証済みだ」
• 「Bash のループのほうが組み込みコマンドより柔軟だ」

これらに当てはまる場合は、必ず停止し、このスキルを読み直して、正しい構文を使用してください。

ワークフローのパターン

digraph workflow {
    "acli request" [shape=doublecircle];
    "Check auth status" [shape=box];
    "Authenticated?" [shape=diamond];
    "Run acli auth login" [shape=box];
    "Verify command with --help" [shape=box];
    "Check for batch operation?" [shape=diamond];
    "Use --jql/--filter/--key" [shape=box];
    "Single operation" [shape=box];
    "Choose output format" [shape=box];
    "Execute command" [shape=box];

    "acli request" -> "Check auth status";
    "Check auth status" -> "Authenticated?";
    "Authenticated?" -> "Run acli auth login" [label="no"];
    "Run acli auth login" -> "Verify command with --help";
    "Authenticated?" -> "Verify command with --help" [label="yes"];
    "Verify command with --help" -> "Check for batch operation?";
    "Check for batch operation?" -> "Use --jql/--filter/--key" [label="multiple items"];
    "Check for batch operation?" -> "Single operation" [label="single item"];
    "Use --jql/--filter/--key" -> "Choose output format";
    "Single operation" -> "Choose output format";
    "Choose output format" -> "Execute command";
}

ワークフローの例

スプリントレポート

# 1. Check auth
acli auth status

# 2. Search sprint issues with CSV output
acli jira workitem search --jql "project = TEAM AND sprint = 42" --fields "key,summary,status,assignee" --csv > sprint-report.csv

ステータスの一括更新

# 1. Check auth
acli auth status

# 2. Verify issues first
acli jira workitem search --jql "project = MOBILE AND status = 'In Review'" --count

# 3. Transition all
acli jira workitem transition --jql "project = MOBILE AND status = 'In Review'" --status "Done" --yes

# 4. Assign all
acli jira workitem assign --jql "project = MOBILE AND status = Done" --assignee "[email protected]" --yes

複数の課題を作成

# 1. Check auth
acli auth status

# 2. Generate template
acli jira workitem create --generate-json > template.json

# 3. Edit template.json with your data

# 4. Create from template (repeat for each)
acli jira workitem create --from-json issue1.json
acli jira workitem create --from-json issue2.json

# OR use create-bulk
acli jira workitem create-bulk

ヘルプの表示

# Top-level help
acli --help

# Product help
acli jira --help

# Entity help
acli jira workitem --help

# Action help
acli jira workitem search --help

迷った場合は、正確なフラグと構文を --help で確認してください。