Forem: Adrian Darian

Export Your Confluence Documentation Like a Pro: Introducing Confluence Export CLI

Adrian Darian — Thu, 25 Dec 2025 10:16:18 +0000

Have you ever needed to backup your Confluence pages? Or migrate documentation to another system? Or simply want your Confluence content in Markdown format for version control?

I've built Confluence Export CLI - a powerful command-line tool that exports Confluence pages to multiple formats (Markdown, HTML, Text, PDF) with support for bulk exports, parallel fetching, and recursive child page export.

Why I Built This

Working with Confluence documentation, I often needed to:

Export entire documentation spaces for backup
Convert Confluence pages to Markdown for Git-based workflows
Migrate documentation between systems
Create offline backups of critical documentation

The existing solutions were either too complex, required manual work, or didn't support bulk exports. So I built a tool that does exactly what I needed - and made it open source for others to use.

Key Features

🚀 Multiple Export Formats

Export to the format that works best for your workflow:

Markdown - Perfect for Git-based documentation
HTML - Standalone HTML files with embedded CSS
Plain Text - Great for search and archival
PDF - Native Confluence PDF export

# Export to multiple formats at once
confluence-export --pages 123456 --format markdown html pdf

📦 Bulk Export with Parallel Processing

Export hundreds of pages efficiently with configurable parallel workers:

# Export entire space with 8 parallel workers
confluence-export --space DOCS --format markdown --workers 8

🌳 Recursive Child Page Export

Automatically export parent pages and all their children:

# Export a page and all its sub-pages
confluence-export --pages 123456 --include-children --format markdown

🎯 Flexible Input Options

Support for multiple input methods:

Full URLs: https://yoursite.atlassian.net/wiki/spaces/DOCS/pages/123/Page+Title
Page IDs: 123456
From file: --pages-file pages.txt
Entire spaces: --space DOCS

📊 Progress Display & Export Manifest

Beautiful progress bars using Rich library, plus optional manifest generation:

confluence-export --pages 123456 --include-children --manifest

Creates INDEX.md and manifest.json listing all exported pages.

Quick Start

Installation

pip install confluence-export

Setup Authentication

Get your API token from Atlassian API Tokens:

export CONFLUENCE_BASE_URL=https://yoursite.atlassian.net
export CONFLUENCE_EMAIL=your.email@example.com
export CONFLUENCE_API_TOKEN=your-api-token

Export Your First Page

# Using a full URL
confluence-export --pages "https://yoursite.atlassian.net/wiki/spaces/DOCS/pages/123456/My+Page" --format markdown

# Or using a page ID
confluence-export --pages 123456 --format markdown

Real-World Examples

Backup an Entire Documentation Space

confluence-export \
  --space DOCS \
  --format markdown html pdf \
  --include-children \
  --manifest \
  --output "./backup-$(date +%Y%m%d)" \
  --workers 8

Export Documentation Section with Sub-pages

confluence-export \
  --pages "https://mysite.atlassian.net/wiki/spaces/DOCS/pages/123/Getting+Started" \
  --include-children \
  --format markdown \
  --manifest \
  --output ./docs

Export from a File of URLs

Create pages.txt:

https://mysite.atlassian.net/wiki/spaces/DOCS/pages/123/Page+One
https://mysite.atlassian.net/wiki/spaces/DOCS/pages/456/Page+Two
789012

Then:

confluence-export --pages-file pages.txt --format markdown

Technical Highlights

Architecture

The tool is built with Python 3.8+ and follows clean architecture principles:

Modular Design: Separate exporters for each format, easy to extend
Parallel Processing: Uses ThreadPoolExecutor for concurrent API calls
Error Handling: Graceful error handling with --skip-errors option
Configuration Layers: CLI args > Config file > Environment variables > Defaults

Distribution Options

I've made it easy to distribute and use:

Wheel Package: Install via pip install confluence-export
Standalone Executables: No Python required - download and run
- Linux, Windows, and macOS executables
- Built with PyInstaller
- Available in GitHub releases

GitHub Actions Workflow

Automated builds and releases:

Builds wheel packages and executables for all platforms
Creates GitHub releases automatically
Publishes to PyPI on tag push

