Search Confluence with CQL from the Command Line

atlassian-cli is an independent, community open-source project, not affiliated with, endorsed by, or sponsored by Atlassian, and is not Atlassian's official CLI (acli). Product names are used only to identify compatibility.

What Confluence CQL Is

Confluence CQL (Confluence Query Language) is a structured search syntax for finding content by exact metadata: which space it lives in, whether it is a page or a blog post, its labels, its author, when it was last modified, and the words it contains. It is the same language behind Confluence's advanced search, and the Confluence Cloud search REST endpoint accepts a raw CQL string. That last detail is what makes it so useful from a terminal: the query you type is passed straight through to the API and returns a clean, filtered result set you can automate against.

With atlassian-cli, you run a CQL query with a single command and get results as a table, JSON, CSV, YAML, or markdown. No clicking through the advanced search UI, no copying page IDs by hand. This post covers the CQL syntax you will actually use, how to run and filter searches from the command line, and how to export or chain the output into other tools.

atlassian-cli is an independent, community open-source project. It is not Atlassian's official CLI (acli) and is not affiliated with Atlassian. Use the official acli for first-party vendor support; use atlassian-cli if you want a single free Rust binary spanning Jira, Confluence, Bitbucket, and JSM with CQL search built in.

Running a CQL Search

The core command is confluence search cql. Pass your CQL string in quotes and, optionally, a --limit:

# Every page in the ENG space labeled "runbook"
atlassian-cli confluence search cql "space = ENG and type = page and label = runbook" --limit 25

By default the results print as a readable table. Because CQL is passed through to the Confluence search API verbatim, anything valid in the Confluence advanced search box is valid here. If you already know CQL, you know this command.

The CLI also ships two convenience wrappers for the common cases so you do not have to write full CQL every time:

# Full-text keyword search (relevance ranked)
atlassian-cli confluence search text "meeting notes" --limit 10

# Keyword search scoped to a single space
atlassian-cli confluence search in-space DEV "api docs"

Use search text when you are hunting for a keyword and want the best matches ranked first. Reach for search cql when you need precision: an exact, repeatable, filtered set of content that you can hand to a script, a report, or a bulk operation.

CQL Fields and Operators

CQL statements read like plain clauses: field operator value, joined with AND, OR, and NOT. Keywords are case-insensitive, and string values with spaces need quotes. The table below covers the fields you will use most.

The operators are just as small a set. = and != test exact equality; ~ and !~ test text contains and does-not-contain; >, >=, <, and <= compare dates; and IN (a, b, c) matches any value in a list. CQL also provides functions that resolve at query time, which keep your saved queries evergreen: currentUser(), now("-7d"), startOfMonth(), and favouriteSpaces() are the ones worth memorizing. Append order by lastModified desc to sort.

Filtering Recipes

Here are queries that map to real housekeeping and reporting tasks. Each one is a complete, copy-pasteable command.

Find every page you personally created in a space, newest first:

atlassian-cli confluence search cql \
  "space = DOCS and type = page and creator = currentUser() order by created desc"

Surface stale content: pages in a space not touched in over a year, which are prime candidates for review or archival:

atlassian-cli confluence search cql \
  "space = KB and type = page and lastModified <= now(\"-365d\")" \
  --limit 100

Combine a label filter with a keyword match to pull a topical subset:

atlassian-cli confluence search cql \
  "label = incident and text ~ \"database\" and lastModified >= now(\"-90d\")"

Search across several spaces at once with IN, and exclude blog posts:

atlassian-cli confluence search cql \
  "space IN (ENG, DOCS, KB) and type = page and title ~ \"architecture\""

List everything nested under a specific parent page, which is handy for auditing a documentation tree without knowing its structure in advance:

atlassian-cli confluence search cql "ancestor = 3302031761 and type = page" --limit 200

Two things to note. Inside a double-quoted shell string, escape the inner quotes CQL needs (\"database\") or wrap the whole query in single quotes instead. And --limit caps the number of results returned, so raise it when you expect a large set.

Exporting and Piping Results

A CQL search is only half the job. The other half is doing something with the results. Every search command respects the global --format flag, so you can switch from a human-readable table to machine-readable output without changing the query.

# JSON for scripting: pipe to jq to pull just the titles
atlassian-cli confluence search cql "space = DOCS and type = page" \
  --format json | jq '.[].title'

# CSV redirected to a file for a spreadsheet
atlassian-cli confluence search cql "space = DOCS and label = reviewed" \
  --format csv > reviewed-pages.csv

# Markdown, ready to paste into a report or another page
atlassian-cli confluence search cql "space = KB and lastModified >= now(\"-7d\")" \
  --format markdown

The available formats are table (default), json, csv, yaml, markdown, and quiet. JSON is the workhorse for automation: pipe it to jq to count results, extract IDs, or reshape the data. A common pattern is turning a CQL search into a to-do list of page IDs that a follow-up command then acts on.

# Count how many stale pages a query matches
atlassian-cli confluence search cql \
  "space = KB and type = page and lastModified <= now(\"-365d\")" \
  --format json | jq 'length'

If you want the full page bodies rather than a result list, that is an export rather than a search: reach for confluence bulk export, covered next.

Feeding CQL into Bulk Actions

The same CQL you use to search also drives the bulk commands. This is where CQL earns its keep: you write a precise query once, preview it, then apply an action to every matching page. The bulk commands accept --cql and, like all destructive operations in atlassian-cli, support --dry-run so you can see the blast radius before committing.

# Preview which pages a query matches before touching anything
atlassian-cli confluence bulk add-labels \
  --cql "space = DEV and title ~ \"draft\"" \
  --labels needs-review \
  --dry-run

# Export the full content of everything a query matches
atlassian-cli confluence bulk export \
  --cql "space = DEV and type = page" \
  --output dev-pages.json \
  --format json

# Clean up an archived space (preview first, always)
atlassian-cli confluence bulk delete --cql "space = OLD" --dry-run

The workflow is consistent: write the CQL, run search cql to eyeball the matches, then hand the identical query to a bulk command with --dry-run, and only remove the flag once the count and sample look right. For a production-grade cleanup routine built on this pattern, see the Confluence bulk cleanup runbook.

How This Differs from acli

Atlassian ships its own official CLI, acli, which is the right choice when you want first-party vendor support. atlassian-cli is a separate, independent, MIT-licensed community project. It is not affiliated with, endorsed by, or maintained by Atlassian. Its appeal is breadth from one binary: the same tool that runs your Confluence CQL searches also handles Jira issues, Bitbucket repositories, and Jira Service Management requests, with consistent --format and --profile flags across every command.

If most of your work is Confluence content management, start with the Confluence CLI guide for the wider command set, or the full command reference for exact flags. To go beyond CQL search into raw endpoints, the companion post on calling the Confluence API from the CLI shows how to script against the API directly, and the space export and backup post covers archiving whole spaces.

FAQ

Related Resources