confluence-cli

Confluence CLI（NPM パッケージ）

概要

confluence-cli は、ターミナルから直接コンテンツを管理できる、コミュニティ開発の Atlassian Confluence 用コマンドラインインターフェースです。これは NPM から入手できるサードパーティ製ツールであり、Atlassian 公式のツールではありません。

次の場合にこのスキルを使用してください：

• ユーザーが CLI ベースの Confluence 操作を依頼している
• ドキュメント作成のワークフローを自動化する必要がある
• ページの一括操作が必要である
• スペース間でコンテンツを移行する必要がある
• ユーザーがドキュメントの更新をスクリプト化したい

重要：これは Confluence をサポートしていない、Atlassian 公式 CLI（acli）ではありません。コミュニティ製のツールです：https://github.com/pchuri/confluence-cli

インストール

前提条件

• Node.js と NPM がインストールされていること

インストール方法

# Global installation (recommended for frequent use)
npm install -g confluence-cli

# Or use directly with npx (no installation)
npx confluence-cli --help

設定

対話型セットアップ（推奨）

# Launch configuration wizard
confluence init

ウィザードに沿って、次の項目を設定できます：

1. Confluence インスタンスの種類（Cloud またはセルフホスト）を選択する
2. 適切な API エンドポイントを選択する
3. 認証を設定する

環境変数

または、環境変数を使用して設定できます：

export CONFLUENCE_DOMAIN="yourcompany.atlassian.net"
export CONFLUENCE_EMAIL="[email protected]"
export CONFLUENCE_API_TOKEN="your-api-token"
export CONFLUENCE_API_PATH="/wiki/rest/api"  # Cloud default
export CONFLUENCE_AUTH_TYPE="basic"  # or "bearer"

API パスのデフォルト値：

• Cloud：/wiki/rest/api
• セルフホスト／Data Center：/rest/api

認証

API トークンの取得

1. https://id.atlassian.com/manage-profile/security/api-tokens にアクセスします
2. 「Create API token」をクリックします
3. トークンにラベルを付けます（例：「confluence-cli」）
4. 生成されたトークンをコピーします

認証方式

Basic Auth（Cloud - デフォルト）

• 必要なもの：メールアドレス＋API トークン
• CONFLUENCE_EMAIL が設定されている場合に自動的に使用されます

Bearer Token（セルフホスト／Data Center）

• 必要なもの：Bearer トークンのみ
• CONFLUENCE_AUTH_TYPE="bearer" を設定します

主なコマンド

1. ページの読み取り

さまざまな形式でページのコンテンツを取得します：

# Read as text (default)
confluence read 123456789

# Read as HTML
confluence read 123456789 --format html

# Read as Markdown
confluence read 123456789 --format markdown

# Using page URL instead of ID
confluence read "https://yourcompany.atlassian.net/wiki/spaces/SPACE/pages/123456789"

形式：

• text - プレーンテキスト（デフォルト）
• html - HTML 形式
• markdown - Markdown 形式（ドキュメント作成のワークフローに便利）

2. ページ情報の取得

ページのメタデータを表示します：

# Get page metadata
confluence info 123456789

# Using URL
confluence info "https://yourcompany.atlassian.net/wiki/spaces/SPACE/pages/123456789"

返される情報：ページ ID、タイトル、スペース、バージョン、作成日／更新日、作成者など。

3. コンテンツの検索

Confluence Query Language（CQL）を使用してページを検索します：

# Basic search
confluence search "API documentation"

# Search with result limit
confluence search "meeting notes" --limit 10

# Complex CQL queries
confluence search "type=page AND space=DEV AND title~'API'"

よく使う CQL パターン：

• type=page - ページのみ（添付ファイルは除外）
• space=SPACEKEY - 指定したスペース内
• title~'keyword' - タイトルにキーワードを含む
• text~'keyword' - コンテンツにキーワードを含む
• created >= now()-7d - 過去 7 日間に作成

4. スペースの一覧表示

アクセス可能なすべてのスペースを表示します：

# List all spaces
confluence spaces

返される情報：スペースキー、名前、種類、URL

5. タイトルでページを検索

完全一致または部分一致するタイトルでページを検索します：

# Find in all spaces
confluence find "Project Documentation"

# Find in specific space
confluence find "API Guide" --space DEV

6. ページの作成

コンテンツを指定して新しいページを作成します：

# Create with inline content
confluence create "My New Page" SPACEKEY --content "Hello World!"

# Create from file
confluence create "Documentation" SPACEKEY --file ./content.md --format markdown

