Jira Service Management のナレッジベースを CLI で自動化する

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

Jira Service Management のナレッジベースにあるもの

Jira Service Management のナレッジベースは、顧客がポータルで読み、エージェントがリクエストへの返信に貼り付けるセルフサービス記事のライブラリです。記事そのものは Jira の中には保存されません。サービスプロジェクトにリンクされた Confluence スペースのページとして存在し、そのリンク先のスペースには同じサイト上に Confluence 製品が必要です。この構造上の事実こそが、コマンドラインからの自動化を可能にしています。KB 記事はすべて通常の Confluence ページなので、atlassian-cli は他のスペースと同じ confluence コマンドで作成、検索、ラベル付け、監査、エクスポートができ、ポータル側の検索には専用の jsm kb search が使えます。

その結果、KB のメンテナンスは 2 つのタブを行き来する作業ではなくなります。JSM のポータルと Confluence のエディターを往復する代わりに、1 つのバイナリを実行するだけです。面倒な部分（ラベルの付け替え、古い記事の洗い出し、バックアップ）はスクリプト化でき、執筆はチームがすでに Git でレビューしているファイルのまま進められます。

acli との違い

atlassian-cli はコミュニティによる独立したオープンソースプロジェクトです。Atlassian が提供する公式 CLI（acli）ではなく、Atlassian と提携・関連しておらず、Atlassian による承認、推奨、後援、保守のいずれも受けていません。ベンダーによる一次サポートが必要な場合は公式の acli を使ってください。Jira、Confluence、Bitbucket、JSM を 1 つのコマンド体系でカバーする無料の Rust バイナリが欲しい場合は atlassian-cli を使ってください。以下はすべて、そのままコピーして使える atlassian-cli の構文です。サブコマンドとフラグの一覧が必要なら、コマンドリファレンスを別のタブで開いておいてください。

コマンドに入る前に 1 点だけ補足します。認証は最初にプロファイルを作って一度だけ行い、あとは使い回します。ここでの例は既定のプロファイルを前提としています。特定のサイトを対象にする場合は --profile <name> を付けてください。認証の手順は JSM CLI ガイドで最初から最後まで解説しています。

ナレッジベースを検索する

ポータル向けの検索は、JSM に固有の唯一のコマンドです。指定したサービスデスクにリンクされたナレッジベースを検索し、一致する記事を返します。顧客がヘルプセンターで入力を始めたときに見えるものとまったく同じです。まず、サービスデスクの数値 ID を調べます。

# List service desks to get the numeric id
atlassian-cli jsm service-desk list --limit 25

続いて、そのデスクのナレッジベースをキーワードで検索します。

# Search the KB linked to service desk 10
atlassian-cli jsm kb search \
  --query "vpn" \
  --servicedesk-id 10 \
  --limit 25

エージェントが新しい返信を書き始める前に「この件の記事はもうあるか」を確かめる最速の方法であり、新しいページを公開した直後の確認にも向いています。想定される検索語で記事が出てこないなら、タイトルか文言に手を入れる必要があります。結果の一覧を別のスクリプトに渡したいときは、JSON にパイプします。

# Machine-readable output for scripting
atlassian-cli jsm kb search \
  --query "password reset" \
  --servicedesk-id 10 \
  --format json | jq '.[].title'

Confluence ページとして記事を書く

「kb article create」のような専用のコマンドはありませんし、必要もありません。KB 記事は、リンクされたスペースにある Confluence のページだからです。執筆には confluence page のコマンドを使います。まず、ナレッジベースを支えているスペースキーを調べます。

# Find the Confluence space that backs the KB
atlassian-cli confluence space list --limit 25

そのスペースに新しい記事を作成します。本文は Confluence のストレージ形式（HTML に似た形式）なので、単純なマークアップはそのまま渡せます。

# Create a KB article in the KB space (key: HELP)
atlassian-cli confluence page create \
  --space HELP \
  --title "How to reset your VPN password" \
  --body "<p>Follow these steps to reset access.</p>"

ナレッジベースを見つけやすくするのは分類であり、Confluence ではそれがラベルにあたります。ポータルと検索で正しくグループ化されるように、記事にタグを付けます。

# Label the article (page id from the create output)
atlassian-cli confluence page add-label 45678 vpn
atlassian-cli confluence page add-label 45678 self-service

# Update the article later
atlassian-cli confluence page update 45678 \
  --title "How to reset your VPN password (2026)"

# Check the edit history
atlassian-cli confluence page versions 45678

