magnus919_agent-skills/confluence-cli/SKILL.md

name, description, license, compatibility, metadata

name	description	license	compatibility	metadata
confluence-cli	Interact with Atlassian Confluence from the terminal: list spaces, browse pages, view page content, search with CQL, and create pages. Use when the user mentions Confluence, a space key (e.g. DEV), or asks about documentation, wiki pages, space content, or knowledge base articles. Do not use this skill for unrelated requests; route to the nearest named specialist.	MIT	Requires CONFLUENCE_EMAIL and CONFLUENCE_API_TOKEN env vars (free from id.atlassian.com/manage/api-tokens), Python 3.8+, and the `requests` library. Also requires CONFLUENCE_SERVER (defaults to your-domain.atlassian.net).	tags sources confluence, atlassian, wiki, documentation, knowledge-base, api-client https://developer.atlassian.com/cloud/confluence/rest/v2/, https://id.atlassian.com/manage/api-tokens

confluence-cli — Confluence Wiki from the Terminal

Interact with Atlassian Confluence Cloud via the REST API. List spaces, browse pages, view page content with body, search with CQL, and create pages.

Setup

1. Generate an API token at id.atlassian.com/manage/api-tokens
2. Set environment variables:

export CONFLUENCE_EMAIL="your-email@example.com"
export CONFLUENCE_API_TOKEN="your-api-token"
export CONFLUENCE_SERVER="https://your-domain.atlassian.net"

--help and --dry-run work without credentials.

Essential Commands

me — Current user profile

confluence-cli me                       # your account info
confluence-cli me --json                # machine-readable

spaces — List spaces

confluence-cli spaces                   # all accessible spaces
confluence-cli spaces --limit 50        # more results
confluence-cli spaces --json            # machine-readable

pages — List pages

confluence-cli pages                                # recent pages across all spaces
confluence-cli pages --space DEV                    # pages in a specific space
confluence-cli pages --space DEV --limit 10          # top 10
confluence-cli pages --space DEV --json             # machine-readable

Filters by space key. Resolves the key to an internal ID automatically.

view — View a page by ID

confluence-cli view 123456                   # full page with body
confluence-cli view 123456 --json            # machine-readable

Shows title, status, version, author, timestamps, and HTML body (stripped to plain text for display). The full HTML body is available in --json output up to 5000 chars.

search — Search with CQL

confluence-cli search --cql 'text~"deploy"'              # full-text search
confluence-cli search --cql 'space=DEV AND type=page'    # by space and type
confluence-cli search --cql 'creator=currentuser()'      # my content
confluence-cli search --cql 'text~"api"' --limit 5       # top 5 results

CQL (Confluence Query Language) is Confluence's search syntax. Common patterns:

• text~"keyword" — full-text search
• space=KEY — filter by space
• type=page — filter by content type
• creator=currentuser() — your content
• label="name" — by label
• Combine with AND: space=DEV AND text~"deploy"

create — Create a page

confluence-cli create --space DEV --title "My Page"                             # basic
confluence-cli create --space DEV --title "API Docs" --body "<p>Content</p>"    # with HTML body
confluence-cli create --space DEV --title "Test" --parent 123456                # as child page
confluence-cli create --space DEV --title "Test" --dry-run                      # preview

Creates pages in Confluence Cloud (v2 API). The body is HTML using Confluence's storage format. For simple pages, basic HTML tags work (<p>, <ul>, <h2>, etc.).

Global Flags

All flags work in any position:

confluence-cli --json pages --space DEV              # flag before subcommand
confluence-cli pages --space DEV --json              # flag after subcommand
confluence-cli --dry-run create --space DEV --title "Test"
confluence-cli --quiet pages                         # suppress non-essential output

Known Gotchas

• Authentication uses HTTP Basic Auth with email + API token. Same credentials as Jira, but stored under different env var names.
• Two API versions — The CLI uses v2 API for most operations (spaces, pages, create) and the legacy rest API for me and search (CQL). This is transparent to the user.
• Space keys must be resolved to IDs — The v2 API requires numeric space IDs for filtering. The CLI resolves keys automatically, which costs one extra API call on pages --space and create --space.
• Page body is HTML — The Confluence storage format uses HTML. The CLI strips HTML tags for display and returns raw HTML in --json output (up to 5000 chars). Creating pages with rich formatting requires valid HTML.
• CQL search quirks — CQL is case-insensitive for most operators. The text~ operator searches the full text body. Enclose multi-word phrases in escaped quotes.
• Rate limits — Confluence Cloud has rate limits. The CLI does not auto-retry.

References

• scripts/confluence-cli — The CLI binary. Built following the cli-builder patterns: non-interactive, --json, --dry-run, --quiet, --verbose, dual-output via emit(), lazy auth, structured logging.
• Confluence REST API v2 docs — Official API reference.
• CQL (Confluence Query Language) — Search syntax reference.
• API Token Management — Generate and revoke tokens.