confluence-cli

Use Confluence as a knowledge base from your terminal — built for coding agents.

confluence-cli lets coding agents (Claude Code and others) — and humans — read, search and maintain a Confluence instance from the command line: fetch and edit pages, manage attachments, labels and comments. It speaks to both Confluence Cloud and Data Center / Server, returns agent-friendly JSON with structured errors, and ships a companion Skill that teaches an agent how to use it. Write commands support --dry-run, and destructive ones require --yes.

📖 Documentation site: https://angelmsger.github.io/confluence-cli/

Features

• Cloud & Data Center — one flavor-agnostic client; the backend is detected automatically.
• Agent-friendly — JSON output by default, structured errors with exit codes and recovery hints, and partial page reads (outline / section / keyword) so an agent spends minimal context.
• Read & write — fetch pages and browse trees, CQL search; create, edit, move, delete and restore pages; manage attachments, labels, comments and page watches. Every write supports --dry-run; destructive commands need --yes.
• Time-bounded edit history — find pages the current user contributed to, then filter their version history by actor and an exact time window.
• Flexible configuration — CLI flags, environment variables, a .env file, a YAML config file, or an interactive wizard; secrets stored in the OS keychain.
• Companion Skill — a confluence Skill, embedded in the binary, that guides coding agents through the CLI.

Installation

Install the CLI with npm, then take two short steps to finish setup — deploy the companion Skill, then (optionally) enable shell completion.

1. Install the CLI — npm (recommended)

npm install -g @angelmsger/confluence-cli

npm downloads the prebuilt binary for your platform, verifies its SHA-256 checksum, and keeps upgrades one npm update -g @angelmsger/confluence-cli away.

go install github.com/angelmsger/confluence-cli/cmd/confluence-cli@latest   # go 1.24+
make install                                                                # from a source checkout

Or download a prebuilt binary from the Releases page. The full installation guide covers every method.

2. Deploy the companion Skill

The confluence Skill is embedded in the binary; it teaches your coding agent (Claude Code, Codex, Cursor, Agents (shared), Gemini CLI, GitHub Copilot, OpenCode, Continue, Windsurf, Grok Build, Pi, Kilo Code, and Roo Code) how to drive the CLI. skill install probes for installed agents and installs into each one found:

confluence-cli skill install            # auto-detect; install for each agent found
confluence-cli skill install --agent codex
confluence-cli skill status             # compare loaded, installed, embedded versions
confluence-cli skill uninstall          # remove it again

After upgrading the CLI, re-run skill install and reload the agent context. Details, including the npx skills workflow, are in docs/installation.md.

3. Enable shell completion (optional)

confluence-cli completes subcommands, enum flag values and live space keys. Load the completion script for your shell once:

source <(confluence-cli completion bash)                       # bash, current shell
confluence-cli completion zsh > "${fpath[1]}/_confluence-cli"   # zsh, persistent

fish, PowerShell and persistent setup are covered in docs/installation.md.

Quick start

confluence-cli config init --pretty   # interactive TUI setup (recommended for humans)
confluence-cli doctor                 # verify configuration and connectivity

confluence-cli search --text "release process"
confluence-cli page get <id|url> --scope outline
confluence-cli page get <id|url> --scope section --section sec-2
confluence-cli comment list <id|url>

Configuration

Settings resolve in precedence order (highest first): CLI flags → environment variables (CONFLUENCE_*) → .env → ~/.angelmsger/confluence/config.yaml (legacy fallback ~/.confluence/config.yaml) → defaults. See .env.example and docs/installation.md. Secrets are stored in the OS keychain. If Windows Credential Manager is unavailable, the fallback is encrypted with per-user DPAPI; macOS/Linux retain the 0600 fallback. Secrets are never written to the config file.

Commands

Command	Purpose
page get	fetch a page; render body with --scope/--detail/--as
page children / page descendants	browse the page tree
page create / update / delete / move / copy	write pages; --dry-run previews, delete needs --yes
page history / page restore	list or filter one or more pages' versions; roll a page back to an earlier one
page watch / unwatch / watch-status	subscribe to or check page notifications
search	CQL search, raw or built from --text/--author/--space/...
space list / space get	inspect spaces
comment list / add / update / delete	read, post, edit and remove comments; preview writes with --dry-run
attachment list / download / upload / update / delete	inspect, fetch and manage attachments
label list / add / remove	manage page labels
whoami	print the user the credentials authenticate as
user search / user get / user me	discover Confluence users — the values --author / --contributor accept (Cloud: --query required; DC: optional)
skill install / skill uninstall	deploy or remove the embedded companion Skill (Claude Code, Codex, Cursor, Agents, Gemini, GitHub Copilot, OpenCode, Continue, Windsurf, Grok Build, Pi, Kilo Code, Roo Code)
config get-contexts / /

In the default JSON output, list commands return a {items, next, has_more} envelope; pass --cursor with a prior page's next to read the following page, or --all to fetch every page. --format ndjson instead streams the items themselves, one JSON object per line. If more results remain, stderr emits a structured _notice.pagination with next and has_more: true; pass that next as --cursor. Field projection affects rows only, so an empty filtered page can still have a continuation notice. Completed pages and --all results emit no pagination notice.

Find pages I edited in a time range

Confluence CQL indexes contributor and lastmodified as independent page-level properties. Use search only to find candidates, then inspect the version events for an exact actor and time match:

