Confluence Agent CLI

Git-like Confluence pull/diff/push workflow for coding agents.

The goal is simple: turn Confluence pages into local files an agent can inspect, edit, diff, and push back without using the browser editor.

npm install -g confluence-agent-cli

conf init --base-url https://example.atlassian.net --email [email protected]
export CONFLUENCE_API_TOKEN=...

conf doctor https://example.atlassian.net/wiki/spaces/ENG/pages/123456/Runbook
conf pull https://example.atlassian.net/wiki/spaces/ENG/pages/123456/Runbook --out wiki --depth 2
conf status --dir wiki
conf diff --dir wiki
conf push --dir wiki --dry-run
conf push --dir wiki --message "Update runbook from agent"

Why this exists

Agents are good at editing files. Confluence is not a file system.

This CLI creates a local page tree:

wiki/
  .confagent/
    manifest.json
    originals/
  api-runbook-123456/
    attachments/
      screenshot.png
    attachments.json
    page.md
    page.storage.html
    meta.json

Agents usually edit page.md. If a page contains Confluence macro or namespaced storage markup, the CLI marks it as a lossy conversion risk and refuses Markdown-based pushes by default. In those cases, edit page.storage.html or pass --allow-lossy deliberately.

Attachments are pulled into each page's attachments/ directory. Add a file there or modify an existing file, then run conf push --dry-run before publishing. Local deletion of attachments is intentionally ignored in the current version; remote attachment deletion is not implemented yet.

Commands

conf init

Writes .confagent/config.yaml.

conf init --base-url https://example.atlassian.net --email [email protected]

Credentials are read from the environment:

• CONFLUENCE_API_TOKEN with CONFLUENCE_EMAIL or the configured email
• CONFLUENCE_BEARER_TOKEN for OAuth-style bearer auth

conf pull <page-id-or-url>

Pulls the root page and child pages.

conf pull 123456 --out wiki --depth 3
conf pull https://example.atlassian.net/wiki/spaces/ENG/pages/123456/Runbook --out wiki --depth 3

--depth 0 pulls only the root page.

If you pass a full Confluence page URL, the CLI extracts both the page ID and base URL. That means first-time users can skip conf init when CONFLUENCE_EMAIL and CONFLUENCE_API_TOKEN are set.

conf doctor [page-id-or-url]

Checks local auth configuration and optional live page access.

conf doctor
conf doctor 123456
conf doctor https://example.atlassian.net/wiki/spaces/ENG/pages/123456/Runbook

The command prints the base URL and auth mode. When a page is provided, it verifies live access by fetching that page and printing its title/version.

conf status

Shows changed pulled pages.

conf status --dir wiki

conf new <title>

Creates a pending local page under a pulled parent page.

conf new "Incident Runbook" --parent 123456 --dir wiki
conf new "Incident Runbook" --parent https://example.atlassian.net/wiki/spaces/ENG/pages/123456/Runbook --dir wiki

The new page is created locally first. Edit its page.md, add files to its attachments/ folder if needed, then review and publish:

conf diff --dir wiki
conf push --dir wiki --dry-run
conf push --dir wiki --message "Create incident runbook"

Current limitation: creating a local child under another pending local page is not supported yet. Create the first page, push it, then add children under the newly pulled/created page.

conf diff

Prints unified diffs against the last pulled/pushed state.

conf diff --dir wiki

conf push

Pushes local changes back to Confluence.

conf push --dir wiki --dry-run
conf push --dir wiki --message "Refresh deployment checklist"

Push behavior:

• Checks the live Confluence version before writing.
• Refuses to overwrite remote edits unless --force is passed.
• Creates pending local pages made with conf new.
• Chooses page.md when only Markdown changed.
• Chooses page.storage.html when only storage changed.
• Refuses when both changed unless --source markdown or --source storage is provided.
• Refuses lossy Markdown pushes unless --allow-lossy is provided.
• Uploads new or modified files in page attachments/ folders.
• Refuses to overwrite remotely changed attachments unless --force is passed.

Install For Local Development

For normal use:

npm install -g confluence-agent-cli
conf --help

Or run without a global install:

npx confluence-agent-cli --help

For local development:

npm install
npm run build
npm link

Then run:

conf --help

Copy .env.example if you want a local env file, then source it before running the CLI:

cp .env.example .env
set -a
source .env
set +a

Current Scope

Implemented:

• Pull Confluence page trees through the Confluence Cloud REST API v2.
• Pull by pasted Confluence page URL or numeric page ID.
• Verify auth and page access with conf doctor.
• Write local Markdown, raw storage HTML, metadata, manifest, and original snapshots.
• Pull page attachments into local attachments/ folders.
• Upload new or modified attachment files during conf push.
• Create new pages locally with conf new and publish them with conf push.
• Show local status and unified diffs.
• Push Markdown or storage edits with optimistic version checks.
• Provide a small agent skill in skills/confluence-agent-cli/SKILL.md.

Not implemented yet:

• Creating children under pending local pages before the parent is pushed.
• Deleting pages.
• Deleting remote attachments.
• Label sync.
• Comment sync.
• OAuth device flow.

API Notes

The first version uses Confluence Cloud REST API v2 page endpoints:

• Get page by ID and update page
• Get child pages
• Get page attachments
• Create or update attachment

Confluence storage format is XHTML-like, and Markdown conversion can be lossy for macros or rich Confluence-specific elements. The raw page.storage.html file is included for that reason.