convez.ai
Skill
sofq

confluence-cli

sofq/confluence-cli

Ver no GitHub
BomPluginScore · de 0 a 100

Confluence CLI for developers and AI agents — structured JSON output, jq filtering, batch operations, and workflow automation. Built from Jira's OpenAPI spec.

Instalação

$npx convez-ai sofq/confluence-cli

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 5 dias
Versão
v1.2.7
Issues abertas
5
Contribuidores
2

README

A tradução para o português deste README ainda está na fila.

cf

The Confluence CLI that speaks JSON — built for AI agents. Pure JSON on stdout. Structured errors on stderr. Semantic exit codes. 200+ auto-generated commands. Zero prompts, zero interactivity.

npm PyPI Release CI Coverage Go License

🧭 Mental model · 📦 Install · ⚡ Quickstart · ✨ Features · 🛠 Workflow · 📖 Commands · ⚙️ Configuration · 🔒 Security · 🤖 Agent integration · 🧪 Development


Overview

cf wraps the Confluence Cloud REST API in a CLI designed for machines first, humans second. Every command emits a single JSON document on stdout. Every error is a structured object on stderr. Every exit code maps to a recoverable agent action. No spinners, no colors, no prompts, no surprises.

[!TIP] Use --preset agent, --fields, and --jq together to compress an 8KB Confluence response down to ~50 tokens before it ever reaches the model.

Mental model

cf is a conduit: agent intent enters wide, gets shaped by flags, leaves Confluence as raw JSON, and arrives back at the agent narrowed to exactly what it needs.

---
config:
  theme: base
  themeVariables:
    primaryColor: "#7c5cff"
    primaryBorderColor: "#5b3fd9"
    primaryTextColor: "#1a1d22"
    lineColor: "#7c5cff"
    secondaryColor: "#eef0ff"
    tertiaryColor: "#dcf7eb"
    edgeLabelBackground: "#ffffff"
    fontSize: "14px"
---
flowchart LR
    subgraph agent["👤 Agent"]
        a[👤 AI Agent]
    end

    subgraph cf["⚙️ cf — the compressor"]
        direction LR
        parse[📥 Parse intent]
        shape[⚙️ Shape request<br/>--fields / --preset]
        req[🔗 HTTP request<br/>retry + auth]
        filt[🪄 Filter response<br/>--jq]
    end

    subgraph confluence["🌐 Confluence"]
        api[(🌐 Confluence REST)]
    end

    json[📤 Tight JSON<br/>+ exit code]

    a --> parse
    parse --> shape
    shape --> req
    req -->|HTTP| api
    api -->|raw JSON| filt
    filt --> json

    classDef actor fill:#7c5cff,stroke:#5b3fd9,color:#ffffff
    classDef compress fill:#1a2236,stroke:#7c5cff,color:#e8e9f3
    classDef external fill:#dcf7eb,stroke:#3ddc97,color:#0b3a26
    classDef output fill:#3ddc97,stroke:#1da76b,color:#06321f

    class a,parse actor
    class shape,req,filt compress
    class api external
    class json output

    style agent fill:#eef0ff,stroke:#7c5cff,color:#1a1d22
    style cf fill:#0b0f1a,stroke:#7c5cff,color:#e8e9f3
    style confluence fill:#dcf7eb,stroke:#3ddc97,color:#0b3a26

Three properties make this work:

  • Self-describing. cf schema returns the full operation graph — no command lists to memorize.
  • Compressible. --preset / --fields / --jq stack to drop response size by orders of magnitude.
  • Recoverable. Every failure is a typed exit code an agent can branch on.

Install

Using npm

npm install -g confluence-cf

Using pip

pip install confluence-cf

Using brew  ·  macOS / Linux

brew install sofq/tap/cf

Using scoop  ·  Windows

scoop bucket add sofq https://github.com/sofq/scoop-bucket
scoop install cf

Using go install

go install github.com/sofq/confluence-cli@latest

Prebuilt binaries — download from Releases and drop on your PATH.

Quickstart

cf configure --base-url https://yoursite.atlassian.net --token YOUR_API_TOKEN
cf pages get --id 12345 --preset agent
{"id":"12345","title":"Deploy Runbook","status":"current","version":5}

[!NOTE] Get a Confluence API token at https://id.atlassian.com/manage-profile/security/api-tokens. cf configure --test validates credentials before you commit them to a profile.

Features

Workflow

Use caseCommand
Read a page, only what the model needscf pages get --id 12345 --preset agent
Find recently-updated pages in a spacecf search search-content --cql "space = DEV AND lastModified > now('-7d')" --jq '.results[] | {id, title}'
Create a page from XHTML bodycf pages create --space-id 123456 --title "Runbook" --body "<p>Steps...</p>"
Update a page (auto version increment)cf pages update --id 12345 --title "Runbook v2" --body "<p>...</p>"
Diff what changed in the last 2 hourscf diff --id 12345 --since 2h
Export a page tree as JSONcf export --id 12345 --tree
Watch a space for changescf watch --cql "space = DEV" --interval 30s --max-events 50
Move, copy, archive, commentcf workflow move | copy | archive | comment ...
Add and remove labelscf labels add --page-id 12345 --name reviewed
Upload an attachmentcf attachments upload --page-id 12345 --file ./diagram.png
Run multiple ops in one processecho '[...]' | cf batch
Hit any v2 endpoint directlycf raw GET /pages/12345
{"event":"updated","id":"12345","title":"Deploy Runbook","version":5,"when":"2026-04-07T10:15:00Z"}
{"event":"created","id":"67890","title":"New RFC","version":1,"when":"2026-04-07T10:16:30Z"}

