confluence-cli

Confluence CLI（NPM Package）

概述

confluence-cli 是由社区开发的 Atlassian Confluence 命令行界面，可直接在终端管理内容。这是一款通过 NPM 提供的第三方工具（非 Atlassian 官方工具）。

在以下情况下使用此工具：

• 用户需要基于 CLI 执行 Confluence 操作
• 需要自动化文档工作流
• 需要批量操作页面
• 需要在不同空间之间迁移内容
• 用户希望通过脚本更新文档

重要：这不是 Atlassian 官方 CLI（acli），后者不支持 Confluence。这是一款社区工具：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
• Self-hosted/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（Self-hosted/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 - 预览将要复制的内容，但不进行更改

排除模式：

• * 匹配任意字符
• ? 匹配单个字符
• 示例：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 风格的 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. 批量操作

对于批量操作，可结合使用 shell 工具：

# 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 官方产品：由社区维护
• 支持：通过 GitHub issues 获取支持，而非 Atlassian 支持
• 更新：取决于社区贡献
• 兼容性：可能无法及时跟进 Confluence API 的变更

API 限制

• 不支持附件管理：无法通过此 CLI 上传/下载附件
• 宏支持有限：复杂的 Confluence 宏可能无法与 markdown/HTML 格式兼容
• 不支持管理操作：不支持用户/空间管理
• 速率限制：受 Confluence Cloud API 速率限制约束

格式转换

• Markdown 的限制：Markdown 不支持所有 Confluence 功能
• 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
• 分析数据：工具会收集匿名使用数据（可通过环境变量选择退出）