# Create with HTML content
confluence create "Release Notes" SPACEKEY --content "<h1>Version 2.0</h1>" --format html

# Create with storage format (Confluence native)
confluence create "Technical Doc" SPACEKEY --file ./doc.xml --format storage

主なオプション：

• --content - インラインのコンテンツ文字列
• --file - ファイルからコンテンツを読み込む
• --format - コンテンツ形式：markdown、html、または storage（デフォルト：storage）

7. 子ページの作成

既存の親ページの下にページを作成します：

# Create child page with inline content
confluence create-child "Subsection" 123456789 --content "Child content"

# Create from file
confluence create-child "API Reference" 123456789 --file ./api-docs.md --format markdown

# Using parent page URL
confluence create-child "Details" "https://...pages/123456789" --content "Details here"

8. ページの更新

既存のページを変更します：

# Update title only
confluence update 123456789 --title "Updated Title"

# Update content only
confluence update 123456789 --content "New content" --format markdown

# Update from file
confluence update 123456789 --file ./updated-content.md --format markdown

# Update both title and content
confluence update 123456789 --title "New Title" --content "New content"

主なオプション：

• --title - ページのタイトルを変更する
• --content - インラインのコンテンツ
• --file - ファイルからコンテンツを読み込む
• --format - コンテンツ形式（markdown、html、storage）

9. 編集ワークフロー（エクスポート → 変更 → 更新）

ページをエクスポートしてローカルで編集します：

# Export page to file in storage format
confluence edit 123456789 --output ./page.xml

# Edit the file locally with your preferred editor
# Then update back to Confluence
confluence update 123456789 --file ./page.xml --format storage

このワークフローは次の用途に便利です：

• 複雑な書式の変更
• オフラインでの編集
• バージョン管理との連携
• バッチ処理

10. ページツリーのコピー

子ページをすべて含めて、ページ階層を複製します：

# Copy entire page tree
confluence copy-tree 123456789 987654321

# Copy with custom title for root page
confluence copy-tree 123456789 987654321 "Copied Documentation"

# Limit depth of copy
confluence copy-tree 123456789 987654321 --max-depth 2

# Exclude pages by pattern (wildcards supported)
confluence copy-tree 123456789 987654321 --exclude "temp*,*draft*,*obsolete*"

# Add delay between operations (for rate limiting)
confluence copy-tree 123456789 987654321 --delay-ms 500

# Dry run (preview without making changes)
confluence copy-tree 123456789 987654321 --dry-run

主なオプション：

• --max-depth <number> - ツリーの深さを制限する（デフォルト：無制限）
• --exclude <patterns> - 除外するワイルドカードパターンをカンマ区切りで指定する
• --delay-ms <number> - API 呼び出し間の遅延時間をミリ秒で指定する
• --dry-run - 変更を加えずに、コピー内容をプレビューする

除外パターン：

• * は任意の文字列に一致します
• ? は 1 文字に一致します
• 例：temp*、*draft*、archive-?

11. 統計の表示

CLI の使用状況に関する分析データを確認します：

# View usage statistics
confluence stats

分析を無効にする：

export CONFLUENCE_CLI_ANALYTICS=false

コンテンツ形式

ストレージ形式（Confluence ネイティブ）

Confluence の内部 XML ベース形式（XHTML）：

<p>This is <strong>bold</strong> and <em>italic</em> text.</p>
<ac:structured-macro ac:name="code">
  <ac:plain-text-body><![CDATA[console.log('Hello');]]></ac:plain-text-body>
</ac:structured-macro>

使用する場面：

• Confluence 固有の機能を最大限忠実に再現する場合
• マクロ、レイアウト、高度な書式設定を扱う場合
• エクスポート／インポートのワークフロー

HTML 形式

標準 HTML：

<h1>Heading</h1>
<p>Paragraph with <strong>bold</strong> text.</p>
<ul>
  <li>List item 1</li>
  <li>List item 2</li>
</ul>

使用する場面：

• 慣れ親しんだ構文を使う場合
• 他の HTML ソースから変換する場合
• シンプルな書式設定が必要な場合

Markdown 形式

GitHub Flavored Markdown：

# Heading

Paragraph with **bold** text.

- List item 1
- List item 2

```code
console.log('Hello');

**When to use:**
- Developer documentation
- README files and similar content
- Simple, readable syntax
- Integration with markdown-based tools

**Note**: Markdown is converted to storage format server-side. Complex Confluence features may not be available.

## Best Practices

### 1. Authentication and Security

```bash
# Store credentials securely in environment variables
# Add to ~/.bashrc, ~/.zshrc, or use a secrets manager
export CONFLUENCE_API_TOKEN="your-token-here"

