DOCSEARCHbyAlgolia
Submit Docs

Confluence CLI

repository·main·Indexed 42 days ago

https://github.com/pchuri/confluence-cli

A command-line interface for Atlassian Confluence version 2.23.0 that enables reading, searching, managing, and automating content such as pages, spaces, attachments, and comments from the terminal. It features integration with Claude Code and Pi Coding Agent, supports multiple authentication methods (Basic, Bearer, mTLS, Cookie), and provides over 30 commands for content management and automation.

Tokens
29K
Snippets
119
Records
139
Agent score
54%

What's inside Confluence CLI

  1. Use .netrc for Secure Token Storage

    main

    To keep API tokens out of config.json while using basic or bearer authentication, you can use a ~/.netrc file. The CLI resolves tokens with the following precedence:

    1. Environment variable / --token flag
    2. Profile token in config.json
    3. .netrc entry

    Format for ~/.netrc (or ~/_netrc on Windows):

    For Basic Auth (requires machine to match domain and login to match email):

    machine your-domain.atlassian.net
  login your.email@example.com
  password your-api-token

    For Bearer Auth (only machine is matched):

    machine your-domain.atlassian.net
  password your-personal-access-token

    Note: .netrc does not support mtls, cookie, or none authentication types.

  2. Manage multiple Confluence instances with profiles

    main

    To switch between different Confluence environments (e.g., Production vs. Staging) without reconfiguring, use profiles.

    • Via CLI flag: Use --profile <name> in your command.
    • Via Environment Variable: Set CONFLUENCE_PROFILE=<name>.
    • Read-only protection: You can create a profile in read-only mode to prevent accidental writes. This can be done by setting CONFLUENCE_READ_ONLY=true or using the --read-only flag during profile creation. When a profile is in read-only mode, all write commands will be blocked at the CLI level.

  3. Use Markdown markers to create Confluence macros

    main

    When using confluence convert, create, or update, you can use specific Markdown paragraph-level markers to generate native Confluence macros. These markers are designed to round-trip cleanly between Markdown and Confluence storage format.

    Callout Macros (INFO, WARNING, NOTE)

    Use a blockquote where the first line is **INFO**, **WARNING**, or **NOTE**.

    > **INFO**
> This is an info box.

    Note: A plain blockquote > text without these markers will remain a standard HTML <blockquote> and not an alert macro.

    Table of Contents

    Use any of the following on their own line to create a Table of Contents macro:

    • **TOC**
    • [[_TOC_]]
    • <!-- _TOC_ -->
    • <!-- [[_TOC_]] -->

    Children Display

    Use any of the following on their own line to create a Children Display macro:

    • [[_LISTING_]]
    • <!-- _LISTING_ -->
    • <!-- [[_LISTING_]] -->

    Anchors

    Use **ANCHOR: id** on its own line to create a Confluence anchor macro with the specified ID.

    Expand (Collapsible) Macros

    Wrap content between **EXPAND: title** and **EXPAND_END** (each on its own paragraph) to create a collapsible section.

    **EXPAND: Show details**

This content is hidden until expanded.

**EXPAND_END**

    In-page Anchor Links

    Standard Markdown links starting with # (e.g., [text](#id)) are converted to ac:link with ac:anchor for in-page jumping.

    > **WARNING**
> This is a native Confluence warning macro.

**TOC**

**EXPAND: Click to expand**

Secret content here.

**EXPAND_END**

  4. Pi Coding Agent: Mutation Tool Approval Workflow

    main

    Certain destructive or bulk operations in Pi require a two-step 'preview and execute' workflow.

    1. Preview: Run a preview tool (e.g., confluence_copy_tree_preview or confluence_versions_purge_preview). This returns a one-use approvalId.
    2. Execute: Pass the approvalId to the corresponding execution tool.

    Constraints:

    • The approvalId expires after 5 minutes (300000 ms).
    • If the ID is expired, stale, or already used, you must run a new preview.

  5. How the confluence skill works in Claude Code

    main

    The plugin provides a model-invoked skill named confluence. Claude Code automatically activates this skill whenever a task involves Confluence. Once activated, the skill allows Claude to perform actions on your behalf using the underlying confluence-cli commands, including:

    • Reading and searching Confluence pages
    • Creating, updating, moving, or deleting pages
    • Managing attachments
    • Converting pages

    The skill covers all 30+ available CLI commands, handles configuration, manages common workflows, and processes error handling automatically.

  6. Enable Read-Only mode for safety

    main

    Read-only mode prevents any write operations (create, update, delete, move, etc.) at the CLI level. This is highly recommended when using the CLI with AI agents (like Claude Code or Copilot) to prevent accidental modifications.

    How to enable:

    1. During initialization: confluence init --read-only.
    2. When adding a profile: confluence profile add <name> ... --read-only.
    3. Via Environment Variable: export CONFLUENCE_READ_ONLY=true (this overrides profile settings).
    export CONFLUENCE_READ_ONLY=true

  7. Use JSON output for scripting and automation

    main

    Pass the global --json flag to any command to emit raw JSON to stdout. This is ideal for piping output to tools like jq.

    Supported Commands:

    • Read commands: info, search, spaces, find, children, versions, comments, attachments, property-list, property-get, property-set.
    • Write commands: create, create-child, update, move, delete, copy-tree, comment, comment-delete, property-delete, attachment-upload, attachment-delete, version-delete, versions-purge.

    Important Notes:

    • For destructive commands, --json requires the --yes flag to bypass interactive prompts.
    • Human-readable messages and warnings are sent to stderr, ensuring stdout contains only valid JSON.
    • The per-command --format json flag is deprecated; use the global --json flag instead.
    confluence search "release notes" --json | jq '.results[].title'