confluence-cli search --type page --contributor me --after 2026-09-03 \
  --all --fields id \
  | jq -r '.items[].id' \
  | confluence-cli page history - --actor me \
      --from 2026-09-03T00:00:00+08:00 \
      --to 2026-09-04T00:00:00+08:00

Do not add search --before to this candidate query: another person's later edit would move the page's lastmodified value past that upper bound. The history window is [from,to); date-only values mean UTC, so use RFC 3339 with an explicit offset for a local calendar day. --since cannot be combined with --from or --to, and --to requires --from; a rejected window exits 2 with BAD_TIME_RANGE naming the rule, before any request is sent. Batch history queries require --since or --from; they read newest-first and stop once versions are older than that lower bound. Data Center installations without the version-list API are handled through versioned historical-content reads. If one page is inaccessible, the batch continues: successful versions remain on stdout, a HISTORY_SOURCE_FAILED notice identifies the page, and the command exits non-zero with BATCH_PARTIAL_FAILURE so incomplete coverage cannot look like a complete result.

Multiple servers (contexts)

A single config file can hold several Confluence servers as named contexts. Most users need only one and never see the concept — config init --pretty configures a default context and the flow is unchanged. To work with more than one server, re-run config init --pretty and pick Add a new context, then:

confluence-cli config get-contexts          # list contexts, current marked
confluence-cli config use-context prod      # switch the current context
confluence-cli --use-context prod page get 123   # override for one command

CONFLUENCE_CONTEXT overrides the current context via the environment. Legacy single-server config files are read unchanged.

Contexts on the same host and authentication scheme share one stored credential. config delete-context <name> removes a context together with its credential, unless another context still uses it.

Errors and exit codes

Failures are JSON on stderr (stdout stays a clean data channel) and map to stable exit codes: 0 success, 2 usage, 3 config, 4 auth, 5 permission, 6 not found, 7 rate limit, 8 network, 9 server, 10 parse, 11 conflict. Each error carries next_steps naming the command to run next, and retryable to guide back-off.

Use as a Go library

The HTTP client that powers the CLI is published as a standalone Go package, so a GUI or other tool can drive Confluence directly — same normalized models, Cloud / Data Center flavor handling and structured errors, without shelling out to the binary.

import (
	"context"
	"net/http"
	"os"

	api "github.com/angelmsger/confluence-cli/pkg/apiclient"
	cerr "github.com/angelmsger/confluence-cli/pkg/errors"
	"github.com/angelmsger/confluence-cli/pkg/transport"
)

// Authentication is a transport.Decorator you supply — it sets the
// Authorization header on every request. PAT uses a Bearer token:
func bearer(token string) transport.Decorator {
	return func(r *http.Request) { r.Header.Set("Authorization", "Bearer "+token) }
}

ctx := context.Background()
client, flavor, err := api.Build(ctx, api.BuildParams{
	BaseURL:       "https://wiki.example.com",
	Flavor:        "auto", // "cloud" | "datacenter" | "auto"
	AuthDecorator: bearer(os.Getenv("CONFLUENCE_PERSONAL_ACCESS_TOKEN")),
})
if err != nil { /* see error handling below */ }

page, err := client.GetPage(ctx, "123456", api.GetPageOpts{})

Errors are *errors.CLIError with a stable Category and Code, so callers branch on failure kinds instead of parsing strings:

if ce := cerr.AsCLIError(err); ce != nil {
    // ce.Category, ce.Code, ce.Hint, ce.NextSteps, ce.HTTPStatus, ce.Retryable
}

These pkg/... packages primarily back this CLI and its companion Skill; their exported surface is treated as a stable contract. Read the package doc comment (go doc ./pkg/apiclient) before changing it.

Development

make test       # unit + integration tests
make e2e        # build + run against an in-repo mock Confluence server
make e2e-live   # additionally run read-only checks against the real server
make lint       # gofmt + go vet
make docs       # regenerate the CLI reference under docs/cli/

The docs/cli/ reference is generated from the cobra command tree by cmd/gen-docs, so it always matches --help. After changing a command or flag, run make docs and commit the result — CI fails if it drifts.

See docs/technical-design.md for the architecture and internal/ package layout, docs/releasing.md for the release process, and CHANGELOG.md for the version history.

Related

Part of a family of agent-facing CLIs — one skeleton, one set of conventions, all built for coding agents. Browse the full set at github.com/AngelMsger:

• jira-cli — Jira issues & workflow transitions
• confluence-cli — Confluence as a knowledge base (this project)
• bitbucket-cli — Bitbucket pull requests & code review
• openobserve-cli — OpenObserve logs, metrics & traces
• jenkins-cli — inspect Jenkins jobs & builds
• prometheus-cli — Prometheus queries, targets, rules & alerts
• wecom-calendar-cli — WeCom calendars, synced locally & annotated

License

Released under the MIT License.

Team setup

An installer can run confluence-cli config set-context team --base-url <url> --auth-scheme pat --activate without credentials or network access. Members then run confluence-cli auth guide and confluence-cli auth login. See team distribution and personal login for environment-only presets, conflict handling, and version-specific credential pages.

To point a prepared team context at a login this machine already has for the same service, whatever scheme it uses, run confluence-cli --use-context team auth reuse --dry-run, then omit --dry-run. See existing-login reuse.