コマンドラインから Confluence を管理する

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

ターミナルから Confluence を管理する理由

Confluence は多くの Atlassian チームにとってドキュメントの中心ですが、Web エディターは 1 ページずつ書くことに最適化されており、数百ページをまとめて管理する用途には向いていません。スペース全体をエクスポートする、古いページを棚卸しする、ラベルを一括で付ける、Git リポジトリからドキュメントを同期する、といった場面ではブラウザがボトルネックになります。

Confluence CLI ツールを使えば、これらの操作をスクリプト化できます。CQL（Confluence Query Language）でページを検索し、結果を jq にパイプし、バックアップ用にスペースを JSON へエクスポートし、CI/CD パイプラインから添付ファイルをアップロードし、複数のスペースにまたがる権限を管理する。これらをすべて Web UI をクリックせずに行えます。すでに Jira や Bitbucket で atlassian-cli を使っているなら、Confluence のコマンドも同じ考え方です。プロファイル、出力形式、ドライラン、一括操作がそのまま使えます。

このガイドでは、atlassian-cli で使える Confluence のコマンドをすべて、コピーしてそのまま使える例とあわせて紹介します。コマンドの完全なリファレンスは Confluence CLI のドキュメントをご覧ください。

はじめに

インストール

# Homebrew (macOS / Linux)
brew tap omar16100/atlassian-cli
brew install atlassian-cli

# Cargo (Rust toolchain)
cargo install atlassian-cli

# Verify
atlassian-cli --version

認証

Confluence は Jira と同じ Atlassian の API トークンを使います。id.atlassian.com でトークンを作成し、プロファイルを設定します。

# Add a profile
atlassian-cli auth login \
  --profile work \
  --base-url https://your-domain.atlassian.net \
  --email you@company.com \
  --token $ATLASSIAN_API_TOKEN \
  --default

# Verify
atlassian-cli auth list

認証情報は ~/.atlassian-cli/config.yaml に AES-256-GCM 暗号化で保存されます。同じプロファイルが Jira と Confluence の両方のコマンドで使えるため、別々に設定する必要はありません。

最初のコマンド

# List available Confluence spaces
atlassian-cli confluence space list --limit 10

CQL 検索

CQL（Confluence Query Language）はコンテンツを探すもっとも強力な方法です。confluence search コマンドは、生の CQL クエリ、全文検索、スペース内検索の 3 つのモードに対応しています。

CQL クエリ

スペース、タイプ、ラベル、日付での絞り込みを細かく制御したい場合は、構造化クエリの search cql を使います。

# All pages in a specific space
atlassian-cli confluence search cql \
  --cql "space = DEV and type = page" \
  --limit 5

# Pages with a specific label
atlassian-cli confluence search cql \
  --cql "label = 'api-docs' and type = page"

# Recently updated pages across all spaces
atlassian-cli confluence search cql \
  --cql "type = page and lastModified >= '2026-01-01'" \
  --format json

# Blog posts in a space
atlassian-cli confluence search cql \
  --cql "space = ENG and type = blogpost"

# Pages containing specific text
atlassian-cli confluence search cql \
  --cql "text ~ 'deployment runbook' and space = OPS"

全文検索とスペース内検索

CQL の構文までは必要ない、より単純な検索の場合は次のとおりです。

# Full-text search across all spaces
atlassian-cli confluence search text \
  --query "meeting notes" \
  --limit 10

# Search within a specific space
atlassian-cli confluence search in-space \
  --space DEV \
  --query "api docs"

すべての検索コマンドは、後続の処理に向けて --format json、--format csv、--format yaml に対応しています。

スペース管理

スペースは Confluence の最上位のコンテナです。CLI では CRUD 操作一式に加えて、権限の管理も行えます。

# List all spaces
atlassian-cli confluence space list --limit 10

# Get details for a specific space
atlassian-cli confluence space get DEV

# Create a new space
atlassian-cli confluence space create \
  --key DOCS \
  --name "Documentation" \
  --description "Team docs"

# Update space name
atlassian-cli confluence space update DEV \
  --name "Development Space"

# Delete a space (requires --force for safety)
atlassian-cli confluence space delete OLD --force

権限

誰がスペースにアクセスできるかを、ターミナルから直接確認・管理できます。

# View current permissions
atlassian-cli confluence space permissions DEV

# Grant read access to a user
atlassian-cli confluence space add-permission DEV \
  --principal user@example.com \
  --operation read

ページ操作

ページは Confluence の中心となるコンテンツ単位です。CLI は作成、更新、バージョン管理、ラベル付け、コメント、閲覧制限の管理までカバーします。

CRUD 操作

# List pages in a space
atlassian-cli confluence page list --space DEV --limit 25

# Get a page by ID
atlassian-cli confluence page get 12345

# Create a new page
atlassian-cli confluence page create \
  --space DEV \
  --title "New Page" \
  --body "<p>Page content here</p>"

# Update a page title
atlassian-cli confluence page update 12345 \
  --title "Updated Title"

# Delete a page
atlassian-cli confluence page delete 12345

ラベルとコメント

# Add a label to a page
atlassian-cli confluence page add-label 12345 documentation

# Remove a label
atlassian-cli confluence page remove-label 12345 outdated

# List comments on a page
atlassian-cli confluence page comments 12345

# Add a comment
atlassian-cli confluence page add-comment 12345 \
  "Reviewed and approved."

バージョンと閲覧制限

# View page version history
atlassian-cli confluence page versions 12345

# View page restrictions
atlassian-cli confluence page get-restrictions 12345

# Restrict editing to a specific user
atlassian-cli confluence page add-restriction \
  --operation update \
  --subject-type user \
  --subject-id user@example.com \
  12345

