コマンドラインから CQL で Confluence を検索する

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

Confluence CQL とは

Confluence CQL（Confluence Query Language）は、正確なメタデータでコンテンツを探すための構造化された検索構文です。どのスペースにあるか、ページかブログ記事か、ラベル、作成者、最終更新日、本文に含まれる語などで指定できます。Confluence の高度な検索の裏側にあるのと同じ言語で、Confluence Cloud の検索 REST エンドポイントは CQL 文字列をそのまま受け取ります。この最後の点が、ターミナルから使うときに効いてきます。入力したクエリはそのまま API に渡され、自動化に使えるきれいに絞り込まれた結果が返ります。

atlassian-cli なら、1 つのコマンドで CQL クエリを実行し、結果を表、JSON、CSV、YAML、markdown として受け取れます。高度な検索の UI をクリックして回る必要も、ページ ID を手でコピーする必要もありません。この記事では、実際に使う CQL の構文、コマンドラインでの検索と絞り込みの方法、そして出力をエクスポートしたりほかのツールにつないだりする方法を扱います。

atlassian-cli はコミュニティによる独立したオープンソースプロジェクトです。Atlassian と提携・関連しておらず、Atlassian による承認、推奨、後援、保守のいずれも受けておらず、Atlassian が提供する公式 CLI（acli）でもありません。ベンダーによる一次サポートが必要な場合は acli を使ってください。Jira、Confluence、Bitbucket、JSM を横断し、CQL 検索を内蔵した無料の単一 Rust バイナリが欲しい場合は atlassian-cli を使ってください。

CQL 検索を実行する

中心となるコマンドは confluence search cql です。CQL 文字列を引用符で囲んで渡し、必要に応じて --limit を指定します。

# Every page in the ENG space labeled "runbook"
atlassian-cli confluence search cql "space = ENG and type = page and label = runbook" --limit 25

既定では結果が読みやすい表として出力されます。CQL は Confluence の検索 API にそのまま渡されるため、Confluence の高度な検索ボックスで有効なものはここでも有効です。すでに CQL を知っているなら、このコマンドも知っているのと同じです。

よくあるケース向けに、毎回フルの CQL を書かずに済む便利なラッパーも 2 つ用意されています。

# Full-text keyword search (relevance ranked)
atlassian-cli confluence search text "meeting notes" --limit 10

# Keyword search scoped to a single space
atlassian-cli confluence search in-space DEV "api docs"

キーワードを探していて、一致度の高いものから並べたいときは search text を使います。正確さが必要なときは search cql です。スクリプトやレポート、一括操作にそのまま渡せる、厳密で再現性のある絞り込み済みのコンテンツ集合が得られます。

CQL のフィールドと演算子

CQL の文は素直な節の形です。field operator value を AND、OR、NOT でつなぎます。キーワードは大文字小文字を区別せず、空白を含む文字列の値は引用符で囲みます。以下の表は、最もよく使うフィールドをまとめたものです。

演算子も同じくらい少数です。= と != は完全一致と不一致、~ と !~ は部分一致と部分不一致、>、>=、<、<= は日付の比較、IN (a, b, c) はリスト内のいずれかの値との一致を表します。CQL にはクエリ実行時に評価される関数もあり、保存したクエリを陳腐化させずに済みます。覚えておく価値があるのは currentUser()、now("-7d")、startOfMonth()、favouriteSpaces() です。並べ替えるには order by lastModified desc を末尾に付けます。

絞り込みのレシピ

ここからは、実際の棚卸しやレポート作業に対応するクエリです。いずれもそのままコピーして使える完全なコマンドです。

自分が作成したスペース内のページを、新しい順にすべて探します。

atlassian-cli confluence search cql \
  "space = DOCS and type = page and creator = currentUser() order by created desc"

古くなったコンテンツを洗い出します。1 年以上更新されていないスペース内のページで、見直しやアーカイブの有力な候補です。

atlassian-cli confluence search cql \
  "space = KB and type = page and lastModified <= now(\"-365d\")" \
  --limit 100

ラベルでの絞り込みとキーワード一致を組み合わせて、話題ごとの部分集合を取り出します。

atlassian-cli confluence search cql \
  "label = incident and text ~ \"database\" and lastModified >= now(\"-90d\")"

IN で複数のスペースをまとめて検索し、ブログ記事を除外します。

