# Confluence CLI

> 查询、检索与阅读 Confluence 文档/页面。

- Skill: `dcjanus/confluence-cli` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add dcjanus/confluence-cli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dcjanus/confluence-cli/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: DCjanus (https://skillmd.com/u/dcjanus)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/dcjanus/confluence-cli

---


1) 常用子命令（覆盖日常场景）
- `space`
  - `list [--start --limit --expand]`
  - `get --space-key [--expand]`
- `page`
  - `get --page-id [--body-format --expand --fresh]`
  - `by-title --space-key --title [--body-format --expand]`
  - `children --page-id [--start --limit --expand]`
  - `rename --page-id --title`
  - `publish-markdown --parent-id --title --markdown-path [--update-if-exists --body-format --expand]`
- `attachment`
  - `list --page-id [--start --limit --expand]`
  - `download --page-id [--output-dir --name --filter --all --start --limit --expand]`
- `search`
  - `--cql [--start --limit --body-format --expand]`

2) 输出格式
- 所有调用统一在脚本后、子命令前加 `--json`（示例：`./scripts/confluence_cli.py --json page get --page-id ...`）

3) 冷门参数/字段怎么查
- 运行 `./scripts/confluence_cli.py <command> --help` 查看该命令的参数
- 需要更深入的 Confluence API 字段时，可扩展脚本中的 `expand` 参数

4) 注意事项
- `page get` 默认保持普通缓存读；刚更新页面后需要校验正文时，使用 `--fresh` 绕过 Confluence 或代理缓存，例如：`./scripts/confluence_cli.py --json page get --page-id ... --body-format storage --expand body.storage,version --fresh`
- 如果 Markdown 文件由 Agent 为当前单次发布临时创建，且成功后不再复用，在同一次
  shell 调用中把发布命令与 `rm -- <明确路径>` 用 `&&` 串行执行。发布失败时保留文件，
  不要使用 `;` 无条件删除，也不要用变量、通配符或目录作为清理目标。用户提供的源文档、
  仓库文件和本地图片不得随 Markdown 临时文件自动删除。

5) 附件下载示例
- 下载指定附件（可重复传入 `--name`）：`./scripts/confluence_cli.py attachment download --page-id 3060336952 --output-dir ./attachments --name a.png --name b.png`
- 下载全部附件（自动分页）：`./scripts/confluence_cli.py attachment download --page-id 3060336952 --all --output-dir ./attachments`
- 过滤下载（正则）：`./scripts/confluence_cli.py attachment download --page-id 3060336952 --filter 'image2026-1-19_.*\\.png' --all --output-dir ./attachments`

6) 发布 Markdown 示例
- 发布到父页面（同名则更新）：`./scripts/confluence_cli.py --json page publish-markdown --parent-id 3061931928 --title "批量重置 Offset 功能测试" --markdown-path /path/to/doc.md`
- 发布单次临时 Markdown 并在成功后清理：`./scripts/confluence_cli.py --json page publish-markdown --parent-id 3061931928 --title "批量重置 Offset 功能测试" --markdown-path /tmp/confluence-page.md && rm -- /tmp/confluence-page.md`
- Markdown 表格支持 `:---`、`:---:`、`---:` 这类左对齐、居中、右对齐语法，会转换为 Confluence storage 的 table cell `text-align` 样式。
- 本地图片发布时会按最大展示框自动生成单个 Confluence 尺寸属性：默认最大宽度 `1000`、最大高度 `800`，可用 `--image-max-width` / `--image-max-height` 覆盖；只写触发缩放的 `ac:width` 或 `ac:height`，不修改附件原图。
- 如需覆盖单张图片展示尺寸，可使用 Markdown title：`![图](./a.png "confluence-width=1200")`、`![图](./a.png "confluence-height=600")`、`![图](./a.png "confluence-size=original")`。

## 资源

- [confluence_cli.py](scripts/confluence_cli.py)：主 CLI 入口，负责读取配置并发起 API 调用。
- [confluence_api_client.py](scripts/confluence_api_client.py)：SDK 封装层，收敛常用 API 调用。