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

When NOT to Use This Skill

Risk Levels

All operations are read-only with no risk:

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 = "[email protected]"
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

# Attachments in a space
type = attachment AND space = "DOCS"

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

CQL Fields Reference

CLI Commands

Output format tip: A global -o/--output flag placed before the subcommand (e.g. confluence-as -o json search cql "...") sets the default output format for all subcommands; an explicit subcommand-level --output wins. Note that for search export and search stream-export, the subcommand-level -o/--output is the output file path, not the format - use --format there.

confluence-as search cql

Execute CQL queries against Confluence.

Usage:

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

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

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

# Show excerpts
confluence-as 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-as search validate

Validate CQL query syntax.

Usage:

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

Arguments:

• cql - CQL query to validate (required)

confluence-as search suggest

Get CQL field and value suggestions.

Usage:

# Get field suggestions
confluence-as search suggest --fields

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

# Get operators and functions
confluence-as search suggest --operators
confluence-as 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-as search interactive

Interactive CQL query builder.

Usage:

confluence-as search interactive
confluence-as search interactive --space DOCS
confluence-as 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-as search export

Export search results to file.

Usage:

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

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

# Select columns
confluence-as search export "type = page" --columns id,title,space,created --output pages.csv

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-as search stream-export

Export large result sets with checkpoints.

Usage:

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

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

# Custom batch size
confluence-as 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-as search history

Manage local query history.

Usage:

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

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

# Show specific query by index
confluence-as search history show 5

# Clear history
confluence-as search history clear

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

# Cleanup old entries
confluence-as 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-as search content

Simple text search (no CQL knowledge required).

Usage:

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

Arguments:

• query - Search text (required)
• --space - Limit to space
• --type - Content type: page or blogpost. Omit the flag to search all types. (The CLI also accepts all, but that injects the literal type = all into the CQL, which the server rejects - do not use it.)
• --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-as 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

CQL Troubleshooting

Validate query before running:

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

Build query interactively:

confluence-as search interactive --space DOCS

Check available fields:

confluence-as search suggest --fields
confluence-as 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"