confluence-search

Confluence Search Skill

Search Confluence content using CQL (Confluence Query Language).

---

⚠️ PRIMARY USE CASE

This skill finds content across Confluence. Use this skill for:

• Searching pages by text, title, or labels
• Building CQL queries for complex searches
• Exporting search results to CSV/JSON
• Finding content by date, creator, or space

This is a read-only skill - it cannot create, modify, or delete content.

---

When to Use This Skill

Trigger	Example
Text search	"Find pages about API documentation"
Label search	"Find all pages with label 'approved'"
Space search	"Search for content in DOCS space"
Date-based	"Find pages modified this week"
Export	"Export all pages in KB space to CSV"
CQL query	"Run CQL: space = DOCS AND type = page"

---

When NOT to Use This Skill

Operation	Use Instead
Create/edit pages	confluence-page
Add/remove labels	confluence-label
Manage permissions	confluence-permission
View page hierarchy	confluence-hierarchy

---

Risk Levels

All operations are read-only with no risk:

Operation	Risk	Notes
Search content	-	Read-only
Validate CQL	-	Read-only
Export results	-	Creates local file only
View history	-	Local history only

---

Overview

This skill provides powerful search capabilities:

• Execute CQL queries
• Validate CQL syntax
• Get field and value suggestions
• Interactive query builder
• Export results to CSV/JSON
• Streaming export for large result sets
• Query history management

CQL Query Patterns

Basic Queries

# Find pages in a space
space = "DOCS" AND type = page

# Find by label
label = "documentation"

# Text search
text ~ "API documentation"

# By creator
creator = "john.doe@company.com"
creator = currentUser()

# By date
created >= "2024-01-01"
lastModified > startOfMonth()

Advanced Queries

# Multiple spaces
space in ("DOCS", "KB", "DEV") AND type = page

# Exclude labels
label = "approved" AND label != "draft"

# Date ranges
lastModified >= "2024-01-01" AND lastModified < "2024-02-01"

# Ancestor (child pages)
ancestor = 12345

# Combined with ordering
space = "DOCS" AND label = "api" ORDER BY lastModified DESC

# Content with attachments
type = attachment AND container.space = "DOCS"

# Blog posts by date
type = blogpost AND created >= startOfYear()

CQL Fields Reference

Field	Description	Example
space	Space key	space = "DOCS"
title	Page title	title ~ "API"
text	Full text search	text ~ "configuration"
type	Content type	type = page
label	Content label	label = "docs"
creator	Content creator	creator = currentUser()
contributor	Any contributor	contributor = "email"
created	Creation date	created >= "2024-01-01"
lastModified	Last modified date	lastModified > startOfWeek()
parent	Parent page ID	parent = 12345
ancestor	Ancestor page ID	ancestor = 12345
id	Content ID	id = 12345

CLI Commands

confluence search cql

Execute CQL queries against Confluence.

Usage:

# Simple text search
confluence search cql "text ~ 'API documentation'"

# Search with space filter
confluence search cql "space = 'DOCS' AND type = page"

# With limit
confluence search cql "label = 'approved'" --limit 50

# Show excerpts
confluence search cql "text ~ 'config'" --show-excerpts

Arguments:

• cql - CQL query string (required)
• --limit, -l - Maximum results (default: 25)
• --show-excerpts - Show content excerpts
• --show-labels - Show content labels
• --show-ancestors - Show ancestor pages
• --output, -o - Output format: text or json

confluence search validate

Validate CQL query syntax.

Usage:

confluence search validate "space = 'DOCS' AND type = page"
confluence search validate "invalid query (("

Arguments:

• cql - CQL query to validate (required)

confluence search suggest

Get CQL field and value suggestions.

Usage:

# Get field suggestions
confluence search suggest --fields

# Get values for a field
confluence search suggest --field space
confluence search suggest --field type

# Get operators and functions
confluence search suggest --operators
confluence search suggest --functions

Arguments:

• --fields - List all available CQL fields
• --field NAME - Get values for a specific field
• --operators - List all CQL operators
• --functions - List all CQL functions
• --output, -o - Output format: text or json

confluence search interactive

Interactive CQL query builder.

Usage:

confluence search interactive
confluence search interactive --space DOCS
confluence search interactive --type page --execute