# Rotate API tokens regularly
# Revoke old tokens from: https://id.atlassian.com/manage-profile/security/api-tokens

# Use separate tokens for different environments
export CONFLUENCE_DEV_TOKEN="dev-token"
export CONFLUENCE_PROD_TOKEN="prod-token"

2. 一括操作

一括操作では、シェルツールと組み合わせます：

# Search and process multiple pages
confluence search "type=page AND space=DEV" | while read -r line; do
  # Extract page ID and process
  # Add delays to respect rate limits
  sleep 1
done

# Batch create pages from directory of markdown files
for file in docs/*.md; do
  title=$(basename "$file" .md)
  confluence create "$title" DEV --file "$file" --format markdown
  sleep 0.5  # Rate limit protection
done

3. レート制限

Confluence API のレート制限を遵守します：

# Add delays in scripts
sleep 0.5  # 500ms between calls

# Use --delay-ms for copy-tree operations
confluence copy-tree SOURCE TARGET --delay-ms 500

# Monitor for rate limit errors and implement backoff

4. スクリプトでのエラー処理

#!/bin/bash

# Check if confluence is installed
if ! command -v confluence &> /dev/null; then
  echo "confluence-cli not found. Install: npm install -g confluence-cli"
  exit 1
fi

# Check authentication
if ! confluence spaces &> /dev/null; then
  echo "Authentication failed. Run: confluence init"
  exit 1
fi

# Perform operations with error checking
if confluence create "My Page" DEV --content "Hello"; then
  echo "Page created successfully"
else
  echo "Failed to create page"
  exit 1
fi

5. バージョン管理との統合

# Export pages for version control
mkdir -p confluence-backup
for page_id in 123456 234567 345678; do
  confluence read "$page_id" --format markdown > "confluence-backup/${page_id}.md"
done

# Commit to git
cd confluence-backup
git add .
git commit -m "Backup Confluence pages"
git push

6. コンテンツの移行

# Migrate space documentation to new space

# 1. Export all pages from source space
SOURCE_SPACE="OLD"
TARGET_SPACE="NEW"

# Get root pages in source space
confluence search "type=page AND space=$SOURCE_SPACE AND parent is null" > root_pages.txt

# 2. For each root page, copy tree to target space
# (Manual: create corresponding parent page in target space first)
# Then copy children:
confluence copy-tree SOURCE_PAGE_ID TARGET_PAGE_ID

よくあるユースケース

ドキュメントのワークフロー

# 1. Create documentation structure
confluence create "API Documentation" DEV --content "# API Docs"
ROOT_ID=123456789

# 2. Create subsections
confluence create-child "Authentication" $ROOT_ID --file ./auth.md --format markdown
confluence create-child "Endpoints" $ROOT_ID --file ./endpoints.md --format markdown
confluence create-child "Examples" $ROOT_ID --file ./examples.md --format markdown

# 3. Update as docs evolve
confluence update $ROOT_ID --file ./updated-overview.md --format markdown

コンテンツの検索とエクスポート

# Find and export all API documentation
confluence search "type=page AND title~'API'" --limit 50 | \
  grep -o '[0-9]\{8,\}' | \
  while read page_id; do
    confluence read "$page_id" --format markdown > "export/${page_id}.md"
  done

スペースの移行

# Copy documentation from one space to another
# (Requires manual creation of target parent page first)

SOURCE_ROOT=123456789  # Root page in source space
TARGET_ROOT=987654321  # Root page in target space (pre-created)

confluence copy-tree $SOURCE_ROOT $TARGET_ROOT "Migrated Documentation" \
  --exclude "*draft*,*temp*" \
  --delay-ms 500 \
  --dry-run  # Remove after verifying

更新の自動化

#!/bin/bash
# Update release notes automatically

VERSION="2.0.0"
DATE=$(date +"%Y-%m-%d")
PAGE_ID=123456789

# Generate release notes from git log
echo "# Release $VERSION ($DATE)" > release-notes.md
echo "" >> release-notes.md
git log --oneline --since="2 weeks ago" >> release-notes.md

# Update Confluence page
confluence update $PAGE_ID --file release-notes.md --format markdown

echo "Release notes updated for version $VERSION"

バックアップと復元

# Backup script
BACKUP_DIR="./confluence-backup-$(date +%Y%m%d)"
mkdir -p "$BACKUP_DIR"

# Export pages from specific space
confluence search "type=page AND space=DEV" | \
  grep -o '[0-9]\{8,\}' | \
  while read page_id; do
    confluence read "$page_id" --format storage > "$BACKUP_DIR/${page_id}.xml"
    confluence info "$page_id" > "$BACKUP_DIR/${page_id}-info.json"
    sleep 0.5
  done

tar -czf "confluence-backup-$(date +%Y%m%d).tar.gz" "$BACKUP_DIR"

Claude Code との統合

Claude Code でこのスキルを使用する場合：

1. インストールを確認する：confluence コマンドが利用可能であることを確認します
2. 認証を確認する：confluence spaces を実行して動作を確認します
3. Bash ツールを使用する：Bash ツールから Confluence コマンドを実行します
4. 出力を解析する：ほとんどのコマンドは人間が読みやすいテキストを出力します。利用可能な場合は --format フラグを使用します
5. ページ ID を処理する：URL または検索結果からページ ID を抽出します
6. レート制限に対応する：一括操作では待ち時間を追加します
7. エラーを処理する：終了コードを確認し、役立つエラーメッセージを表示します
8. 破壊的な操作を確認する：一括更新や削除の前に警告します

トラブルシューティング

認証の問題

# Check if configuration exists
ls -la ~/.confluence/

# Re-run initialization
confluence init

# Test connection
confluence spaces

API エラー

# Verify API token is valid
# Check: https://id.atlassian.com/manage-profile/security/api-tokens

# Ensure correct domain format
# Cloud: "yourcompany.atlassian.net"
# NOT: "https://yourcompany.atlassian.net"

# Check API path matches your instance type
# Cloud: /wiki/rest/api
# Self-hosted: /rest/api

レート制限

# If you encounter rate limits:
# - Add delays between operations (--delay-ms or sleep)
# - Reduce batch sizes
# - Space out operations over time

コンテンツ形式の問題

# If content doesn't render correctly:
# - Try different format: --format storage, html, or markdown
# - Export existing similar page to see format: confluence edit PAGE_ID --output example.xml
# - Use storage format for maximum compatibility

制限事項

サードパーティ製ツール

• Atlassian の公式製品ではありません：コミュニティによって保守されています
• サポート：Atlassian サポートではなく、GitHub の Issue を通じて提供されます
• 更新：コミュニティからの貢献に依存します
• 互換性：Confluence API の変更への対応が遅れる場合があります

API の制限事項

• 添付ファイル管理には非対応：この CLI から添付ファイルをアップロードまたはダウンロードできません
• マクロのサポートは限定的：複雑な Confluence マクロは Markdown／HTML 形式では動作しない場合があります
• 管理者操作には非対応：ユーザーやスペースの管理はサポートされていません
• レート制限：Confluence Cloud API のレート制限が適用されます

形式変換

• Markdown の制限：すべての Confluence 機能を Markdown で利用できるわけではありません
• HTML からストレージ形式への変換：複雑なレイアウトでは手動調整が必要な場合があります
• マクロ：ストレージ形式で作成・編集するのが最適です

代替ツール

Atlassian 公式 CLI（acli）

• 状況：現在、Confluence には対応していません（Jira のみ）
• サポートが追加された場合：推奨される公式ツールになる可能性があります
• 現在：Jira の操作にのみ使用します

Appfire Confluence CLI

• 種類：Marketplace の商用アプリ
• 機能：より包括的な管理・自動化機能
• 費用：購入またはライセンスが必要です
• 用途：エンタープライズ自動化、高度な管理タスク

Confluence REST API

• API の直接呼び出し：curl などのツールを使用します
• 柔軟性：最大限の制御が可能です
• 複雑さ：より多くのコードが必要です
• 用途：カスタム統合、特定の要件への対応

ヘルプとドキュメント

# Main help
confluence --help

# Command help
confluence read --help
confluence create --help
confluence copy-tree --help

# Version info
confluence --version

外部リソース：

• GitHub：https://github.com/pchuri/confluence-cli
• NPM：https://www.npmjs.com/package/confluence-cli
• Confluence REST API：https://developer.atlassian.com/cloud/confluence/rest/v1/

重要な注意事項

• サードパーティ製ツール：Atlassian の公式ツールではなく、コミュニティによって開発されています
• クラウドとセルフホスト：どちらにも対応していますが、設定方法は異なります
• API トークン：認証に必要です。Atlassian アカウント設定から取得してください
• レート制限：一括操作では Confluence API のレート制限を遵守してください
• コンテンツ形式：Confluence の機能を最も忠実に再現するには、ストレージ形式を使用してください
• 公式 CLI なし：Atlassian の公式 CLI（acli）は、現在 Confluence に対応していません
• 分析：ツールは匿名の使用状況データを収集します（環境変数でオプトアウトできます）