# Confluence Kb

> Read and edit a Confluence Cloud knowledge base through the REST API - pages, spaces, CQL search, comments, with Markdown in and Markdown out. Use whenever asked to open, read, fetch, export, search, create, edit, update, rename, append to or comment on a Confluence or wiki page, including when given a .atlassian.net/wiki/ link. Not for Jira issues - that is the jira-tasks skill.

- Skill: `viderstar/confluence-kb` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add viderstar/confluence-kb`
- Raw SKILL.md: https://api.skillmd.com/api/skills/viderstar/confluence-kb/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: ViderStar (https://skillmd.com/u/viderstar)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/viderstar/confluence-kb

---


# Confluence knowledge base

Entry point: `scripts/kb.py`. Standard library only. Markdown goes in, Markdown comes out;
the storage-format XHTML in between is the script's problem, not yours.

## 1. Access

Same credentials as Jira — one Atlassian API token covers both. Read in this order:
environment → `~/.config/atlassian-kit/atlassian.env` → `credentials.json` next to the
script.

```
CONFLUENCE_URL=https://yoursite.atlassian.net
CONFLUENCE_USERNAME=you@example.com
CONFLUENCE_API_TOKEN=...
```

`python3 kb.py check` prints who you are and which site you are on. If it says the request
went out anonymous, the token is dead — a wrong token does not error, it silently
downgrades you to an anonymous reader who sees nothing.

## 2. Writing is a two-step action, always

Every write command is a **dry run by default**. Without `--yes` the script prints a diff
and sends nothing.

1. Run the command without `--yes`.
2. Show the human the diff.
3. Only after an explicit "yes", repeat with `--yes`.

Pages are visible to everyone with access to the space, and page history keeps your name
on the change. This is not a step to optimise away.

Prefer `append` and `replace` over `update`: they touch one region and leave the rest of
the page exactly as it was. `update` replaces the whole body, which quietly destroys
anything added by someone else since you read it.

## 3. Commands

```bash
python kb.py check
python kb.py spaces
python kb.py search "confidence criteria" --space ENG --limit 10
python kb.py search --cql 'space=ENG and lastmodified > now("-7d")'

python kb.py page <id|url>                    # as Markdown to stdout
python kb.py page <id|url> --out page.md
python kb.py export <id|url> --dir ./wiki     # a page or a whole tree
python kb.py children <id|url>
python kb.py comments <id|url>

python kb.py create --space ENG --title "Title" --file body.md --parent <id>   # add --yes
python kb.py append <id|url> --file section.md --message "add results"         # add --yes
python kb.py replace <id|url> --find "old text" --replace-with "new" --count 1 # add --yes
python kb.py update <id|url> --file body.md --title "New title"                # add --yes
python kb.py comment <id|url> --text "..."                                     # add --yes
```

A page is addressed by id or by pasting its URL — the script pulls the id out.

## 4. Traps

- **409 means someone edited the page after you read it.** Re-read and redo the edit; do
  not retry the same version number.
- **`replace` works on storage XHTML, not on the Markdown you saw.** Text can be split by
  tags, so an obvious string may match zero times. Look at the real markup before
  concluding the text is not there. `--count` makes it fail rather than replace more
  occurrences than you expected.
- **403 and 404 both often mean the token expired**, not that the page is missing.
- Backups of every page the script overwrites go to
  `~/.local/state/atlassian-kit/kb-backups/` — deliberately outside the plugin directory,
  which is wiped on update.