confluence

CLI for managing Confluence Cloud content and publishing storage bundles produced by other tools (notably richdoc). JSON output, no interactive prompts.

When to use confluence

• Browsing or searching Confluence spaces / pages.
• Downloading existing pages locally — a single page, a subtree, or a whole space — into JSONL (lossless, default) and optionally best-effort markdown for human reading. This is the read side of the edit-and-reupload loop.
• Creating, updating, or deleting Confluence pages from storage-format XML files.
• Uploading attachments to a page.
• Managing the auth profile(s) the agent uses to talk to Confluence.
• Publishing a richdoc.confluence.bundle.v1 directory to a Confluence space (one-shot, idempotent, two-pass).

For authoring rich documents, use the richdoc skill. The two skills share a documented on-disk bundle format and are deliberately decoupled: confluence never imports richdoc code, and richdoc never opens a Confluence connection.

CLI Discovery

The CLI is located at ./confluence-cli/ relative to this SKILL.md. Requires uv; the first call provisions the Python environment.

All three of page-by-id, page get, page update, and download accept either a numeric page id or a full Confluence page URL (e.g. https://acme.atlassian.net/wiki/spaces/DEV/pages/123456/Title). TinyLinks (/wiki/x/…) need to be expanded in a browser first.

Authentication — the AI agent workflow

The CLI never accepts an API token as a flag, on stdin, or through any other channel the AI agent can supply. The token MUST be entered by the human user. The agent's job is to template the config file and forward instructions.

Standard recipe (do this exact sequence):

1. Call confluence auth init --profile NAME [--site URL] [--email EMAIL] [--space-key KEY].
2. Read the next_steps array from the JSON envelope. Forward those instructions to the user verbatim. Do not try to fill in the token yourself.
3. Wait for the user to confirm they've saved the file.
4. Call confluence auth status --profile NAME to verify.

For CI / headless contexts, prefer the env-var path — no auth init needed:

export CONFLUENCE_SITE=https://acme.atlassian.net
export CONFLUENCE_EMAIL=me@acme.com
export CONFLUENCE_TOKEN=...     # CI secret
export CONFLUENCE_SPACE_KEY=DEV
confluence spaces

See references/auth.md for the threat model, full resolution precedence, and the advanced OS-keyring path.

Downloading existing pages (read side)

The agent workflow for editing a page that already lives in Confluence:

1. Get a page reference from the human — a numeric id, a page URL, or a title within a space.
2. Download the page (and optionally its subtree) locally:

   # Single page from a URL the user pasted:
   confluence download "https://acme.atlassian.net/wiki/spaces/DEV/pages/123456/How+to+deploy" \
       -o ./pulled --markdown --attachments
   
   # A page and all its descendants:
   confluence download 123456 -o ./pulled --recurse --depth 3

3. Inspect ./pulled/manifest.json for the page tree, then read ./pulled/pages.jsonl. Each row is a complete page record with the storage-format XML body under body.value. This is the lossless, edit-friendly representation.
4. To edit a page: extract body.value, modify the storage XML (LLMs handle XHTML + ac:*/ri:* macros fine), write it to a file, then push it back with:

   confluence page update 123456 --body-file edited.storage.xml

5. The download envelope already suggests this nextStep argv so the agent has a known-good path forward.

Important: markdown is read-only. When --markdown is passed, each page also gets a best-effort .md sidecar so a human can skim it. The conversion is intentionally lossy — info/warning callouts, code blocks, page links, attachments, expand sections, and task lists are handled; everything else degrades to HTML comments or plain text. Never re-upload from markdown. Always edit the storage XML in pages.jsonl and push via page update.

See references/download.md for the full JSONL/manifest schema, markdown caveats, and worked examples.

Publishing a richdoc bundle

Always a two-step flow. The agent should pipe nextStep.argv from the richdoc envelope directly into the next command — don't reconstruct the bundle path by hand.

# 1. In the richdoc skill: build the bundle (no credentials needed).
richdoc export confluence docs/ -o build/confluence-docs
# Envelope contains: "nextStep": {"argv": ["confluence", "publish-bundle", "<path>"], ...}

# 2. Here: publish it.
confluence publish-bundle build/confluence-docs --profile work --parent-id 12345

The publisher is idempotent: re-running updates existing pages in place (matched by (space, parent, title)) and re-uploads only changed attachments. Cross-page links and attachment references are resolved post-creation. See references/richdoc-bundles.md.

Common agent mistakes

• Do not pass a .html file or a richdoc source directory to confluence publish-bundle. It will fail with code: NOT_A_BUNDLE and a hint pointing at richdoc export confluence. Always build a bundle first.
• Do not attempt to run auth login — the command no longer exists. Use auth init to template a config file, then ask the user to fill in the token.
• Do not echo, log, or include CONFLUENCE_TOKEN or any literal token value in commands you suggest to the user. Reference env vars by name only.

Output

Every command writes a single-line JSON envelope to stdout. On success: {"ok": true, ...}. On failure: {"ok": false, "code": "...", "error": "...", "hint": "..."}. Exit code matches.

Limits and trust

• Confluence Cloud only. The v2 REST API the client targets does not exist on Data Center.
• Pages and attachments only. Whiteboards, databases, blog posts, comments, and labels are not managed by this CLI yet.
• Read side is JSONL + storage XML. confluence download pulls pages locally losslessly. Markdown is opt-in, best-effort, and read-only — re-uploads always go through storage XML.
• No mirror sync. Re-downloading does not delete local files; uploading does not delete Confluence pages. Stale dumps must be pruned manually.
• Destructive operations require confirmation. page delete (when implemented) takes --confirm; without it the call errors with CONFIRMATION_REQUIRED.

See also

• references/auth.md — profile / env / keyring precedence; corporate-proxy TLS / CA-bundle env vars.
• references/download.md — JSONL / manifest schema for confluence download, markdown caveats, edit-and-reupload recipe.
• references/richdoc-bundles.md — bundle schema and publish algorithm.
• richdoc/SKILL.md — authoring polished HTML documents and producing Confluence bundles.