Confluence

Confluence

Interact with Confluence for content search, viewing pages, and space management.

Creating/Updating Content? See references/creating-content.md for page creation and updates with Markdown.

Installation

Dependencies: pip install --user requests keyring pyyaml

Setup Verification

After installation, verify the skill is properly configured:

$SKILL_DIR/scripts/confluence.py check

This will check:

• Python dependencies (requests, keyring, pyyaml)
• Authentication configuration
• Connectivity to Confluence
• Deployment type detection (Cloud vs Data Center/Server)

If anything is missing, the check command will provide setup instructions.

Authentication

Configure Confluence authentication using one of these methods:

Option 1: Environment Variables (Recommended)

export CONFLUENCE_URL="https://yourcompany.atlassian.net/wiki"
export CONFLUENCE_EMAIL="you@example.com"
export CONFLUENCE_API_TOKEN="your-token"

Add these to your ~/.bashrc or ~/.zshrc for persistence.

Option 2: Config File

Create ~/.config/agent-skills/confluence.yaml:

url: https://yourcompany.atlassian.net/wiki
email: you@example.com
token: your-token

Required Credentials

• URL: Your Confluence instance URL
• Cloud: https://yourcompany.atlassian.net/wiki
• DC/Server: https://confluence.yourcompany.com
• Email: Your account email (required for Cloud)
• API Token: Create at https://id.atlassian.com/manage-profile/security/api-tokens (Cloud) or from your Confluence profile (DC/Server)

Configuration Defaults

Optionally configure defaults in ~/.config/agent-skills/confluence.yaml to reduce repetitive typing:

# Authentication (optional if using environment variables)
url: https://yourcompany.atlassian.net/wiki
email: you@example.com
token: your-token

# Optional defaults
defaults:
  cql_scope: "space = DEMO"
  max_results: 25
  default_space: "DEMO"

How Defaults Work

• CLI arguments always override config defaults
• CQL scope is prepended to all searches: (scope) AND (your_query)
• Default space is used when space parameter is omitted

View Configuration

# Show all configuration
$SKILL_DIR/scripts/confluence.py config show

# Show space-specific defaults
$SKILL_DIR/scripts/confluence.py config show --space DEMO

Commands

See permissions.md for read/write classification of each command.

check

Verify configuration and connectivity.

$SKILL_DIR/scripts/confluence.py check

This validates:

• Python dependencies are installed
• Authentication is configured
• Can connect to Confluence
• Deployment type (Cloud vs DC/Server) is detected correctly

search

Search for content using CQL (Confluence Query Language).

# Basic search
$SKILL_DIR/scripts/confluence.py search "type=page AND space = DEMO"
$SKILL_DIR/scripts/confluence.py search "title~login" --space DEMO

# Filter by type
$SKILL_DIR/scripts/confluence.py search "space = DEMO" --type page

# Limit results
$SKILL_DIR/scripts/confluence.py search "type=page" --max-results 10

Arguments:

• cql: CQL query string (required)
• --max-results: Maximum number of results (default: 50)
• --type: Content type filter (page, blogpost, comment)
• --space: Limit to specific space

See also: CQL Reference for query syntax

page get

Get page content by ID or title.

# Get by title (returns Markdown by default)
$SKILL_DIR/scripts/confluence.py page get "My Page Title"

# Get by ID
$SKILL_DIR/scripts/confluence.py page get 123456

# Get without body content
$SKILL_DIR/scripts/confluence.py page get "My Page" --no-body

# Get in original format (not Markdown)
$SKILL_DIR/scripts/confluence.py page get "My Page" --raw

# Export with YAML frontmatter (for round-tripping)
$SKILL_DIR/scripts/confluence.py page get 123456 --frontmatter > page.md

Output: By default, displays page metadata and body content converted to Markdown for readability.

Arguments:

• page_identifier: Page ID or title (required)
• --markdown: Output body as Markdown (default)
• --raw: Output in original format
• --no-body: Don't include body content
• --frontmatter: Output as markdown with YAML frontmatter (title, space, labels, parent) for round-tripping with page create/page update

Example Output

$ $SKILL_DIR/scripts/confluence.py page get "API Documentation"

Page ID: 123456
Title: API Documentation
Type: page
Space: DEMO
Status: current
Version: 1