Arguments:

• --space - Pre-filter by space
• --type - Pre-filter by content type: page, blogpost, comment, or attachment
• --limit, -l - Maximum results (default: 25)
• --execute - Execute query after building

confluence search export

Export search results to file.

Usage:

# Export to CSV
confluence search export "space = 'DOCS'" --format csv --output results.csv

# Export to JSON
confluence search export "label = 'api'" --format json --output results.json

# Select columns
confluence search export "type = page" --columns id,title,space,created

Arguments:

• cql - CQL query (required)
• --format, -f - Output format: csv or json (default: csv)
• --output, -o - Output file path (required)
• --columns - Columns to include (comma-separated)
• --limit, -l - Maximum results

confluence search stream-export

Export large result sets with checkpoints.

Usage:

# Full export with progress
confluence search stream-export "space = 'DOCS'" --output docs.csv

# Resume from checkpoint
confluence search stream-export "space = 'DOCS'" --output docs.csv --resume

# Custom batch size
confluence search stream-export "type = page" --output pages.csv --batch-size 50

Arguments:

• cql - CQL query (required)
• --output, -o - Output file path (required)
• --format, -f - Output format: csv or json (inferred from extension if not specified)
• --columns - Columns to include (comma-separated)
• --batch-size - Records per batch (default: 100)
• --resume - Resume from last checkpoint

confluence search history

Manage local query history.

Usage:

# List recent queries
confluence search history list
confluence search history list --limit 10

# Search history
confluence search history search "space = DOCS"

# Show specific query by index
confluence search history show 5

# Clear history
confluence search history clear

# Export history to file
confluence search history export history.csv
confluence search history export history.json --format json

# Cleanup old entries
confluence search history cleanup --days 30

Subcommands:

• list - List recent queries (--limit default: 20, --output)
• search KEYWORD - Search history for queries containing keyword
• show INDEX - Show specific query by index
• clear - Clear all query history
• export FILE - Export history to file (--format: csv or json)
• cleanup - Remove old entries (--days default: 90)

confluence search content

Simple text search (no CQL knowledge required).

Usage:

confluence search content "meeting notes"
confluence search content "meeting notes" --space DOCS
confluence search content "API documentation" --type page

Arguments:

• query - Search text (required)
• --space - Limit to space
• --type - Content type: page, blogpost, or all
• --limit, -l - Maximum results
• --output, -o - Output format

Examples

Natural Language Triggers

• "Search for pages about API documentation"
• "Find all pages with label 'approved' in DOCS space"
• "Search for content created this month"
• "Export all pages in KB space to CSV"
• "Find pages modified by me today"

---

Common Pitfalls

1. CQL Syntax Errors

• Problem: Query fails with syntax error
• Solution: Use confluence search validate "query" to check syntax first

2. Quoting Issues

• Problem: Values with spaces not matching
• Solution: Use double quotes: space = "My Space" or single quotes: label = 'my-label'

3. Case Sensitivity

• Problem: Search not finding expected results
• Solution: Text search (~) is case-insensitive, but = is exact match

4. Date Format

• Problem: Date queries failing
• Solution: Use YYYY-MM-DD format or functions like startOfWeek(), now("-7d")

5. Large Result Sets

• Problem: Export timing out or running slow
• Solution: Use stream-export for large datasets, add --batch-size option

6. Empty Results

• Problem: Search returns nothing when content exists
• Solution: Check space permissions, verify space key is correct, try broader query

---

Error Handling

Error	Cause	Resolution
400 Bad Request	Invalid CQL syntax	Use confluence search validate to check query
403 Forbidden	No permission to search space	Request space access
408 Timeout	Query too complex or large result set	Simplify query, use pagination

CQL Troubleshooting

Validate query before running:

confluence search validate "space = 'DOCS' AND type = page"

Build query interactively:

confluence search interactive --space DOCS

Check available fields:

confluence search suggest --fields
confluence search suggest --field space

Common CQL fixes:

# Wrong: unquoted space with spaces
space = My Space

# Right: quoted space name
space = "My Space"

# Wrong: wrong date format
created > 01-15-2025

# Right: correct date format
created > "2025-01-15"

# Wrong: invalid operator for text
text = "exact match"

# Right: use contains operator
text ~ "search text"