Confluence

Confluence CLI

Command-line tool for managing Confluence pages via af confluence.

Setup

Add the following environment variables to your project's .env file (preferred names first; legacy JIRA_* names are still accepted and fall back to these when unset):

• ATLASSIAN_BASE_URL — Your Atlassian instance URL (e.g., https://company.atlassian.net)
• ATLASSIAN_EMAIL — Your Atlassian account email
• ATLASSIAN_API_TOKEN — API token from https://id.atlassian.com/manage-profile/security/api-tokens

Uses the same Atlassian credentials as the Jira skill.

Project Defaults

If the project instructions specify a default Confluence space key (e.g., Confluence space: TEAM), use it as the default for --space, list, and CQL queries. Explicit user input always overrides the default.

Quick Reference

Run bare af confluence (no subcommand) for the full command and flag reference. Note af confluence --help is intercepted by af's router and prints only a short stub.

--limit N is a global option (default: 50). Every result-listing subcommand honours it — list, search, tree, comments, labels, attachments, and spaces.

Read Operations

• af confluence get <page-id> — Get page content and metadata
• af confluence list <space-key> [--limit N] — List pages in a space
• af confluence search "<cql>" [--limit N] — Search with CQL
• af confluence tree <page-id> [--limit N] — Show page and its children (--limit caps the children listed)
• af confluence comments <page-id> [--limit N] — List comments on a page
• af confluence labels <page-id> [--limit N] — List labels on a page
• af confluence attachments <page-id> [--limit N] — List attachments on a page
• af confluence spaces [--limit N] — List all spaces
• af confluence space <space-key> — Get space details

Write Operations

• af confluence create --space <key> --title "<text>" [--body "<text>"] [--body-file <path>] [--parent <page-id>] [--status draft|current]
• af confluence update <page-id> [--title "<text>"] [--body "<text>"] [--body-file <path>] [--status draft|current] [--message "<text>"]
• af confluence delete <page-id>
• af confluence comment <page-id> --add "<text>"
• af confluence label <page-id> --add "<name>[,<name>...]" — Comma-separated list adds several labels in one call
• af confluence label <page-id> --remove "<name>" — One label at a time (not comma-split)
• af confluence attach <page-id> <file> — Upload an attachment

Output Formats

• Default: Markdown
• JSON: Add --json flag

Common Workflows

Publish a document from a file

af confluence create --space TEAM --title "Architecture Decision Record" \
  --body-file ./docs/adr-001.md

Create a child page under an existing page

# Find the parent page ID first
af confluence search "title = 'Engineering Wiki' AND space = TEAM"

# Create child page
af confluence create --space TEAM --title "Onboarding Guide" \
  --body-file ./onboarding.md --parent 12345

Update a page from a file with a version message

af confluence update 12345 --body-file ./updated-doc.md \
  --message "Revised after Q1 review"

Create a draft page

af confluence create --space TEAM --title "RFC: New Auth System" \
  --body-file ./rfc.md --status draft

Browse a page tree

# See a page and all its children
af confluence tree 12345

Work with comments

# List comments
af confluence comments 12345

# Add a comment
af confluence comment 12345 --add "Reviewed — looks good to merge"

Manage labels

# List labels
af confluence labels 12345

# Add a label
af confluence label 12345 --add "reviewed"

# Add several labels in one call (comma-separated)
af confluence label 12345 --add "reviewed,architecture,q1-roadmap"

# Remove a label (one at a time — --remove is not comma-split)
af confluence label 12345 --remove "draft"

# Bulk label: add to multiple pages
for id in 12345 12346 12347; do
  af confluence label "$id" --add "q1-roadmap"
done

Attach files

# Attach a diagram
af confluence attach 12345 ./architecture.png

# Attach multiple files
for f in ./diagrams/*.png; do
  af confluence attach 12345 "$f"
done

Search examples

# Pages in a space
af confluence search "space = TEAM" --limit 20

# Pages by title
af confluence search "title = 'Meeting Notes'"

# Pages with a specific label
af confluence search "label = 'architecture'"

# Recently modified pages
af confluence search "space = TEAM AND lastModified > now('-7d')"

# Pages containing specific text
af confluence search "text ~ 'deployment process'"

# Pages by creator
af confluence search "creator = currentUser() AND space = TEAM"

Tips

• Discover first: Run af confluence spaces to find space keys, af confluence list <space> to browse pages
• Use --body-file for real content: Inline --body is fine for short pages; use --body-file for anything substantial
• Quote CQL queries: Always wrap CQL in double quotes to handle spaces and operators
• CQL syntax: Uses = for exact match, ~ for contains, AND/OR for combining. See Atlassian CQL docs for full syntax
• Use --json for scripting: Pipe output to jq for automation

Error Handling

• Errors print to stderr
• With --json, API/client failures are wrapped as {"error": "message"}. Argument-validation failures (missing page ID, missing --add, etc.) ignore --json and print plain text — don't assume stderr is always parseable JSON
• Exit codes: 0 success, 1 error