playbooks

home / skills / dcjanus / prompts / confluence-cli

confluence-cli skill

/skills/confluence-cli

This skill helps you query, retrieve, and read Confluence pages and spaces via a Python CLI, with JSON output.

npx playbooks add skill dcjanus/prompts --skill confluence-cli

Review the files below or copy the command above to add this skill to your agents.

Files (4)
SKILL.md
2.5 KB
---
name: confluence-cli
description: 查询、检索与阅读 Confluence 文档/页面。
---

说明：以下调用方式均以当前 `SKILL.md` 文件所在文件夹为 workdir。

脚本调用方式（必须直接执行，不要用 `uv run python` 或 `python`）：
```bash
cd skills/confluence-cli && ./scripts/confluence_cli.py --json page get --page-id 3060336952
```
错误示例：
```bash
uv run python skills/confluence-cli/scripts/confluence_cli.py --json page get --page-id 3060336952
python skills/confluence-cli/scripts/confluence_cli.py --json page get --page-id 3060336952
```

1) 常用子命令（覆盖日常场景）
- `space`
  - `list [--start --limit --expand]`
  - `get --space-key [--expand]`
- `page`
  - `get --page-id [--body-format --expand]`
  - `by-title --space-key --title [--body-format --expand]`
  - `children --page-id [--start --limit --expand]`
  - `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) 附件下载示例
- 下载指定附件（可重复传入 `--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`

5) 发布 Markdown 示例
- 发布到父页面（同名则更新）：`./scripts/confluence_cli.py --json page publish-markdown --parent-id 3061931928 --title "批量重置 Offset 功能测试" --markdown-path /path/to/doc.md`

## 资源

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

Overview

This skill provides a lightweight CLI to query, retrieve, read, and publish Confluence content. It exposes common Confluence API operations for spaces, pages, attachments, and search via a single Python-based command-line script. The tool returns JSON for programmatic use and supports markdown publishing and bulk attachment downloads.

How this skill works

Run the bundled CLI script from the skill folder to call Confluence APIs. Commands map to high-level operations (space, page, attachment, search) and accept parameters like page-id, space-key, CQL, expand, and body-format. Use --json to get machine-readable output and flags like --all or --filter to control pagination and downloads.

When to use it

  • Inspect space metadata and list spaces or fetch a specific space by key
  • Retrieve a page by ID or title, including body in different formats
  • Download one or many attachments with regex filtering or pagination
  • Publish or update pages from Markdown files under a parent page
  • Run CQL searches to locate pages, attachments, or other Confluence content

Best practices

  • Always run the CLI from the skill folder so relative script paths resolve correctly
  • Include --json for deterministic, parseable output in automation
  • Use expand to fetch additional Confluence fields only when needed to reduce payload size
  • When downloading attachments, prefer --all for automatic pagination or use --filter to limit results
  • Use --update-if-exists with publish-markdown to avoid creating duplicate pages

Example use cases

  • Fetch a page by its ID and render the body as storage or exportable HTML
  • Search Confluence with CQL to build an index of matching pages for offline processing
  • Batch-download all attachments from a page into a local folder, optionally filtering by filename regex
  • Publish a Markdown file as a child of a given parent page; update if a page with the same title exists
  • List children of a parent page to programmatically traverse documentation hierarchies

FAQ

How do I get JSON output for scripting?

Pass --json immediately after invoking the script; this makes all subcommands emit JSON.

How do I see available flags for a command?

Run the script with the command and --help to list parameters and examples.

Can I publish Markdown and update existing pages?

Yes. Use page publish-markdown with --parent-id and --title; add --update-if-exists to overwrite same-named pages.