---

# API Documentation

## Overview

This document describes our **REST API**.

## Endpoints

- `GET /api/users` - List users
- `POST /api/users` - Create user

page create / update

For creating and updating pages with Markdown support, see references/creating-content.md.

Quick examples:

# Create page from Markdown file
$SKILL_DIR/scripts/confluence.py page create --space DEMO --title "Documentation" \
  --body-file README.md

# Create page with table of contents
$SKILL_DIR/scripts/confluence.py page create --space DEMO --title "Guide" \
  --body-file guide.md --toc

# Update page from file
$SKILL_DIR/scripts/confluence.py page update 123456 --body-file updated.md

Frontmatter support: Markdown files can include YAML frontmatter with page metadata. CLI flags take precedence over frontmatter values. Supported fields: title, space, labels, parent, toc.

---
title: API Documentation
space: DEMO
labels: docs, api
parent: 123456
toc: true
---

# Introduction
...

Table of contents: Use --toc (or toc: true in frontmatter) to prepend a TOC macro.

Internal link conversion: Links pointing to pages on the same Confluence instance are automatically converted to native Confluence links during markdown conversion. The linked page is validated before conversion — invalid links are left as-is.

page move

Move a page under a new parent, or to the space root.

# Move under a new parent
$SKILL_DIR/scripts/confluence.py page move 123456 --parent 789012

# Move to space root (no parent)
$SKILL_DIR/scripts/confluence.py page move 123456

page delete

Delete a page by ID (moves to trash on Cloud).

$SKILL_DIR/scripts/confluence.py page delete 123456

space

Manage spaces.

# List all spaces
$SKILL_DIR/scripts/confluence.py space list

# List with limit
$SKILL_DIR/scripts/confluence.py space list --max-results 10

# Filter by type
$SKILL_DIR/scripts/confluence.py space list --type global

# Get space details
$SKILL_DIR/scripts/confluence.py space get DEMO

Arguments:

• list: List spaces
• --type: Filter by type (global, personal)
• --max-results: Maximum results
• get <space-key>: Get space details

For creating spaces, see references/creating-content.md.

space permissions

View, add, and remove space permissions.

# List all permissions for a space
$SKILL_DIR/scripts/confluence.py space permissions list DEMO

# Filter by subject type
$SKILL_DIR/scripts/confluence.py space permissions list DEMO --subject-type group

# Add a permission
$SKILL_DIR/scripts/confluence.py space permissions add DEMO \
  --subject-type user --subject "5a1234abc" --operation read --target space

# Remove a permission by ID
$SKILL_DIR/scripts/confluence.py space permissions remove DEMO --id 2154

Arguments:

• list <space-key>: List permissions
• --subject-type: Filter by user or group
• add <space-key>: Add a permission
• --subject-type: user or group (required)
• --subject: User account ID or group name/ID (required)
• --operation: read, create, delete, export, administer, archive, restrict_content (required)
• --target: space, page, blogpost, comment, attachment (required)
• remove <space-key>: Remove a permission
• --id: Permission ID (required)

config

Show configuration and defaults.

# Show all configuration
$SKILL_DIR/scripts/confluence.py config show

# Show space-specific defaults
$SKILL_DIR/scripts/confluence.py config show --space DEMO

This displays:

• Authentication settings (with masked token)
• Default CQL scope, max results, and default space
• Space-specific defaults for parent pages and labels

Examples

Search for Pages

# Find pages in a space
$SKILL_DIR/scripts/confluence.py search "type=page AND space = DEMO"

# Search by title
$SKILL_DIR/scripts/confluence.py search "title~login"

# Find recent pages
$SKILL_DIR/scripts/confluence.py search "type=page AND created >= now('-7d')"

View Page Content

# View page as Markdown
$SKILL_DIR/scripts/confluence.py page get "My Page Title"

# View page metadata only
$SKILL_DIR/scripts/confluence.py page get 123456 --no-body

# Export to file
$SKILL_DIR/scripts/confluence.py page get "My Page" > exported-page.md

List and Explore Spaces

# List all spaces
$SKILL_DIR/scripts/confluence.py space list

# Get details about a space
$SKILL_DIR/scripts/confluence.py space get DEMO

