confluence-cli

Confluence, readable and scriptable.

Read, search, browse, automate, and edit Confluence Cloud or Data Center—without leaving the terminal.

Install · Quick start · Read and explore · Proof Desk · Commands

confluence-cli makes Confluence directly useful from the shell. Read and browse without creating a local sync directory. Pipe stable JSON into scripts and agents. When content needs to change, work in Markdown and publish through an explicit plan-and-apply boundary.

Install

Choose the package manager that fits your environment. Every distribution installs the confluence executable.

With uv from PyPI:

uv tool install confluence-cli-rs

With Homebrew:

brew install rvben/tap/confluence-cli

With Cargo:

cargo install confluence-cli

With Nix (flakes):

nix run github:rvben/confluence-cli -- --help
nix profile install github:rvben/confluence-cli

The PyPI distribution is named confluence-cli-rs; the crate is named confluence-cli. Prebuilt macOS and Linux archives for Intel and ARM are available from GitHub Releases.

Quick start

Connect a profile and check access:

confluence init
confluence doctor --space SPACEKEY

For local-only diagnostics, use confluence auth status --offline or confluence doctor --offline. The former doctor --skip-network spelling remains available as a compatibility alias.

Then read, search, or browse immediately—no pull required:

confluence search 'release notes' --space DOCS
confluence page tree 'DOCS:Handbook'
confluence tui --space DOCS

The same commands become structured input when piped:

confluence search 'release notes' --space DOCS \
  | jq '.items[] | {title, web_url}'

_{Proof Desk in its medium-width Browse layout, rendered from the deterministic test fixture. Open full resolution.}

When you want to edit, pull a page tree to Markdown and inspect the local plan:

confluence pull tree 'SPACEKEY:Parent Page' ./docs/parent-page
$EDITOR ./docs/parent-page/parent-page--123/index.md
confluence plan ./docs/parent-page --diff

When the plan is correct, apply it:

confluence apply ./docs/parent-page

plan reads only the Markdown and sidecar state on disk. apply validates the complete local tree and checks every remote version before writing. If Confluence changed after the pull, the apply is refused unless you explicitly choose --force.

Before writing a hand-edited storage body, check it offline:

confluence template expand > body.xml
confluence validate --format storage --body-file body.xml

validate needs no credentials and makes no API requests. Writes also validate bodies automatically, catching malformed XML, broken CDATA, and known macro body mismatches before contacting Confluence. Markdown input, including embedded storage blocks, goes through the same checks after conversion. See storage-format guidance for the validation limits and error-recovery workflow.

To inspect XML generated from Markdown, run confluence convert --body-file page.md --output-file generated.xml. The saved artifact remains available if validation fails. Ready-to-use code, expand, and noformat templates are built into the CLI. Agents can use the bundled Confluence skill; the upgrade and editing workflow explains installation, preserving the original body, and updating against its base version.

Read and explore

The direct commands cover everyday Confluence retrieval without requiring a sync directory:

confluence space list
confluence search 'on-call rotation' --space OPS
confluence page get 'OPS:Incident handbook' --show-body
confluence page tree 'OPS:Runbooks'
confluence blog list ENG

References accept a numeric content ID, a Confluence URL, or SPACE:Title. Search accepts plain text by default and full Confluence Query Language with --cql.

On a terminal, search results, lists, and page metadata are formatted for scanning. page get --show-body includes the canonical storage-format body for agents and transformations; Proof Desk turns that content into a readable page for humans.

When stdout is piped, data commands emit one JSON document:

confluence search 'release notes' --space DOCS \
  | jq '.items[] | {title, web_url}'

For an interactive reading experience, confluence tui opens Proof Desk on the first visible space. The --space option starts in a specific space, and o opens the selected page in Confluence.

Proof Desk TUI

Proof Desk is a keyboard-first, read-only workspace for reading and browsing Confluence. Add a local path when you also want to review a sync plan:

confluence tui
confluence tui --space DOCS
confluence tui --space DOCS --path ./docs/handbook

Browse mode combines the page hierarchy, a readable Markdown proof, and an outer margin for metadata, labels, attachments, comments, and content properties. Review mode presents the local plan and unified body diffs in the same layout.

The TUI never applies changes and does not contact Confluence to detect drift. confluence apply remains the separate, remote-aware write boundary. Passing --delete-remote only includes attachment deletions in the local review plan.

Wide terminals show all three regions. Compact terminals reveal complete proofs and margins on demand. Proof Desk requires interactive stdin and stdout and honors --no-color.

Edit and publish with Markdown

Pull

Export one page, a page tree, or an entire space:

confluence pull page 'DOCS:Getting Started' ./docs/getting-started
confluence pull tree 'DOCS:Handbook' ./docs/handbook
confluence pull space DOCS ./docs

Pulls are staged beside the destination and installed as one snapshot. A pull refuses to replace local Markdown changes or unmanaged files. Use --force only when the remote snapshot should replace the entire destination.

Filtered pull space --since ... exports require a new or empty destination because a partial result cannot safely replace a complete snapshot. Attachment names are confined to their page's attachments/ directory.

Edit

Each page has a predictable local layout:

<slug>--<content-id>/
├── index.md
├── .confluence.json
└── attachments/

The Markdown frontmatter contains editable metadata such as title, type, labels, status, and properties. Move a page directory beneath its desired local parent to reparent it; the parent frontmatter field is informational.

The sidecar records remote IDs, versions, hashes, and attachment mappings. It is the baseline that makes offline planning and drift detection possible.

Plan

confluence plan ./docs/handbook --diff

plan validates the complete tree and compares it with the state captured by pull. It never contacts Confluence and never writes remotely.

For an interactive review, open the same directory in the Proof Desk:

confluence tui --space DOCS --path ./docs/handbook

Apply

confluence apply ./docs/handbook

Before its first mutation, apply validates every local document and preflights every remote version. Versioned updates continue to reject drift that occurs during the apply. If an API failure leaves a partial remote mutation, the CLI reports the completed actions in structured error details so automation can reconcile safely.

Remote attachment deletions are opt-in with --delete-remote. Conditional overwrites require an explicit --force or --replace where supported.

Authentication

confluence init starts the guided login flow. It links to the appropriate token page, discovers scoped-token details, verifies access, and stores credentials in the operating-system keychain. New profiles start read-only unless you explicitly enable commands that change Confluence. Cloud and Data Center profiles share the same workflow.

Scripts and headless machines can use explicit profiles or environment-only credentials. See the authentication guide for Cloud, Data Center, CI, keychain, environment, and private certificate authority examples.

Command surface

Reading, browsing, direct updates, and Markdown publishing are all first-class:

On a terminal, --output auto produces readable text. When piped, data commands produce one JSON document. Agents can request one token-efficient, versioned command contract without loading the complete CLI surface:

confluence schema --command 'page get'

See the CLI reference for output modes, exit codes, shell completions, Markdown fidelity, and the complete command map.

Status and compatibility

The project is an early release, live-verified against Confluence Cloud and Data Center.

The deterministic simulator runs on every pull request. Protected live checks exercise real provider lifecycles. The testing guide explains the confidence model and automation.

Known limits

• Unknown provider-specific macros can behave differently between Cloud and Data Center; unsupported storage is preserved instead of silently flattened.
• apply refuses remote-version drift unless --force is explicit.

Documentation

• Authentication and profiles
• CLI, output, schema, and Markdown reference
• Testing and live-provider confidence
• Release and recovery runbook

Development and releases

make test           # deterministic unit, contract, and simulator tests
make release-check  # formatting, clippy, tests, smoke checks, and packaging

Live-provider tests and the local Data Center stack are documented in the testing guide.

License

MIT