CQL Guide
CQL (Confluence Query Language) is used by manage_search to find content. This guide covers the most useful patterns for both CLI and MCP usage.
Search Modes
Section titled “Search Modes”ctk supports two search modes:
| Mode | Description | When to Use |
|---|---|---|
CQL (cql action) | Structured queries with field/operator/value | Precise filtering by space, type, label, date |
Quick (quick action) | Plain text search | Simple keyword searches, like the Confluence search bar |
Basic CQL Syntax
Section titled “Basic CQL Syntax”CQL queries follow the pattern: field operator value
type = page AND space = "DEV"Use AND, OR to combine conditions, and ORDER BY for sorting.
Operators
Section titled “Operators”| Operator | Description | Example |
|---|---|---|
= | Exact match | type = "page" |
!= | Not equal | type != "comment" |
~ | Contains text | title ~ "meeting notes" |
!~ | Does not contain | title !~ "draft" |
IN | Match any in list | space IN ("DEV", "TEAM") |
NOT IN | Not in list | space NOT IN ("ARCHIVE") |
>, <, >=, <= | Comparison | created >= "2025-01-01" |
Common Fields
Section titled “Common Fields”| Field | Description | Example |
|---|---|---|
type | Content type | type = "page" or type = "blogpost" |
space | Space key | space = "DEV" |
title | Page title | title ~ "architecture" |
text | Full-text content search | text ~ "API documentation" |
label | Content label | label = "approved" |
creator | Created by user | creator = currentUser() |
contributor | Any editor | contributor = "jane@example.com" |
created | Creation date | created >= "2025-01-01" |
lastModified | Last modified date | lastModified >= "2025-06-01" |
ancestor | Under a parent page (recursive) | ancestor = "12345678" |
parent | Direct parent page | parent = "12345678" |
id | Content ID | id = "12345678" |
Practical Patterns
Section titled “Practical Patterns”Pages in a space (newest first)
Section titled “Pages in a space (newest first)”type = page AND space = "DEV" ORDER BY lastModified DESCRecently modified content
Section titled “Recently modified content”type = page AND lastModified >= "-7d" ORDER BY lastModified DESCContent with a specific label
Section titled “Content with a specific label”type = page AND label = "architecture" ORDER BY title ASCPages under a parent (recursive)
Section titled “Pages under a parent (recursive)”ancestor = "12345678" AND type = page ORDER BY title ASCFull-text search in a space
Section titled “Full-text search in a space”space = "DEV" AND text ~ "database migration" ORDER BY lastModified DESCPages created this month
Section titled “Pages created this month”type = page AND created >= startOfMonth() ORDER BY created DESCMy recently edited pages
Section titled “My recently edited pages”type = page AND contributor = currentUser() AND lastModified >= "-30d" ORDER BY lastModified DESCBlog posts in a space
Section titled “Blog posts in a space”type = blogpost AND space = "ENG" ORDER BY created DESCPages with multiple labels
Section titled “Pages with multiple labels”type = page AND label = "api" AND label = "v2" ORDER BY title ASCPages without a specific label
Section titled “Pages without a specific label”type = page AND space = "DEV" AND label != "archived" ORDER BY lastModified DESCSearch across all spaces
Section titled “Search across all spaces”type = page AND title ~ "onboarding" ORDER BY lastModified DESCPersonal space search
Section titled “Personal space search”space = "~username" AND type = page ORDER BY lastModified DESCUsing CQL with ctk
Section titled “Using CQL with ctk”# CQL queryctk search 'type=page AND space=DEV AND title~"architecture"'
# Quick text searchctk search --quick "API documentation"{ "action": "cql", "cql": "type=page AND space=DEV AND lastModified >= \"-7d\" ORDER BY lastModified DESC", "limit": 25}{ "action": "quick", "query": "onboarding guide"}