Configuration File Support

Save your settings to avoid repeating them:

confluence-export --base-url https://mysite.atlassian.net \
  --email user@example.com \
  --output ./exports \
  --format markdown html \
  --save-config

Creates .confluence-export.toml:

[auth]
base_url = "https://mysite.atlassian.net"
email = "user@example.com"

[export]
output = "./exports"
formats = ["markdown", "html"]
include_children = true

Now you can just run:

confluence-export --pages 123456

Output Structure

Hierarchical (Default)

Preserves page hierarchy in folder structure:

exports/
├── Parent-Page-123.md
└── Parent-Page/
    ├── Child-Page-456.md
    └── Child-Page/
        └── Grandchild-789.md

Flat Structure

Use --flat for a single directory:

exports/
├── Parent-Page-123.md
├── Child-Page-456.md
└── Grandchild-789.md

Use Cases

Documentation Migration: Export Confluence docs before migrating to another platform
Version Control: Convert Confluence pages to Markdown for Git-based documentation
Backup: Create regular backups of critical documentation
Offline Access: Export documentation for offline viewing
Content Analysis: Export to text format for analysis or search indexing

Contributing

The project is open source and welcomes contributions! Areas where help is appreciated:

Additional export formats (DOCX, LaTeX, etc.)
Performance improvements
Documentation improvements
Bug fixes and feature requests

Check out the GitHub repository to get started.

Conclusion

Confluence Export CLI solves a real problem for teams working with Confluence documentation. Whether you need to backup your docs, migrate to another system, or simply want your content in a different format, this tool makes it easy.

Try it out:

pip install confluence-export
confluence-export --help

Star the repo: github.com/adriandarian/confluence-export

Have questions or feedback? Open an issue on GitHub or reach out!

How I Stopped Mixing Personal and Work GitHub Accounts

Adrian Darian — Sun, 21 Dec 2025 08:13:46 +0000

If you use more than one GitHub account, this probably sounds familiar.

You’re in the zone, commit, push… then notice the commit is tied to the wrong GitHub account. Wrong email. Wrong avatar. Wrong org.

I hit this problem often enough that I stopped trying to “be careful” and built a fix.

The real issue

Git makes this easy to mess up:

Global config applies everywhere
Local config is easy to forget
SSH config controls access, not identity
Hooks are per-repo and brittle

All of this relies on memory. Memory fails.

What I wanted was automatic guardrails.

The idea: identity follows location

The core idea behind gh-account-guard:

Your GitHub identity should be based on where you work, not what you remember to switch.

Example layout:

~/work/*        → work GitHub account
~/personal/*    → personal GitHub account

Once defined, identity switching should be automatic.

Installation

gh-account-guard is a GitHub CLI extension.

gh extension install adriandarian/gh-account-guard

Verify it’s installed:

gh account-guard --help

Initial setup

Initialize your configuration:

gh account-guard init

You’ll map directory paths to GitHub accounts, for example:

~/work        → company-account
~/personal    → adriandarian

This only needs to be done once.

What happens during normal work

From here on, the workflow is simple:

cd ~/work/some-repo
git commit -m "Fix bug"

Before the operation completes, gh-account-guard checks:

Current directory
Expected GitHub account
Active Git identity

If everything matches → nothing happens.
If something doesn’t → it blocks the operation or switches accounts automatically.

No prompts. No guessing.

Checking status

You can always see what account is active:

gh account-guard status

This makes behavior explicit and easy to debug.

Why a GitHub CLI extension?

I wanted something that:

Works across all repositories
Doesn’t require repo-specific hooks
Is visible and inspectable
Fits into existing workflows

The GitHub CLI was a natural home for this.

What daily usage feels like

I’ve been using gh-account-guard daily for a few weeks across work and personal projects.

After setup, it fades into the background — which is exactly the goal.
No wrong commits. No cleanup. No mental overhead.

Who this is for

This is useful if you:

Use multiple GitHub accounts
Switch between personal and work repos
Contribute to OSS and private code
Want safety without friction

If you only use one account, you probably don’t need it.

Open source

The project is open source:

👉 https://github.com/adriandarian/gh-account-guard

If it saves you from one bad commit, it did its job.