# Remove a restriction
atlassian-cli confluence page remove-restriction \
  --operation update \
  --subject-type user \
  --subject-id user@example.com \
  12345

添付ファイル

任意のページで、添付ファイルのアップロード、ダウンロード、管理ができます。

# List attachments on a page
atlassian-cli confluence attachment list 12345

# Upload a file
atlassian-cli confluence attachment upload \
  --page-id 12345 \
  --file ./diagram.png

# Download an attachment
atlassian-cli confluence attachment download \
  --id 11111 \
  --output ./download.png

# Get attachment metadata
atlassian-cli confluence attachment get 11111

# Delete an attachment
atlassian-cli confluence attachment delete 11111

ブログ記事

Confluence のブログ記事は、ページとまったく同じパターンで扱えます。

# List blog posts
atlassian-cli confluence blog list --space DEV --limit 10

# Create a blog post
atlassian-cli confluence blog create \
  --space DEV \
  --title "Sprint Recap" \
  --body "<p>Summary of sprint work</p>"

# Update a blog post
atlassian-cli confluence blog update 67890 \
  --title "Updated Recap"

# Delete a blog post
atlassian-cli confluence blog delete 67890

一括エクスポートとバックアップ

一括操作は Confluence CLI がもっとも力を発揮する場面です。数百ページのエクスポート、コンテンツへの一括ラベル付け、古いページの削除は、ブラウザで行うと何時間もかかります。CLI なら、並列実行、レート制限への配慮、ドライランでのプレビューを備えた形で処理できます。

一括エクスポート

# Export all pages from a space to JSON
atlassian-cli confluence bulk export \
  --cql "space = DEV" \
  --output backup.json \
  --format json

# Export pages matching a CQL query
atlassian-cli confluence bulk export \
  --cql "space = DOCS AND type = page" \
  --output docs-export.json \
  --format json

ラベルの一括管理

# Preview: add labels to pages matching CQL (dry-run)
atlassian-cli confluence bulk add-labels \
  --cql "space = DEV" \
  --labels docs,reviewed \
  --dry-run

# Execute the label addition
atlassian-cli confluence bulk add-labels \
  --cql "space = DEV" \
  --labels docs,reviewed

一括削除

# Preview: delete all pages in a space (dry-run first!)
atlassian-cli confluence bulk delete --cql "space = OLD" --dry-run

# Execute the deletion
atlassian-cli confluence bulk delete --cql "space = OLD"

バックアップスクリプトの例

Confluence CLI のコマンドとシェルスクリプトを組み合わせれば、夜間バックアップを自動化できます。

#!/bin/bash
# Nightly Confluence backup script
DATE=$(date +%Y-%m-%d)
BACKUP_DIR="./confluence-backups/$DATE"
mkdir -p "$BACKUP_DIR"

# Export each critical space
for SPACE in DEV OPS DOCS ENG; do
  echo "Exporting space: $SPACE"
  atlassian-cli confluence bulk export \
    --cql "space = $SPACE" \
    --output "$BACKUP_DIR/${SPACE}.json" \
    --format json
done

# Export space metadata
atlassian-cli confluence space list \
  --format json > "$BACKUP_DIR/spaces-metadata.json"

echo "Backup complete: $BACKUP_DIR"

Markdown から Confluence へ

多くのチームは Markdown でドキュメントを書き、Git に保存しています。pandoc で Markdown を Confluence のストレージ形式に変換し、CLI で公開できます。これにより、Confluence のページをリポジトリと同期させ続けるドキュメントパイプラインができあがります。

# Convert Markdown to Confluence storage format (XHTML)
pandoc README.md -f markdown -t html -o /tmp/page-body.html

# Read the converted HTML and create a Confluence page
BODY=$(cat /tmp/page-body.html)
atlassian-cli confluence page create \
  --space DOCS \
  --title "Project README" \
  --body "$BODY"

# Or update an existing page
atlassian-cli confluence page update 12345 \
  --title "Project README"

CI/CD では、このパターンを main へのマージのたびに実行し、Confluence のドキュメントをコードベースと自動的に同期させます。同じ方法は、ADR（アーキテクチャ決定記録）やランブックなど、Git 上にあるあらゆるドキュメントの公開にも使えます。

実践的なワークフロー

Git からのドキュメント同期

main へのマージのたびに、Markdown のドキュメントを Confluence へ自動公開します。ATLASSIAN_CLI_TOKEN_DEFAULT、ATLASSIAN_CLI_EMAIL、ATLASSIAN_CLI_BASE_URL をパイプラインの環境変数として設定し、CI のステップで前述の Markdown から Confluence へのパターンを使います。マージのたびに最新のドキュメントが公開されます。

スペースの棚卸し

複数のスペースにまたがって、古くなったページや孤立したページを見つけます。

# Pages not updated in 6 months
atlassian-cli confluence search cql \
  --cql "type = page and lastModified < '2025-09-01'" \
  --format json

# Space-level analytics
atlassian-cli confluence analytics space-stats DEV

# Page view stats for a specific page
atlassian-cli confluence analytics page-views 12345 \
  --from 2025-01-01

スペース間の移行

あるスペースからページをエクスポートし、そのデータを使って別のスペースで作り直します。JSON のエクスポートにはページのタイトル、本文、ラベル、メタデータが含まれており、スペースを再構築するのに必要なものがそろっています。

# Export source space
atlassian-cli confluence bulk export \
  --cql "space = OLD_DOCS" \
  --output migration.json \
  --format json

# Create the target space
atlassian-cli confluence space create \
  --key NEW_DOCS \
  --name "New Documentation" \
  --description "Migrated from OLD_DOCS"