Events: initial, created, updated, removed. Always pair --interval with --max-events in unattended contexts.

{"version_from":3,"version_to":5,"title_changed":true,"body":{"added":12,"removed":4,"changed":8}}

Commands

Self-describing — discover the full surface from the binary itself.

cf schema                     # resource → verbs map
cf schema --list              # resource names only
cf schema pages               # operations on `pages`
cf schema pages get           # full flag schema for one operation
cf preset list                # named output presets
ResourceVerbs
pagesget list create update delete
blogpostsget list create update delete
spacesget list
commentslist create update delete
attachmentslist upload download delete
labelsadd remove list
custom-contentget list create update delete
searchsearch-content search-user
workflowmove copy archive restrict comment
diffdiff
exportexport
watchwatch
batchbatch
rawGET POST PUT PATCH DELETE

Global flags

FlagPurpose
--preset <name>Named output preset (agent, brief, titles, meta, tree, search, diff)
--jq <expr>jq filter applied to the response
--fields <list>Comma-separated Confluence field selector (GET only)
--cache <duration>Cache GET responses (5m, 1h, …)
--no-paginateDisable auto-pagination
--dry-runPrint the request without executing it
--verboseLog HTTP details to stderr as JSON
--timeout <duration>HTTP request timeout (default 30s)
--profile <name>Use a named config profile
--audit <path>NDJSON audit log file
--max-batch <N>Cap on operations per batch (default 50)
--prettyPretty-print JSON output

Exit code contract

{"error_type":"rate_limited","status":429,"retry_after":30}
ExitMeaningAgent action
0OKParse stdout
1General errorInspect stderr
2Auth failedRe-authenticate
3Not foundCheck page ID
4ValidationFix input
5Rate limitedWait retry_after seconds
6PermissionCheck access

Configuration

Profiles live in ~/.config/cf/config.json. Each profile holds a base URL, auth, and an optional operation policy.

{
  "profiles": {
    "default": {
      "base_url": "https://yoursite.atlassian.net",
      "auth": { "type": "basic", "token": "..." }
    },
    "agent": {
      "base_url": "https://yoursite.atlassian.net",
      "auth": { "type": "basic", "token": "..." },
      "allowed_operations": ["pages get", "search *", "workflow comment"]
    },
    "readonly": {
      "base_url": "https://yoursite.atlassian.net",
      "auth": { "type": "basic", "token": "..." },
      "denied_operations": ["* delete*", "* create*", "* update*", "raw *"]
    }
  }
}
cf configure --base-url https://yoursite.atlassian.net --token YOUR_TOKEN
cf configure --test                          # validate the default profile
cf configure --test --profile agent          # validate one profile
cf configure --profile readonly --delete     # remove a profile

Security

LayerWhat it does
Operation policiesPer profile, glob-based allowed_operations (deny-by-default) or denied_operations (allow-by-default). Patterns: pages get, * delete*, workflow *.
Audit log--audit ./audit.log — emits one NDJSON record per call (timestamp, profile, command, exit code). Configurable per profile.
Batch capDefault 50 operations per cf batch invocation. Override with --max-batch N.
No interactive promptsAn attacker can't trick cf into reading from a TTY mid-command — there is no TTY path.
Secrets in config onlyTokens are never accepted as positional args; only via cf configure or env.

Vulnerability reports: SECURITY.md.

Agent integration

Claude Code plugin (included)

/plugin marketplace add https://github.com/sofq/confluence-cli
/plugin install confluence-cli@confluence-cli

Or install the skill manually:

cp -r skills/confluence-cli ~/.claude/skills/    # global install

The skill teaches Claude Code the cf command surface, presets, and exit-code contract directly — no system prompt edits needed.

[!NOTE] See skills/confluence-cli/SKILL.md for the full agent integration guide with patterns, error handling, and token optimization strategies.

Any other agent

Drop this into your agent's system prompt:

Use `cf` for all Confluence operations. Output is always JSON on stdout.
Run `cf schema` first to discover available commands.
Use `--preset agent` or `--jq` to minimize tokens.
On non-zero exit, parse stderr for {error_type, status, retry_after}.
Exit codes: 0=ok 1=error 2=auth 3=not_found 4=validation 5=rate_limited 6=permission.

Development

make build          # build the cf binary
make test           # run all tests with race detection
make lint           # golangci-lint
make generate       # regenerate commands from the Confluence OpenAPI spec
make spec-update    # download the latest OpenAPI spec
make docs-dev       # serve the VitePress doc site locally
make docs-build     # build the static doc site
make clean          # remove build artifacts

The generated command tree under cmd/ is rebuilt by make generate from spec/confluence-v2.json. Hand-written commands live alongside the generated ones — anything in cmd/ ending in _test.go is excluded from generation.

License

Apache 2.0 © sofq

Ver o original no GitHub

Bom para

Relacionados