confluence-cli

confluence-cli — 在终端中使用 Confluence Wiki

通过 REST API 与 Atlassian Confluence Cloud 交互。列出空间、浏览页面、查看页面正文、使用 CQL 搜索并创建页面。

设置

1. 在 id.atlassian.com/manage/api-tokens 生成 API 令牌
2. 设置环境变量：

export CONFLUENCE_EMAIL="[email protected]"
export CONFLUENCE_API_TOKEN="your-api-token"
export CONFLUENCE_SERVER="https://your-domain.atlassian.net"

无需凭据即可使用 --help 和 --dry-run。

核心命令

me — 当前用户资料

confluence-cli me                       # your account info
confluence-cli me --json                # machine-readable

spaces — 列出空间

confluence-cli spaces                   # all accessible spaces
confluence-cli spaces --limit 50        # more results
confluence-cli spaces --json            # machine-readable

pages — 列出页面

confluence-cli pages                                # recent pages across all spaces
confluence-cli pages --space DEV                    # pages in a specific space
confluence-cli pages --space DEV --limit 10          # top 10
confluence-cli pages --space DEV --json             # machine-readable

按空间键筛选，并自动将键解析为内部 ID。

view — 按 ID 查看页面

confluence-cli view 123456                   # full page with body
confluence-cli view 123456 --json            # machine-readable

显示标题、状态、版本、作者、时间戳和 HTML 正文（显示时会转换为纯文本）。--json 输出中包含完整 HTML 正文，最多 5000 个字符。

search — 使用 CQL 搜索

confluence-cli search --cql 'text~"deploy"'              # full-text search
confluence-cli search --cql 'space=DEV AND type=page'    # by space and type
confluence-cli search --cql 'creator=currentuser()'      # my content
confluence-cli search --cql 'text~"api"' --limit 5       # top 5 results

CQL（Confluence 查询语言）是 Confluence 的搜索语法。常见用法：

• text~"keyword" — 全文搜索
• space=KEY — 按空间筛选
• type=page — 按内容类型筛选
• creator=currentuser() — 搜索你的内容
• label="name" — 按标签搜索
• 使用 AND 组合：space=DEV AND text~"deploy"

create — 创建页面

confluence-cli create --space DEV --title "My Page"                             # basic
confluence-cli create --space DEV --title "API Docs" --body "<p>Content</p>"    # with HTML body
confluence-cli create --space DEV --title "Test" --parent 123456                # as child page
confluence-cli create --space DEV --title "Test" --dry-run                      # preview

通过 Confluence Cloud（v2 API）创建页面。正文使用 Confluence 的存储格式编写 HTML。对于简单页面，可以使用基本 HTML 标签（<p>、<ul>、<h2> 等）。

全局标志

所有标志都可以放在任意位置：

confluence-cli --json pages --space DEV              # flag before subcommand
confluence-cli pages --space DEV --json              # flag after subcommand
confluence-cli --dry-run create --space DEV --title "Test"
confluence-cli --quiet pages                         # suppress non-essential output

已知注意事项

• 身份验证使用电子邮件地址和 API 令牌进行 HTTP Basic Auth。凭据与 Jira 相同，但存储在不同名称的环境变量中。
• 两个 API 版本 — CLI 对大多数操作（空间、页面、创建）使用 v2 API，对 me 和 search（CQL）使用旧版 REST API。用户无需关心这一差异。
• 空间键必须解析为 ID — v2 API 要求使用数字空间 ID 进行筛选。CLI 会自动解析空间键，因此 pages --space 和 create --space 会额外发起一次 API 调用。
• 页面正文为 HTML — Confluence 存储格式使用 HTML。CLI 会在显示时剥除 HTML 标签，并在 --json 输出中返回原始 HTML（最多 5000 个字符）。创建包含丰富格式的页面需要有效的 HTML。
• CQL 搜索注意事项 — CQL 的大多数运算符不区分大小写。text~ 运算符会搜索正文全文。多词短语需用转义引号括起来。
• 速率限制 — Confluence Cloud 有速率限制。CLI 不会自动重试。

参考资料

• scripts/confluence-cli — CLI 可执行文件。按照 cli-builder 模式构建：非交互式，支持 --json、--dry-run、--quiet、--verbose，通过 emit() 双路输出、延迟身份验证和结构化日志记录。
• Confluence REST API v2 文档 — 官方 API 参考。
• CQL（Confluence 查询语言） — 搜索语法参考。
• API 令牌管理 — 生成和撤销令牌。