confluence spaces --json | jq -r '.spaces[].key'
confluence create "Notes" ENG --content "hi" --json | jq -r '.id'

  8. Perform a Read-Edit-Update round-trip on a Confluence page

    main

    To modify an existing Confluence page using local tools, follow this workflow:

    1. Fetch the raw content: Use edit with --output to save the page's storage XML locally.
    2. Modify the file: Use your preferred editor or tool to change the XML.
    3. Push the update: Use update with the --file flag and specify --format storage to ensure the content is treated as Confluence storage format.

    Note: This workflow requires the page to have a storage body. For folders or bodyless content, use confluence info <id> instead.

    # 1. Fetch raw storage XML
confluence edit 123456789 --output ./page.xml

# 2. Modify page.xml with your tool of choice

# 3. Push the updated content
confluence update 123456789 --file ./page.xml --format storage

  10. Export a page and its attachments for local editing

    main

    Use export to download a page and its associated attachments to a local directory. The command creates a directory structure containing the page's markdown file and an attachments/ folder.

    confluence export 123456789 --format markdown --dest ./local-docs
# => ./local-docs/<page-title>/page.md + ./local-docs/<page-title>/attachments/

  11. Configure Scoped API Tokens for Atlassian Cloud

    main

    Scoped tokens are recommended for agents and automation to follow the principle of least privilege. They use the api.atlassian.com gateway instead of your site domain.

    Setup Steps:

    1. Create a scoped token in Atlassian Admin settings.
    2. Find your Cloud ID by visiting https://<your-site>.atlassian.net/_edge/tenant_info.
    3. Configure the CLI with these specific settings:
      • Domain: api.atlassian.com
      • API Path: /ex/confluence/<your-cloud-id>/wiki/rest/api
      • Auth Type: basic (using your email and the scoped token)

    Required Scopes Reference:

    ScopePurpose
    read:confluence-content.allReading pages and blog posts
    read:confluence-content.summaryReading content summaries and metadata
    read:confluence-space.summaryListing spaces
    search:confluenceSearching content
    readonly:content:attachment:confluenceDownloading attachments
    write:confluence-contentCreating and updating pages
    write:confluence-fileUploading attachments
    write:confluence-spaceManaging spaces
    read:hierarchical-content:confluenceListing folders (required for children --type folders)

  12. Configure Confluence CLI via Non-interactive Flags

    main

    For CI/CD pipelines, Docker builds, or AI agents, you can provide all configuration via command-line flags during initialization. This avoids interactive prompts.

    Common usage patterns:

    • Complete setup: Provide domain, API path, auth type, email, and token.
    • Scoped API token (Recommended for agents): Use the Atlassian API gateway (api.atlassian.com) and a specific API path containing your Cloud ID for least-privilege access.
    • Named profiles: Use the --profile <name> flag to save configuration under a specific identifier (e.g., staging or corp).
    • mTLS: Provide paths to client certificates and keys.
    • Cookie/SSO: Provide session cookies for Enterprise SSO environments.
    • Hybrid mode: Provide some flags and let the CLI prompt for the remaining required fields.
    # Complete non-interactive mode
confluence init \
  --domain "company.atlassian.net" \
  --api-path "/wiki/rest/api" \
  --auth-type "basic" \
  --email "user@example.com" \
  --token "your-api-token"

# Named profile for mTLS
confluence --profile corp init \
  --domain "docs.example.com" \
  --api-path "/confluence/rest/api" \
  --auth-type "mtls" \
  --tls-client-cert "~/.certs/client.pem" \
  --tls-client-key "~/.certs/client.key" \
  --tls-ca-cert "~/.certs/ca-chain.pem"