fetch-confluence-page

fetch-confluence-page is a command-line tool for Confluence 6.3.1. It accepts a Confluence page URL that includes pageId, fetches the page HTML from the body.view API with Basic Auth, converts the content to Markdown, and also:

• Writes the Markdown to stdout
• Saves it under the .confluence/ directory in the current working directory
• Downloads page images to the local assets/ directory when possible and rewrites the references

Install

npm install -g fetch-confluence-page

Install the bundled skill:

fetch-confluence-page install-skill

You can also run it directly from this repository for local development:

npm install
node ./bin/fetch-confluence-page.js --help

Usage

fetch-confluence-page --url '<confluence-page-url>'
fetch-confluence-page -u '<confluence-page-url>'

Install the skill:

fetch-confluence-page install-skill
fetch-confluence-page install-skill --agent codex
fetch-confluence-page install-skill --agent claude-code
fetch-confluence-page install-skill --no-force
fetch-confluence-page install-skill --dest ~/.claude/skills

Override credentials for a single run:

fetch-confluence-page \
  --url 'https://confluence.example.com/pages/viewpage.action?pageId=12345' \
  --username 'alice' \
  --password 'secret'

You can also override credentials for a single run with environment variables:

FETCH_CONFLUENCE_USERNAME='alice' \
FETCH_CONFLUENCE_PASSWORD='secret' \
fetch-confluence-page --url 'https://confluence.example.com/pages/viewpage.action?pageId=12345'

Requirements

• Node.js >= 18
• The URL must include pageId
• This version always calls GET <confluence-host>/rest/api/content/{pageId}?expand=body.view

Install the Skill

The bundled fetch-confluence-page skill can be installed into Codex or Claude Code directly:

fetch-confluence-page install-skill

If --agent is omitted in an interactive terminal, the command shows a selection list so you can choose the target agent directly. If the current terminal is not interactive, it defaults to Codex.

Default install locations:

Codex: ${CODEX_HOME:-~/.codex}/skills/fetch-confluence-page
Claude Code: ${CLAUDE_CONFIG_DIR:-~/.claude}/skills/fetch-confluence-page

Options:

| Option | Required | Default | Description | | --- | --- | --- | --- | | --agent | No | Interactive selection in TTY mode; codex in non-interactive mode | Target agent. Supported values: codex and claude-code | | --dest | No | Depends on the selected agent: $CODEX_HOME/skills, ~/.codex/skills, $CLAUDE_CONFIG_DIR/skills, or ~/.claude/skills | Custom skill install root | | --force | No | true | Overwrite an existing skill with the same name | | --no-force | No | false | Fail instead of overwriting when the target skill already exists |

Restart the target agent after installation so it can load the new skill.

Authorization

When you access a Confluence host for the first time:

• In an interactive terminal, the tool prompts for username and password and stores them locally
• In a non-interactive terminal, you must provide credentials with --username/--password or environment variables

Local credential file:

~/.fetch-confluence-page/credentials.json

Credentials are stored by Confluence host, so multiple hosts can coexist. CLI arguments and environment variables apply only to the current run and do not overwrite stored credentials.

Output

After a successful fetch, the Markdown is:

• Written to stdout
• Saved to ./.confluence/<sanitized-page-title>_<pageId>.md
• Saved with page images under ./.confluence/assets/<pageId>/ when possible

Notes:

• The host value is sanitized so output from different Confluence sources can coexist safely
• If the page title is empty, or becomes empty after sanitization, the filename falls back to page_<pageId>.md
• Fetching the same page again overwrites the previous local file
• Root-relative links such as /pages/viewpage.action?... are rewritten to absolute URLs
• Images are downloaded with the same Basic Auth credentials when possible, so Markdown previews do not depend on browser cookies
• If an image still cannot be downloaded because of permissions or a network error, the Markdown keeps the absolute remote URL and prints a warning to stderr

Example output path:

./.confluence/Product-Plan_12345.md

Agent Usage

This tool is designed to be called directly by Codex or Claude Code:

• The skill assumes the global command is already installed and the runtime environment can already access the target Confluence host
• The agent can consume the Markdown from stdout immediately for follow-up analysis
• A copy is also kept under .confluence/ so later steps can reuse the file
• Authorized images are localized when possible, so agents or IDEs can read the Markdown without relying on a browser login session
• If you use multiple Confluence hosts, it is recommended to complete interactive authorization for each host once, then let the agent reuse the stored local credentials

Common Errors

• 请输入包含 pageId 的正确 Confluence URL。
  • The URL is missing pageId
• Host <...> 尚未授权，且当前为非交互模式。
  • The current terminal is non-interactive and no credentials are available
• Confluence 授权失败（401）。
  • The username or password is wrong, or the stored credentials have expired
• Confluence 响应中缺少 body.view.value。
  • The API response structure does not match expectations
• Markdown 已获取成功，但写入本地文件失败。
  • Creating .confluence/ or writing the local file failed
• 图片未能本地化，已保留远程链接: ...
  • The image endpoint rejected the current Basic Auth credentials, or a network error occurred while downloading the image

Skill

This repository includes one usage-focused skill:

skills/fetch-confluence-page/

This skill is meant for the scenario where an agent calls the installed fetch-confluence-page command to read a Confluence page. It does not describe how to maintain this tool itself. It assumes the agent environment already has the command installed and already has access to the target Confluence host, so the instructions focus on command usage and output consumption.