atlassian-cli confluence search cql \
  "space IN (ENG, DOCS, KB) and type = page and title ~ \"architecture\""

特定の親ページの配下にあるものをすべて一覧表示します。構造を事前に知らなくてもドキュメントのツリーを棚卸しできます。

atlassian-cli confluence search cql "ancestor = 3302031761 and type = page" --limit 200

注意点が 2 つあります。シェルの二重引用符で囲んだ文字列の中では、CQL に必要な内側の引用符をエスケープするか（\"database\"）、クエリ全体を単一引用符で囲んでください。また --limit は返される結果の件数を制限するので、大量にヒットしそうなときは値を大きくしてください。

結果のエクスポートとパイプ

CQL の検索は仕事の半分にすぎません。もう半分は結果を使って何をするかです。どの検索コマンドもグローバルな --format フラグに従うため、クエリを変えずに人が読む表から機械可読な出力へ切り替えられます。

# JSON for scripting: pipe to jq to pull just the titles
atlassian-cli confluence search cql "space = DOCS and type = page" \
  --format json | jq '.[].title'

# CSV redirected to a file for a spreadsheet
atlassian-cli confluence search cql "space = DOCS and label = reviewed" \
  --format csv > reviewed-pages.csv

# Markdown, ready to paste into a report or another page
atlassian-cli confluence search cql "space = KB and lastModified >= now(\"-7d\")" \
  --format markdown

使える形式は table（既定）、json、csv、yaml、markdown、quiet です。自動化の主役は JSON です。jq にパイプすれば、件数を数えたり、ID を抽出したり、データを整形し直したりできます。CQL 検索をページ ID のリストに変え、後続のコマンドがそれを処理する、というのがよくあるパターンです。

# Count how many stale pages a query matches
atlassian-cli confluence search cql \
  "space = KB and type = page and lastModified <= now(\"-365d\")" \
  --format json | jq 'length'

結果の一覧ではなくページの本文全体が欲しい場合、それは検索ではなくエクスポートです。次に扱う confluence bulk export を使ってください。

CQL を一括操作に渡す

検索に使うのと同じ CQL が、一括コマンドも動かします。CQL の真価が出るのはここです。正確なクエリを一度書き、内容を確認してから、一致するすべてのページに操作を適用します。一括コマンドは --cql を受け付け、atlassian-cli のすべての破壊的操作と同様に --dry-run に対応しているので、実行前に影響範囲を確認できます。

# Preview which pages a query matches before touching anything
atlassian-cli confluence bulk add-labels \
  --cql "space = DEV and title ~ \"draft\"" \
  --labels needs-review \
  --dry-run

# Export the full content of everything a query matches
atlassian-cli confluence bulk export \
  --cql "space = DEV and type = page" \
  --output dev-pages.json \
  --format json

# Clean up an archived space (preview first, always)
atlassian-cli confluence bulk delete --cql "space = OLD" --dry-run

手順は一貫しています。CQL を書き、search cql で一致するものを目視し、同じクエリを --dry-run 付きで一括コマンドに渡し、件数とサンプルが問題なければフラグを外します。このパターンにもとづく実運用レベルのクリーンアップ手順は、Confluence 一括クリーンアップランブックをご覧ください。

acli との違い

Atlassian は自社の公式 CLI として acli を提供しており、ベンダーによる一次サポートが必要ならそちらが適切です。atlassian-cli はそれとは別の、独立した MIT ライセンスのコミュニティプロジェクトです。Atlassian と提携・関連しておらず、Atlassian による承認、推奨、後援、保守のいずれも受けていません。魅力はひとつのバイナリで広くカバーできることです。Confluence の CQL 検索を実行するのと同じツールが、Jira の課題、Bitbucket のリポジトリ、Jira Service Management のリクエストも扱い、--format と --profile のフラグはどのコマンドでも共通です。

作業の大半が Confluence のコンテンツ管理なら、まず幅広いコマンドを扱う Confluence CLI ガイドを、正確なフラグはコマンドリファレンスをご覧ください。CQL 検索を超えて生のエンドポイントを扱いたい場合は、対になる記事の CLI から Confluence API を呼び出すが API を直接スクリプト化する方法を、スペースのエクスポートとバックアップの記事がスペース全体のアーカイブ方法を解説しています。

よくある質問

関連リソース