これらは通常のページなので、残りの道具立てもそのまま使えます。レビュアーのフィードバックを読むには confluence page comments、編集できる相手を確認するには confluence page get-restrictions、現在の内容をファイルに取り出して編集するには confluence page get 45678 を使います。

docs-as-code: Markdown を取り込む

多くのチームは、ヘルプ記事をブラウザーで編集するよりも、Markdown で書き、プルリクエストでレビューし、マージ時に公開したいと考えます。KB 記事は Confluence のページにすぎないので、その docs-as-code のワークフローがそのまま当てはまります。Markdown で執筆し、Confluence のストレージ形式に変換して送り込みます。仕組みは Confluence での docs-as-code ガイドで詳しく解説しており、往復のパイプライン全体は Markdown 同期のランブックにあります。

逆方向も、レビューとバックアップに同じくらい役立ちます。既存の記事を Markdown として取り出せば、書き手が差分を確認でき、バージョン管理に保管もできます。この流れは Confluence から Markdown へのエクスポートをご覧ください。内容がファイルとして存在するようになれば、KB はブラックボックスではなくなり、コードベースの他の部分と同じように扱えます。

古い記事の監査と整理

ナレッジベースは劣化します。記事は古くなり、重複が積み上がり、顧客が古い手順に従うまで誰も気づきません。CLI は、この監査をクエリに変えます。CQL を使えば、1 年間更新されていない記事や、分類体系で必要なラベルが付いていないページを探せます。

# Articles in the KB space not updated in the last year
atlassian-cli confluence search cql \
  "space = HELP and type = page and lastmodified < now('-365d')" \
  --limit 50

# Find pages missing a required label
atlassian-cli confluence search in-space HELP "vpn"

利用データを見れば、更新する価値のある記事と、そうでない記事が分かります。特定の記事の閲覧数や、スペース全体の統計を取得します。

# How many people actually read this article?
atlassian-cli confluence analytics page-views 45678 --from 2026-01-01

# Space-level activity for the whole KB
atlassian-cli confluence analytics space-stats HELP

実際に整理すると決めたら、一括コマンドで多数の記事をまとめて処理できます。どのコマンドも --dry-run に対応しているため、何かが変わる前に、どのページが影響を受けるかを正確に確認できます。削除の前には必ずバックアップを取ってください。

# 1. Back up the entire KB space first
atlassian-cli confluence bulk export \
  --cql "space = HELP" \
  --output kb-backup.json \
  --format json

# 2. Preview a relabel across the space
atlassian-cli confluence bulk add-labels \
  --cql "space = HELP" \
  --labels reviewed,2026 \
  --dry-run

# 3. Preview removal of clearly dead drafts
atlassian-cli confluence bulk delete \
  --cql "space = HELP and title ~ 'DRAFT'" \
  --dry-run

--dry-run を外すのは、プレビューの内容が意図どおりだと確認できてからにしてください。同じ安全第一のパターンは Jira の一括操作でも使っており、稼働中のナレッジベースをスクリプトから扱うときに最も重要な習慣です。

週次の KB メンテナンススクリプト

ここまでの要素をつなげた小さなスクリプトを紹介します。定期実行すれば、ナレッジベースを健全に保てます。バックアップを取り、レビュー対象の古い記事を洗い出し、顧客が実際に検索しているのに何も返らない語を表示します。

#!/bin/bash
# Weekly JSM knowledge base health check
set -euo pipefail

SPACE="HELP"        # Confluence space backing the KB
DESK="10"           # JSM service desk id
DATE=$(date +%F)

# 1. Snapshot the whole KB for safekeeping
atlassian-cli confluence bulk export \
  --cql "space = $SPACE" \
  --output "kb-$DATE.json" \
  --format json

# 2. List articles not updated in a year (review candidates)
atlassian-cli confluence search cql \
  "space = $SPACE and type = page and lastmodified < now('-365d')" \
  --format csv > "kb-stale-$DATE.csv"

# 3. Sanity-check common portal searches resolve to something
for term in "vpn" "password" "onboarding"; do
  hits=$(atlassian-cli jsm kb search --query "$term" \
    --servicedesk-id "$DESK" --format json | jq 'length')
  echo "$term -> $hits articles"
done

echo "KB health check complete: kb-$DATE.json"

ここには、あなたの指示なしに稼働中の記事へ触れる処理はありません。バックアップし、レポートし、顧客が探しているものとナレッジベースが答えられるものとのギャップを可視化します。そのギャップの一覧は、サービスチームにとって最も価値のあるものです。優先順位の付いた執筆バックログが自動で手に入るからです。

よくある質問

関連リソース