@tiroxuki0/confluence-sync

v0.1.10

Published

7 months ago

Bi-directional sync tool for Confluence and local markdown files

0High
0Medium
0Low

tiroxuki0

confluence-sync/cli sync markdown atlassian documentation bidirectional cli

confluence-sync

A powerful CLI tool for bidirectional synchronization between Confluence and local Markdown files. Built with TypeScript and Bun runtime for optimal performance.

⚠️ Disclaimer: This is an independent, open-source tool and is not officially associated with, endorsed by, or supported by Atlassian or Confluence. "Confluence" is a trademark of Atlassian Corporation. This tool uses the public Confluence REST API for synchronization purposes.

🤖 AI-Powered Development: This project is built using Claude Code with the BMAD-METHOD methodology, combining AI assistance with structured software engineering practices throughout the development lifecycle.

Features

🔄 Bidirectional sync between Confluence and local Markdown files
📁 Full page hierarchy and space support
🔐 Secure credential storage using system keychain
📝 Confluence storage format to Markdown conversion
👁️ Watch mode for automatic synchronization
🚀 Concurrent operations with rate limiting
🛡️ Conflict detection and resolution
📊 Progress tracking for bulk operations
🔧 Circuit breaker for API resilience
📈 Performance monitoring and caching

✨ Enhanced Features (v0.2.0+)

🎯 Smart Folder ID Handling - Automatically resolves folder IDs to space keys
⚡ Directory-Specific Sync - Sync only what you need (95%+ faster)
✅ Content Validation - Pre-push validation with warnings
💾 Automatic Backups - Create backups before destructive operations
📊 Diff Preview - See changes before applying them
🔄 Auto-Retry - Configurable retry with exponential backoff
🚀 Cache Optimization - Intelligent caching for faster operations
📈 Performance Metrics - Detailed stats with --verbose flag
📁 Auto Folder Pages - No need for _index.md, folders become pages automatically! (NEW)

Quick Start

Prerequisites

Bun runtime (v1.2.0 or higher)
Confluence instance (Cloud or Server)
API token or password for authentication

Install Bun runtime

This CLI requires the Bun runtime to execute and to run bunx examples below.

macOS (Apple silicon & Intel) and Linux:

curl -fsSL https://bun.sh/install | bash
# Restart your terminal, then verify
bun --version

Windows (PowerShell):

powershell -c "irm bun.sh/install.ps1 | iex"
# Restart your terminal, then verify
bun --version

Homebrew (macOS/Linux):

brew tap oven-sh/bun
brew install bun
bun --version

Installation

Install globally, then run the CLI directly:

npm install -g @tiroxuki0/confluence-sync
confluence-sync --help

Initial Setup

1. Create an API Token

For Confluence Cloud (Atlassian):