Using Configuration Defaults

With defaults configured as shown in the Configuration Defaults section:

# Search uses CQL scope automatically
$SKILL_DIR/scripts/confluence.py search "type=page"
# Becomes: (space = DEMO) AND (type=page)

# Search with automatic max_results from config
$SKILL_DIR/scripts/confluence.py search "status=current"
# Uses configured max_results (25) automatically

# Override defaults when needed
$SKILL_DIR/scripts/confluence.py search "type=page" --max-results 100
# CLI argument overrides the configured default of 25

CQL Reference

Common CQL (Confluence Query Language) queries:

Combine with AND, OR, and use ORDER BY for sorting:

$SKILL_DIR/scripts/confluence.py search "type=page AND space=DEMO AND created >= now('-30d') ORDER BY created DESC"

Model Guidance

This skill makes API calls requiring structured input/output. A standard-capability model is recommended.

Troubleshooting

Check command fails

Run $SKILL_DIR/scripts/confluence.py check to diagnose issues. It will provide specific error messages and setup instructions.

Authentication failed

1. Verify your API token is correct 2. Ensure you're using your email (not username) for Cloud instances 3. For Cloud, use your Atlassian account email 4. For Data Center/Server, you may need username/password or Bearer token

Permission denied

You may not have access to the requested space or page. Contact your Confluence administrator.

CQL syntax error

Test your CQL query in the Confluence web interface search before using it in the CLI.

Page not found

When searching by title, ensure the title is exact (case-sensitive). You can use:

• Exact title: $SKILL_DIR/scripts/confluence.py page get "Exact Page Title"
• Page ID: $SKILL_DIR/scripts/confluence.py page get 123456

Import errors

Ensure dependencies are installed:

pip install --user requests keyring pyyaml

Cloud vs Data Center/Server

The skill automatically detects your Confluence deployment type and adapts:

• Cloud (atlassian.net): Uses /wiki/rest/api and editor format (ADF)
• Data Center/Server: Uses /rest/api and storage format (XHTML)

When reading pages, content is automatically converted to Markdown for display regardless of deployment type.

Creating and Updating Confluence Content

This guide covers creating and updating Confluence pages using Markdown.

Note: Most users primarily read from Confluence. For basic usage (search, viewing pages, listing spaces), see the main SKILL.md.

Markdown Support

The Confluence skill uses Markdown as the default format for page content, making it easy to create and read pages.

Supported Markdown Features

• Headers: # through ######
• Bold: **text** or __text__
• Italic: *text* or _text_
• Code: \inline code\
• Code blocks: \\\language ... \\\
• Lists: Unordered (- or *) and ordered (1.)
• Links: [text](url)

Format Conversion

The skill automatically converts between formats:

• Cloud instances: Markdown → ADF (Atlassian Document Format)
• DC/Server instances: Markdown → Storage format (XHTML)
• Reading: Storage/ADF → Markdown (for display)

You can override the automatic format with --format:

# Use storage format directly
python confluence.py page create --space DEMO --title "Page" \
  --body "<p>HTML content</p>" --format storage

# Use editor format (ADF) directly
python confluence.py page create --space DEMO --title "Page" \
  --body '{"type":"doc","content":[...]}' --format editor

Creating Pages

Basic Page Creation

# Create page with inline Markdown
python confluence.py page create --space DEMO --title "New Page" \
  --body "# Heading\n\nThis is **bold** text."

# Create from Markdown file
python confluence.py page create --space DEMO --title "Documentation" \
  --body-file README.md

# Create with parent page
python confluence.py page create --space DEMO --title "Child Page" \
  --body "Content here" --parent 123456

# Create with labels
python confluence.py page create --space DEMO --title "Tagged Page" \
  --body "Content" --labels "important,draft"

Arguments:

• --space: Space key (required)
• --title: Page title (required)
• --body: Page content (Markdown by default)
• --body-file: Read content from file (Markdown)
• --format: Input format - markdown (default), storage, editor
• --parent: Parent page ID for hierarchy
• --labels: Comma-separated labels
• --json: Output as JSON

Example: Creating Rich Content

python confluence.py page create --space DEMO --title "API Documentation" --body "
# API Documentation

## Overview

