Working with the Confluence API 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.

The Confluence API, CLI-first

If you want to work with the Confluence API from the command line, you have two options: build raw HTTP requests against the Confluence Cloud REST API with curl, or use a CLI that wraps those endpoints in named commands. This post is about the second option. Every example here is a single command that talks to the same public Confluence REST API you would call directly, minus the boilerplate of tokens, headers, pagination cursors, and JSON parsing.

The tool is atlassian-cli, a single Rust binary that covers Jira, Confluence, Bitbucket, and Jira Service Management. For Confluence it exposes the parts of the API you actually reach for day to day: listing and editing pages, managing spaces, and running Confluence Query Language (CQL) searches. If you are looking for a low-level walkthrough of the REST endpoints and payloads instead, read the companion Confluence REST API guide. This post stays CLI-first.

Authenticating once

The Confluence API uses your Atlassian account email plus an API token. You authenticate once, store the credentials in a named profile, and every later command reuses them. There is no per-request header wrangling.

# Log in once and mark this profile as default
atlassian-cli auth login \
  --profile work \
  --base-url https://your-domain.atlassian.net \
  --email you@example.com \
  --token $ATLASSIAN_API_TOKEN \
  --default

# Confirm the token works against the API
atlassian-cli auth test --profile work

Generate the token from your Atlassian account security settings, then export it as an environment variable so it never lands in your shell history. From here on, every confluence command targets your default profile unless you pass --profile to point at another instance. Full details are in the authentication guide.

Profiles are the mechanism for juggling more than one Confluence site. Log in with a second --profile name for a sandbox or a client tenant, and you can promote a change from one to the other by re-running the same command with a different --profile flag. Nothing about the command changes except which credentials it uses, which makes it safe to test a script against a throwaway space first.

Working with pages

Pages are the core object in the Confluence API. The confluence page group covers the full lifecycle: list, read, create, update, delete, plus versions, labels, comments, and restrictions.

# List pages in a space
atlassian-cli confluence page list --space DEV --limit 25

# Read a single page by its numeric ID
atlassian-cli confluence page get 12345

# Create a page (body is Confluence storage-format HTML)
atlassian-cli confluence page create \
  --space DEV \
  --title "Release Notes 1.0" \
  --body "<p>Shipped today.</p>"

# Update an existing page's title
atlassian-cli confluence page update 12345 --title "Release Notes 1.0 (final)"

The --body value is Confluence storage format, which is XHTML. That means you can template it: render Markdown or HTML in your own pipeline and pass the result straight in. If your goal is a repeatable Markdown-to-Confluence flow rather than one-off edits, see exporting Confluence to Markdown and the Markdown sync runbook.

One practical note: most page commands key off the numeric page ID, not the title. When you only know the title, do a quick CQL search first, grab the ID from the output, and feed it to page get or page update. That two-step pattern (search to resolve the ID, then act on it) is the backbone of almost every Confluence automation you will write, because IDs are stable while titles change.

Beyond create and edit, the same group handles the metadata that usually forces you into the web UI:

# See the full version history of a page
atlassian-cli confluence page versions 12345

# Tag pages so they are easy to find later with CQL
atlassian-cli confluence page add-label 12345 reviewed

# Read and add comments without leaving the terminal
atlassian-cli confluence page comments 12345
atlassian-cli confluence page add-comment 12345 "Approved for publishing."

# Inspect who can edit a page
atlassian-cli confluence page get-restrictions 12345

Working with spaces

Spaces are the containers pages live in. The confluence space group lets you enumerate, inspect, and provision them, which is handy when you are standing up documentation for a new team or auditing what already exists.

# List spaces you can see
atlassian-cli confluence space list --limit 10

# Inspect one space by key
atlassian-cli confluence space get DEV

# Provision a new space in one command
atlassian-cli confluence space create \
  --key DOCS \
  --name "Documentation" \
  --description "Team docs"

# Review who has access
atlassian-cli confluence space permissions DEV

Because the space key is stable, these commands drop cleanly into scripts. A new-team onboarding script can create the space, seed a landing page with page create, and grant read access, all from the same file. For a ready-made reporting example, see the space report runbook.

Searching with CQL

Confluence Query Language is the API's most powerful feature and the one that is most painful to hit with raw HTTP, because you have to URL-encode the query and page through cursors yourself. The CLI hands you three entry points.

# Full CQL: the most expressive option
atlassian-cli confluence search cql \
  "space = DEV and type = page and title ~ 'runbook'" \
  --limit 10

# Plain full-text search across everything you can read
atlassian-cli confluence search text "meeting notes" --limit 10

# Scope a text search to a single space
atlassian-cli confluence search in-space DEV "api docs"

CQL supports fields such as space, type, title, label, creator, and lastmodified, combined with AND, OR, and operators like ~ for contains. A few queries that come up constantly:

# Everything with a given label
atlassian-cli confluence search cql "label = deprecated"

# Stale pages: not touched in over a year
atlassian-cli confluence search cql "type = page and lastmodified < now('-365d')"

# Pages a specific person created in one space
atlassian-cli confluence search cql "space = DEV and creator = 'you@example.com'"

Pair a stale-page CQL query with the bulk cleanup runbook and you have a repeatable audit-then-archive workflow that never touches the web UI.

Piping API output into scripts

Every command defaults to a human-readable table, but the reason to script the Confluence API is to get structured data out. Add --format json (or csv, yaml, markdown) to any command and pipe it wherever you need.

# Pull page keys out of a CQL search with jq
atlassian-cli confluence search cql "space = DEV and type = page" \
  --format json | jq '.[].title'

# Wrap list output in {"data":[...],"count":N} for easy parsing
atlassian-cli confluence page list --space DEV --format json --envelope

# Snapshot an entire space to a JSON file for backup or diffing
atlassian-cli confluence bulk export \
  --cql "space = DEV" \
  --output backup.json \
  --format json

The --envelope flag is worth calling out: it wraps list responses in an object with a count, which makes downstream parsing predictable instead of guessing whether you got an array or a single object. Bulk commands such as bulk export, bulk add-labels, and bulk delete also accept --dry-run so you can preview the blast radius before anything changes. For a full backup pattern, see the Confluence backup runbook.

CLI commands vs raw REST calls

The CLI is not a replacement for the Confluence REST API; it is a front end to it. The table below maps common tasks to the raw approach versus the command. The value is not that one is capable of more, it is that the command removes the encoding, header, and pagination boilerplate.

Everything the CLI does is reproducible with curl and enough scripting. The point is that you rarely need to: the common 20% of the Confluence API that covers 80% of real work is already wrapped in verbs you can memorize. The complete list lives in the command reference.

FAQ

Related Resources