Go to https://id.atlassian.com/manage/api-tokens
Click Create API token
Give your token a descriptive name (e.g., "confluence-sync")
Click Create
Copy the generated token immediately (you won't be able to see it again)

For Confluence Server/Data Center:

Use your regular username and password instead of an API token

2. Initialize Configuration

Initialize your Confluence sync configuration:

# Interactive mode (will prompt for URL, email, and token)
confluence-sync init

# Non-interactive mode (provide all options)
confluence-sync init --url https://your-domain.atlassian.net/wiki/api/v2 --email [email protected] --token YOUR_API_TOKEN

# Optional: specify a custom sync directory
confluence-sync init --url https://your-domain.atlassian.net/wiki/api/v2 --email [email protected] --token YOUR_API_TOKEN --dir ./my-docs

Note: Replace YOUR_API_TOKEN with the token you created in step 1.

Authentication

Before using the sync commands, you need to authenticate with your Confluence instance:

# Authenticate with Confluence (interactive prompts)
confluence-sync auth login

# Check current authentication status
confluence-sync auth status

# Remove stored credentials
confluence-sync auth logout

Authentication Methods

Cloud: Use your email and an API token from https://id.atlassian.com/manage/api-tokens
Server: Use your username and password

Usage Examples

Pull Commands

Pull a Single Page

# Pull a specific page by ID
confluence-sync pull 123456789

# Pull to a specific directory
confluence-sync pull 123456789 --output ./docs

# Pull a page and all its children recursively
confluence-sync pull 123456789 --recursive

# Limit recursion depth (default: 10)
confluence-sync pull 123456789 --recursive --max-depth 5

Pull an Entire Space

# Pull all pages from a Confluence space
confluence-sync pull --space MYSPACE

# Pull space to a specific directory
confluence-sync pull --space MYSPACE --output ./wiki

# The space structure will be preserved as:
# ./wiki/
# ├── 001-homepage/
# │   ├── _index.md        (Homepage content)
# │   ├── 002-child-page.md
# │   └── 003-another-child/
# │       ├── _index.md
# │       └── 004-grandchild.md

Push Commands

Push a Single File

# Push a Markdown file to update an existing Confluence page
confluence-sync push ./docs/page.md

# Create a new page in a space
confluence-sync push ./docs/new-page.md --space MYSPACE

# Create a child page under a parent page
confluence-sync push ./docs/child.md --parent-id 987654321

# Push with folder ID (auto-resolves to space)
confluence-sync push ./docs/page.md --parent-id 445939715 --space S5

# Push with enhanced options
confluence-sync push ./docs/page.md --space MYSPACE --validate --backup --verbose

# Preview changes before pushing (dry-run)
confluence-sync push ./docs/page.md --dry-run --show-diff

# Push with custom retry and timeout
confluence-sync push ./docs/page.md --retry 5 --timeout 60000

Enhanced Push Features:

✅ Folder ID support - Automatically handles folder IDs with --space flag
✅ Content validation - Use --validate to check content before pushing
✅ Backup creation - Use --backup to create backups before changes
✅ Diff preview - Use --show-diff to see changes before pushing
✅ Performance monitoring - Use --verbose for detailed metrics
✅ Auto-retry - Configurable retry attempts with --retry <n>
✅ Cache optimization - Faster operations with intelligent caching
✅ Dry-run mode - Preview without making changes

Push Multiple Files (with Auto Folder Pages)

NEW: No need for _index.md files! Just organize your docs in folders and push:

# Push entire folder structure - folders become pages automatically!
confluence-sync push ./docs --recursive --space MYSPACE

# Example structure:
# docs/
# ├── guides/
# │   ├── quickstart.md
# │   └── advanced.md
# └── api/
#     └── reference.md
#
# Result in Confluence:
# Docs (container)
# ├── Guides (auto-created)
# │   ├── Quickstart
# │   └── Advanced
# └── Api (auto-created)
#     └── Reference

# With verbose output to see auto-created folders
confluence-sync push ./docs --recursive --space MYSPACE --verbose

How it works:

Tool scans the directory structure
Automatically creates pages for folders (no _index.md needed!)
Creates parent pages before children
Maintains the hierarchy in Confluence
Reports any failed pages at the end

Optional: Use _index.md for custom content

# You can still create _index.md for custom folder page content
echo "# API Documentation\n\nWelcome!" > docs/api/_index.md

# Folders without _index.md will be auto-created
# Folders with _index.md will use your custom content
confluence-sync push ./docs --recursive --space MYSPACE

Sync Commands

Intelligent Bidirectional Sync

# Sync current directory with Confluence
confluence-sync sync

# Sync a specific directory (enhanced with filtering)
confluence-sync sync ./docs

# Sync nested directory
confluence-sync sync ./docs/api

# Sync with verbose output
confluence-sync sync ./docs --verbose

# Dry run to preview changes without applying them
confluence-sync sync --dry-run

# Adjust concurrent operations
confluence-sync sync --max-concurrent 10

Enhanced Sync Features:

✅ Directory filtering - Only syncs files within specified directory
✅ Performance boost - Up to 95% faster for partial syncs
✅ Smart detection - Only checks relevant files
✅ Verbose mode - Detailed progress information
✅ Flexible scope - Sync entire project or specific directories

Watch Mode

Automatic Synchronization on File Changes

# Start watching for file changes and sync automatically
confluence-sync watch

# Customize debounce delay (milliseconds)
confluence-sync watch --debounce 5000

# Set max retry attempts on failure
confluence-sync watch --retry 5

# Disable desktop notifications
confluence-sync watch --no-notifications

# Output in JSON format for scripting
confluence-sync watch --json

Watch mode features:

Monitors all Markdown files for changes
Debounces rapid edits to avoid excessive API calls
Automatically retries on network failures
Respects .syncignore patterns
Shows real-time status indicators

Working with Page Hierarchies

When pulling spaces or recursive pages, the tool preserves the Confluence hierarchy in your local filesystem:

# Example: Pull a documentation space
confluence-sync pull --space DOCS --output ./documentation

# Result structure:
# ./documentation/
# ├── 001-getting-started/
# │   ├── _index.md           # Parent page content
# │   ├── 002-installation.md # Child page
# │   ├── 003-configuration.md # Child page
# │   └── 004-advanced/
# │       ├── _index.md       # Nested parent
# │       └── 005-api.md      # Grandchild page
# └── 006-troubleshooting.md  # Root-level page

Note:

Folders with _index.md represent pages that have children
Direct .md files represent leaf pages
Numbers prefix (001, 002, etc.) maintain Confluence page ordering

Status and Health Commands

# Show sync status of tracked files
confluence-sync status

# Filter status by space
confluence-sync status --space MYSPACE

# Output status in JSON format
confluence-sync status --json

# Check system health and connectivity
confluence-sync health

# Run all health checks
confluence-sync health --all

Conflict Resolution

# List all conflicted files
confluence-sync conflicts list

# Resolve conflicts interactively
confluence-sync conflicts resolve

# Resolve all conflicts with a strategy
confluence-sync conflicts resolve --strategy local-first
confluence-sync conflicts resolve --strategy remote-first

Enhanced Commands Examples

Working with Folder IDs

Confluence folders can now be used with the --parent-id option by providing a --space key:

# Extract space from folder URL:
# https://your-domain.atlassian.net/wiki/spaces/S5/folder/445939715
#                                              ^^         ^^^^^^^^^
#                                              Space      Folder ID

# Push to folder's space (page created at root, can be moved to folder manually)
confluence-sync push ./docs/guide.md --parent-id 445939715 --space S5

# The tool will:
# 1. Detect folder ID
# 2. Create page at root of space S5
# 3. Provide instructions to move to folder in Confluence UI

# After creation, subsequent pushes work normally:
confluence-sync push ./docs/guide.md
# ✅ Updates existing page (stays in folder)

Directory-Specific Operations

# Sync only documentation
confluence-sync sync ./docs

# Sync only API documentation
confluence-sync sync ./docs/api

# Sync with performance metrics
confluence-sync sync ./docs --verbose

# Dry-run to preview
confluence-sync sync ./docs --dry-run

Safe Push Operations

# Validate content before pushing
confluence-sync push ./docs/important.md --validate

# Create backup before pushing
confluence-sync push ./docs/critical.md --backup

# Preview changes without pushing
confluence-sync push ./docs/page.md --dry-run --show-diff

# All safety features combined
confluence-sync push ./docs/page.md \
  --validate \
  --backup \
  --show-diff \
  --dry-run \
  --verbose

# Remove --dry-run when ready to push
confluence-sync push ./docs/page.md \
  --validate \
  --backup \
  --verbose

Performance Optimization

# Disable cache for fresh data
confluence-sync push ./docs/page.md --no-cache

# Increase retry attempts for unstable connections
confluence-sync push ./docs/page.md --retry 5

# Increase timeout for large files
confluence-sync push ./docs/large-file.md --timeout 60000

# Combine for best results
confluence-sync sync ./docs \
  --max-concurrent 10 \
  --verbose

Advanced Options

Global Options

# Use a specific configuration profile for a single command
confluence-sync --profile production pull 123456789

# Or switch profiles permanently
confluence-sync use production
confluence-sync pull 123456789  # Uses production profile

# Increase verbosity for debugging
confluence-sync --verbose sync

# Suppress all output except errors
confluence-sync --quiet push ./docs

Performance Tuning

# Adjust concurrent operations (default: 5)
confluence-sync sync --concurrent 10

# Set custom rate limits for API calls
confluence-sync pull --space MYSPACE --rate-limit 100

Configuration

The tool uses separate files for configuration and sync state:

File Structure

csconfig.json - Configuration profiles and settings
.csmanifest.json - Sync state and page metadata (hidden file)
.csprofile - Active profile marker (hidden file)

Configuration File (`csconfig.json`)

Stores authentication profiles and settings:

{
  "version": "1.0.0",
  "defaultProfile": "default",
  "profiles": {
    "default": {
      "confluenceUrl": "https://mycompany.atlassian.net/wiki/api/v2",
      "spaceKey": "MYSPACE",
      "authType": "token",
      "concurrentOperations": 5,
      "conflictStrategy": "manual",
      "includePatterns": ["**/*.md"],
      "excludePatterns": ["**/node_modules/**", "**/.git/**"],
      "cacheEnabled": true
    }
  },
  "shared": {
    "logLevel": "info",
    "retryAttempts": 3,
    "retryDelay": 1000
  }
}

Managing Profiles

# List all configuration profiles
bunx confluence-sync@latest config list-profiles

# View current configuration
bunx confluence-sync@latest config view

# Create a new profile
bunx confluence-sync@latest config create-profile staging --url https://staging.atlassian.net --space STAGE

# Switch between profiles
bunx confluence-sync@latest use staging
bunx confluence-sync@latest use default

# Delete a profile
bunx confluence-sync@latest config delete-profile staging --force

# Get/set configuration values
bunx confluence-sync@latest config get spaceKey
bunx confluence-sync@latest config set concurrentOperations 10

Ignore Patterns

Create a .syncignore file to exclude files from synchronization:

# Dependencies
node_modules/
vendor/

# Build outputs
dist/
build/

# IDE files
.idea/
.vscode/

# Temporary files
*.tmp
*.swp

# Custom patterns
drafts/
**/README.md

Manifest File

The tool maintains a .csmanifest.json file that tracks:

Page mappings between local files and Confluence IDs
Version numbers for conflict detection
Content hashes for change detection
Space metadata and hierarchy information
Sync operations history

The manifest file is automatically managed by the tool and contains:

{
  "version": "1.0.0",
  "confluenceUrl": "https://mycompany.atlassian.net/wiki/api/v2",
  "lastSyncTime": "2025-01-09T10:30:00Z",
  "syncMode": "manual",
  "pages": {}, // Tracked pages with metadata
  "spaces": {}, // Space information
  "folders": {}, // Folder hierarchy
  "operations": [] // Sync history
}

Note: This file should be committed to version control to maintain sync state across team members.

Available Commands

| Command | Description | |---------|-------------| | auth | Manage authentication (login/logout/status) | | completion | Generate shell completion scripts | | config | Manage configuration profiles and settings | | conflicts | Manage and resolve sync conflicts | | health | Check system health and connectivity | | init | Initialize sync configuration | | pull | Pull pages from Confluence | | push | Push files to Confluence | | search | Search for Confluence pages | | status | Show sync status | | sync | Bidirectional synchronization | | use | Switch between configuration profiles | | watch | Watch for changes and sync automatically |

Error Codes

The tool uses specific error code ranges for different types of issues:

CS-100 to CS-199: Authentication errors
CS-200 to CS-299: API errors
CS-300 to CS-399: File system errors
CS-400 to CS-499: Sync errors
CS-500 to CS-599: Network errors
CS-600 to CS-699: Conflict errors
CS-700 to CS-799: Configuration errors
CS-800 to CS-899: Hierarchy errors
CS-900 to CS-999: Performance errors
CS-1000 to CS-1099: CLI errors
CS-1100 to CS-1199: Watch mode errors

Development

This project is developed using Claude Code with the BMAD method (Business-Minded Agile Development). BMAD is a structured approach that combines business requirements, agile methodologies, and AI-assisted development to create high-quality software efficiently.

The codebase includes:

User stories in docs/stories/ following BMAD format
Architecture documentation in docs/architecture/
Product requirements in docs/prd/
Development guidance in CLAUDE.md for AI-assisted coding

CI/CD Pipelines

This project uses GitHub Actions for continuous integration and deployment:

Continuous Integration (CI)

Branch: develop (default branch)
Triggers: Push and pull requests to develop
Actions: Install dependencies, lint, build, and test
Purpose: Ensure code quality and test coverage

Continuous Deployment (CD)

Branch: main (release branch)
Triggers: Push/merge to main
Actions: CI steps + publish to npm registry
Purpose: Automated releases to npmjs.com

Setting up GitHub Secrets

For the CD pipeline to publish to npm, you need to:

Generate an npm access token:
- Go to https://www.npmjs.com/settings/YOUR_USERNAME/tokens
- Click "Generate New Token" → "Classic Token"
- Select "Automation" type
- Copy the generated token
Add the token to GitHub repository secrets:
- Go to your repository's Settings → Secrets and variables → Actions
- Click "New repository secret"
- Name: NPM_TOKEN
- Value: Paste your npm token
- Click "Add secret"

Running Tests

# Run all tests
bun test

# Run with coverage
bun test --coverage

# Run specific test file
bun test tests/unit/commands/pull.test.ts

Building from Source

# Install dependencies
bun install

# Build the project
bun run build

# Run directly from source
bun run cli [command]

Project Structure

confluence-sync/
├── src/
│   ├── api/          # Confluence API client and types
│   ├── auth/         # Authentication management
│   ├── commands/     # CLI command implementations
│   ├── converters/   # Format converters (Markdown ↔ Confluence)
│   ├── storage/      # File and manifest management
│   ├── sync/         # Sync engine and conflict resolution
│   └── utils/        # Utilities and helpers
├── tests/
│   ├── unit/         # Unit tests
│   └── integration/  # Integration tests
└── docs/
    └── stories/      # Development stories and requirements

Troubleshooting

Common Issues

Authentication Fails

For Confluence Cloud: Ensure you're using an API token, not your password
For Confluence Server: Check if your instance URL includes the context path (e.g., /confluence)

Rate Limiting

The tool automatically handles rate limits with exponential backoff
For large spaces, consider using --concurrent 3 to reduce parallel requests

Hierarchy Issues

Circular references are automatically detected and logged
Maximum depth is limited to prevent infinite recursion (configurable with --max-depth)

File Name Conflicts

The tool sanitizes page titles for filesystem compatibility
Reserved names (CON, PRN, etc.) are prefixed with page-
Long titles are truncated to 100 characters

Debug Mode

Enable detailed logging for troubleshooting:

# Set log level to debug
export LOG_LEVEL=debug
confluence-sync sync

# Or use verbose flag
confluence-sync --verbose pull 123456789

Enhanced Features Troubleshooting

Folder ID Issues

Problem: Push to folder ID fails

# ❌ Error: Parent page not found
confluence-sync push ./docs/page.md --parent-id 445939715

Solution: Provide --space along with folder ID

# ✅ Works: Extract space from folder URL
# URL: https://your-domain.atlassian.net/wiki/spaces/S5/folder/445939715
confluence-sync push ./docs/page.md --parent-id 445939715 --space S5

Directory Sync Issues

Problem: File not synced when using directory filter

Cause: File is outside the specified directory

# File location: /project/GUIDE.md
# Sync command: confluence-sync sync ./docs
# Result: File not synced (correct behavior)

Solution:

Option 1: Move file to correct directory: mv GUIDE.md ./docs/
Option 2: Sync from correct location: confluence-sync sync .
Option 3: Sync all files: confluence-sync sync

Performance Issues

Problem: Slow sync operations

Solution: Use directory filtering

# ❌ Slow: Syncs all 1000 files
confluence-sync sync

# ✅ Fast: Syncs only 50 files in ./docs (95% faster)
confluence-sync sync ./docs

Additional optimizations:

# Increase concurrency
confluence-sync sync ./docs --max-concurrent 10

# Use cache
confluence-sync push ./docs/page.md  # Cache enabled by default

# Disable cache for fresh data
confluence-sync push ./docs/page.md --no-cache

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues, questions, or feature requests, please create an issue on our GitHub repository.