This document describes our **REST API**.

## Endpoints

- \`GET /api/users\` - List users
- \`POST /api/users\` - Create user

## Example

\`\`\`python
import requests
response = requests.get('https://api.example.com/users')
\`\`\`

See [official docs](https://docs.example.com) for more.
"

Creating from Markdown Files

# Use existing README as Confluence page
python confluence.py page create --space DEMO --title "Project README" \
  --body-file README.md

Updating Pages

Basic Updates

# Update page content
python confluence.py page update 123456 --body "# Updated\n\nNew content"

# Update from file
python confluence.py page update 123456 --body-file updated.md

# Update title only
python confluence.py page update 123456 --title "New Title"

# Update with specific version (prevents conflicts)
python confluence.py page update 123456 --body "Content" --version 5

# Update using storage format
python confluence.py page update 123456 --body "<p>HTML</p>" --format storage

Arguments:

• page_id: Page ID to update (required)
• --title: New title
• --body: New content (Markdown by default)
• --body-file: Read content from file (Markdown)
• --format: Input format - markdown (default), storage, editor
• --version: Current version number (auto-detected if not provided)
• --json: Output as JSON

Note: Version is auto-detected, but you can specify it to ensure you're updating the correct version.

Handling Version Conflicts

If you get a version conflict when updating, the page was modified since you last viewed it. Get the latest version:

# Get current version
python confluence.py page get 123456 --no-body

# Update with correct version
python confluence.py page update 123456 --body "Content" --version 5

Or let the tool auto-detect the version:

python confluence.py page update 123456 --body "Content"

Creating Spaces

# Create new space
python confluence.py space create --key PROJ --name "Project Space"

# Create with description
python confluence.py space create --key PROJ --name "Project Space" \
  --description "Documentation for the project"

# JSON output
python confluence.py space create --key PROJ --name "Project" --json

Arguments:

• --key: Space key (required)
• --name: Space name (required)
• --description: Space description
• --type: Space type (global, personal)
• --json: Output as JSON

Advanced Examples

Batch Page Creation

#!/bin/bash
# Create multiple pages from a directory

SPACE="DOCS"
PARENT="123456"

for file in docs/*.md; do
    title=$(basename "$file" .md)
    python confluence.py page create \
        --space "$SPACE" \
        --title "$title" \
        --body-file "$file" \
        --parent "$PARENT"
done

Create Documentation from Files

# Create main page
python confluence.py page create --space DOCS --title "Main Documentation" \
  --body-file README.md

# Create sub-pages
python confluence.py page create --space DOCS --title "API Reference" \
  --body-file docs/api.md --parent 123456

python confluence.py page create --space DOCS --title "Installation Guide" \
  --body-file docs/install.md --parent 123456

Update Existing Page

# Update from file
python confluence.py page update 123456 --body-file updated-docs.md

# Update title
python confluence.py page update 123456 --title "Updated Title"

# Update both
python confluence.py page update 123456 --title "New Title" --body-file content.md

Configuration Defaults for Page Creation

Optionally configure space-specific defaults in ~/.config/agent-skills/confluence.yaml:

# Optional space-specific defaults
spaces:
  DEMO:
    default_parent: "123456"  # Parent page ID
    default_labels: ["auto-created"]
  PROD:
    default_parent: "789012"

When creating pages in configured spaces, these defaults are automatically applied:

# Create page uses space defaults
python confluence.py page create --space DEMO --title "New Page" --body "Content"
# Automatically uses default_parent and default_labels from DEMO space defaults

Cloud vs Data Center/Server

The skill automatically detects your Confluence deployment type and adapts:

• Cloud (atlassian.net): Uses /wiki/rest/api and editor format (ADF)
• Data Center/Server: Uses /rest/api and storage format (XHTML)

Markdown conversion works seamlessly on both:

• Your Markdown input → Appropriate format for your deployment
• API responses → Converted to Markdown for display

You don't need to worry about the internal formats unless you want to use --format storage or --format editor explicitly.

Command Permissions

This reference classifies commands by access level to help agents enforce appropriate permission controls.

• read: Safe to execute without user confirmation. These commands

only retrieve or display information.

• write: Requires user confirmation before execution. These

commands create, modify, or delete data.