@aaronshaf/confluence-cli 0.1.15

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aaron Shafovaloff
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# cn
+
+CLI for syncing Confluence spaces to local markdown.
+
+## Install
+
+```bash
+bun install -g @aaronshaf/confluence-cli
+```
+
+## Getting Started
+
+```bash
+# 1. Configure your Confluence credentials
+cn setup
+
+# 2. Clone a Confluence space
+cn clone <SPACE_KEY>
+
+# 3. Pull pages as markdown
+cd <SPACE_KEY>
+cn pull
+```
+
+The space key is the identifier in your Confluence URL:
+`https://yoursite.atlassian.net/wiki/spaces/<SPACE_KEY>/...`
+
+Credentials are stored in `~/.cn/config.json`. Space configuration is saved to `.confluence.json` in the synced directory.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `cn setup` | Configure Confluence credentials |
+| `cn clone <SPACE_KEY>` | Clone a space to a new folder |
+| `cn pull` | Pull changes from Confluence as markdown |
+| `cn push [file]` | Push local markdown file(s) to Confluence |
+| `cn status` | Check connection and sync status |
+| `cn tree` | Display page hierarchy |
+| `cn open [page]` | Open page in browser |
+| `cn doctor` | Health check for sync issues |
+| `cn search <query>` | Search pages using CQL |
+| `cn spaces` | List available spaces |
+| `cn info <id\|file>` | Show page info and labels |
+| `cn create <title>` | Create a new page |
+| `cn delete <id>` | Delete a page |
+| `cn comments <id\|file>` | Show page comments |
+| `cn labels <id\|file>` | Manage page labels |
+| `cn move <id\|file> <parentId>` | Move a page to a new parent |
+| `cn attachments <id\|file>` | Manage page attachments |
+
+Run `cn <command> --help` for details on each command.
+
+## Requirements
+
+- Bun 1.2.0+
+- Confluence Cloud account
+
+## Development
+
+```bash
+bun install
+bun run cn --help
+bun test
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@aaronshaf/confluence-cli",
+  "version": "0.1.15",
+  "description": "Confluence CLI for syncing spaces and local markdown files",
+  "type": "module",
+  "bin": {
+    "cn": "./src/cli.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "engines": {
+    "bun": ">=1.2.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aaronshaf/confluence-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/aaronshaf/confluence-cli/issues"
+  },
+  "homepage": "https://github.com/aaronshaf/confluence-cli#readme",
+  "scripts": {
+    "dev": "bun run --watch src/cli.ts",
+    "test": "BUN_TEST_JOBS=1 NODE_ENV=test bun test",
+    "test:coverage": "BUN_TEST_JOBS=1 NODE_ENV=test bun test --coverage",
+    "test:coverage:report": "BUN_TEST_JOBS=1 NODE_ENV=test bun test --coverage --coverage-reporter=text",
+    "test:coverage:check": "BUN_TEST_JOBS=1 NODE_ENV=test bun test --coverage --coverage-threshold=70",
+    "check-file-sizes": "bun run scripts/check-file-sizes.ts",
+    "lint": "biome check",
+    "lint:fix": "biome check --write",
+    "format": "biome format --write",
+    "typecheck": "tsc --noEmit",
+    "cn": "bun run src/cli.ts",
+    "prepublishOnly": "bun run lint && bun run typecheck",
+    "pre-commit": "bun run typecheck && biome check --write && bun run check-file-sizes && bun run test:coverage:check",
+    "prepare": "node scripts/install-hooks.cjs"
+  },
+  "keywords": [
+    "confluence",
+    "cli",
+    "markdown",
+    "sync"
+  ],
+  "author": "Aaron Shafovaloff <aaronshaf@gmail.com>",
+  "license": "MIT",
+  "dependencies": {
+    "@effect/schema": "^0.75.5",
+    "@inquirer/prompts": "^7.8.4",
+    "chalk": "^5.4.1",
+    "effect": "^3.16.10",
+    "gray-matter": "^4.0.3",
+    "marked": "17.0.1",
+    "ora": "^8.2.0",
+    "turndown": "^7.2.0",
+    "turndown-plugin-gfm": "^1.0.2",
+    "zod": "4.3.5"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.0.6",
+    "@types/marked": "6.0.0",
+    "@types/turndown": "^5.0.5",
+    "bun-types": "^1.0.20",
+    "msw": "^2.10.4",
+    "typescript": "^5.3.3"
+  }
+}

package/src/cli/commands/attachments.ts

@@ -0,0 +1,113 @@
+import chalk from 'chalk';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { basename } from 'node:path';
+import { ConfluenceClient } from '../../lib/confluence-client/index.js';
+import { ConfigManager } from '../../lib/config.js';
+import { EXIT_CODES } from '../../lib/errors.js';
+import { escapeXml } from '../../lib/formatters.js';
+import { resolvePageTarget } from '../../lib/resolve-page-target.js';
+
+export interface AttachmentsCommandOptions {
+  upload?: string;
+  download?: string;
+  delete?: string;
+  xml?: boolean;
+}
+
+export async function attachmentsCommand(target: string, options: AttachmentsCommandOptions = {}): Promise<void> {
+  const configManager = new ConfigManager();
+  const config = await configManager.getConfig();
+
+  if (!config) {
+    console.error(chalk.red('Not configured. Run: cn setup'));
+    process.exit(EXIT_CODES.CONFIG_ERROR);
+  }
+
+  const pageId = resolvePageTarget(target);
+  const client = new ConfluenceClient(config);
+
+  if (options.upload) {
+    const filePath = options.upload;
+    const filename = basename(filePath);
+    const data = readFileSync(filePath);
+    const mimeType = guessMimeType(filename);
+    await client.uploadAttachment(pageId, filename, data, mimeType);
+    console.log(`${chalk.green('Uploaded:')} ${filename}`);
+    return;
+  }
+
+  if (options.delete) {
+    await client.deleteAttachment(options.delete);
+    console.log(`${chalk.green('Deleted attachment:')} ${options.delete}`);
+    return;
+  }
+
+  const attachments = await client.getAllAttachments(pageId);
+
+  if (options.download) {
+    const attachment = attachments.find((a) => a.id === options.download);
+    if (!attachment) {
+      console.error(chalk.red(`Attachment not found: ${options.download}`));
+      process.exit(EXIT_CODES.GENERAL_ERROR);
+    }
+    if (!attachment.downloadLink) {
+      console.error(chalk.red('No download link available for this attachment.'));
+      process.exit(EXIT_CODES.GENERAL_ERROR);
+    }
+    const buf = await client.downloadAttachment(attachment.downloadLink);
+    const safeFilename = basename(attachment.title);
+    writeFileSync(safeFilename, buf);
+    console.log(`${chalk.green('Downloaded:')} ${safeFilename}`);
+    return;
+  }
+
+  if (options.xml) {
+    console.log('<attachments>');
+    for (const att of attachments) {
+      console.log(`  <attachment id="${escapeXml(att.id)}">`);
+      console.log(`    <title>${escapeXml(att.title)}</title>`);
+      if (att.mediaType) console.log(`    <mediaType>${escapeXml(att.mediaType)}</mediaType>`);
+      if (att.fileSize != null) console.log(`    <fileSize>${att.fileSize}</fileSize>`);
+      console.log('  </attachment>');
+    }
+    console.log('</attachments>');
+    return;
+  }
+
+  if (attachments.length === 0) {
+    console.log('No attachments.');
+    return;
+  }
+
+  for (const att of attachments) {
+    const size = att.fileSize != null ? ` (${formatBytes(att.fileSize)})` : '';
+    const mime = att.mediaType ? ` [${att.mediaType}]` : '';
+    console.log(`${chalk.bold(att.title)}  ${chalk.gray(att.id)}${mime}${size}`);
+  }
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+  return `${(bytes / 1024 / 1024).toFixed(1)}MB`;
+}
+
+function guessMimeType(filename: string): string {
+  const ext = filename.split('.').pop()?.toLowerCase();
+  const mimeTypes: Record<string, string> = {
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    pdf: 'application/pdf',
+    txt: 'text/plain',
+    md: 'text/markdown',
+    json: 'application/json',
+    docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+    zip: 'application/zip',
+    csv: 'text/csv',
+  };
+  return mimeTypes[ext ?? ''] ?? 'application/octet-stream';
+}

package/src/cli/commands/clone.ts

@@ -0,0 +1,188 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import { existsSync, mkdirSync, rmSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { ConfigManager, type Config } from '../../lib/config.js';
+import { EXIT_CODES } from '../../lib/errors.js';
+import { SyncEngine } from '../../lib/sync/index.js';
+import { createProgressReporter } from '../utils/progress-reporter.js';
+
+const SEPARATOR = '='.repeat(60);
+
+export interface CloneCommandOptions {
+  spaceKeys: string[];
+}
+
+/**
+ * Clone command - clones one or more Confluence spaces to new local directories
+ */
+export async function cloneCommand(options: CloneCommandOptions): Promise<void> {
+  const configManager = new ConfigManager();
+  const config = await configManager.getConfig();
+
+  if (!config) {
+    console.error(chalk.red('Not configured. Please run "cn setup" first.'));
+    process.exit(EXIT_CODES.CONFIG_ERROR);
+  }
+
+  // Check for duplicate space keys
+  const uniqueKeys = new Set(options.spaceKeys);
+  if (uniqueKeys.size !== options.spaceKeys.length) {
+    const duplicates = options.spaceKeys.filter((key, index) => options.spaceKeys.indexOf(key) !== index);
+    console.error(chalk.red('Duplicate space keys detected.'));
+    console.log(chalk.gray(`Duplicates: ${[...new Set(duplicates)].join(', ')}`));
+    process.exit(EXIT_CODES.INVALID_ARGUMENTS);
+  }
+
+  const results: Array<{ spaceKey: string; status: 'success' | 'error'; error?: string }> = [];
+
+  // Clone each space sequentially
+  for (let i = 0; i < options.spaceKeys.length; i++) {
+    const spaceKey = options.spaceKeys[i];
+    const isMultiSpace = options.spaceKeys.length > 1;
+
+    if (isMultiSpace) {
+      console.log(chalk.blue(`\n${SEPARATOR}`));
+      console.log(chalk.blue(`Cloning ${i + 1}/${options.spaceKeys.length}: ${chalk.bold(spaceKey)}`));
+      console.log(chalk.blue(SEPARATOR));
+    }
+
+    try {
+      await cloneSingleSpace({ spaceKey, directory: spaceKey }, config);
+      results.push({ spaceKey, status: 'success' });
+    } catch (error) {
+      results.push({
+        spaceKey,
+        status: 'error',
+        error: error instanceof Error ? error.message : 'Unknown error',
+      });
+    }
+  }
+
+  // Check for failures
+  const successes = results.filter((r) => r.status === 'success');
+  const failures = results.filter((r) => r.status === 'error');
+
+  // Display summary if multiple spaces were cloned
+  if (options.spaceKeys.length > 1) {
+    console.log(chalk.blue(`\n${SEPARATOR}`));
+    console.log(chalk.bold('Clone Summary'));
+    console.log(chalk.blue(SEPARATOR));
+
+    if (successes.length > 0) {
+      console.log(chalk.green(`✓ Successfully cloned: ${successes.map((r) => r.spaceKey).join(', ')}`));
+    }
+
+    if (failures.length > 0) {
+      console.log(chalk.red(`✗ Failed to clone: ${failures.map((r) => r.spaceKey).join(', ')}`));
+      for (const failure of failures) {
+        console.log(chalk.red(`  ${failure.spaceKey}: ${failure.error}`));
+      }
+    }
+  }
+
+  // Exit with error if any failures occurred
+  if (failures.length > 0) {
+    process.exit(EXIT_CODES.GENERAL_ERROR);
+  }
+}
+
+/**
+ * Clone a single space - extracted from original cloneCommand
+ */
+async function cloneSingleSpace(options: { spaceKey: string; directory?: string }, config: Config): Promise<void> {
+  const syncEngine = new SyncEngine(config);
+
+  // Determine target directory
+  const targetDir = options.directory || options.spaceKey;
+  const fullPath = resolve(process.cwd(), targetDir);
+
+  // Check if directory already exists
+  if (existsSync(fullPath)) {
+    throw new Error(`Directory "${targetDir}" already exists.`);
+  }
+
+  const spinner = ora({
+    text: `Cloning space ${options.spaceKey} into ${targetDir}...`,
+    hideCursor: false,
+    discardStdin: false,
+  }).start();
+
+  try {
+    // Create directory
+    mkdirSync(fullPath, { recursive: true });
+
+    // Initialize space config
+    const spaceConfig = await syncEngine.initSync(fullPath, options.spaceKey);
+    spinner.succeed(`Cloned space "${spaceConfig.spaceName}" (${spaceConfig.spaceKey}) into ${targetDir}`);
+
+    // Perform initial pull - wrapped separately so init failures clean up but sync failures don't
+    let syncFailed = false;
+    try {
+      console.log('');
+      const progressReporter = createProgressReporter();
+      const result = await syncEngine.sync(fullPath, {
+        progress: progressReporter,
+      });
+
+      // Show warnings
+      if (result.warnings.length > 0) {
+        console.log('');
+        console.log(chalk.yellow('Warnings:'));
+        for (const warning of result.warnings) {
+          console.log(chalk.yellow(`  ! ${warning}`));
+        }
+      }
+
+      // Show errors
+      if (result.errors.length > 0) {
+        console.log('');
+        console.log(chalk.red('Errors:'));
+        for (const error of result.errors) {
+          console.log(chalk.red(`  x ${error}`));
+        }
+        syncFailed = true;
+      }
+
+      // Final summary
+      const { added, modified, deleted } = result.changes;
+      const total = added.length + modified.length + deleted.length;
+      if (total > 0) {
+        console.log('');
+        const parts = [];
+        if (added.length > 0) parts.push(`${added.length} added`);
+        if (modified.length > 0) parts.push(`${modified.length} modified`);
+        if (deleted.length > 0) parts.push(`${deleted.length} deleted`);
+        console.log(chalk.green(`✓ Clone complete: ${parts.join(', ')}`));
+      }
+    } catch (_syncError) {
+      // Sync failed but clone succeeded - don't clean up, provide recovery guidance
+      console.log('');
+      console.log(chalk.yellow('Initial pull failed. You can retry with:'));
+      syncFailed = true;
+    }
+
+    console.log('');
+    console.log(chalk.gray(`  cd ${targetDir}`));
+    if (syncFailed) {
+      console.log(chalk.gray('  cn pull'));
+    }
+  } catch (error) {
+    spinner.fail('Failed to clone space');
+
+    // Clean up directory on failure (only for init failures, not sync failures)
+    if (existsSync(fullPath)) {
+      try {
+        rmSync(fullPath, { recursive: true });
+      } catch {
+        // Ignore cleanup errors - directory may be partially created
+      }
+    }
+
+    if (error instanceof Error && error.message.includes('not found')) {
+      throw new Error(`Space "${options.spaceKey}" not found. Check the space key and try again.`);
+    }
+
+    throw error;
+  }
+}

package/src/cli/commands/comments.ts

@@ -0,0 +1,56 @@
+import chalk from 'chalk';
+import { ConfluenceClient } from '../../lib/confluence-client/index.js';
+import { ConfigManager } from '../../lib/config.js';
+import { EXIT_CODES } from '../../lib/errors.js';
+import { escapeXml } from '../../lib/formatters.js';
+import { resolvePageTarget } from '../../lib/resolve-page-target.js';
+
+export interface CommentsCommandOptions {
+  xml?: boolean;
+}
+
+function stripHtml(html: string): string {
+  return html.replace(/<[^>]+>/g, '').trim();
+}
+
+export async function commentsCommand(target: string, options: CommentsCommandOptions = {}): Promise<void> {
+  const configManager = new ConfigManager();
+  const config = await configManager.getConfig();
+
+  if (!config) {
+    console.error(chalk.red('Not configured. Run: cn setup'));
+    process.exit(EXIT_CODES.CONFIG_ERROR);
+  }
+
+  const pageId = resolvePageTarget(target);
+  const client = new ConfluenceClient(config);
+  const comments = await client.getAllFooterComments(pageId);
+
+  if (options.xml) {
+    console.log('<comments>');
+    for (const comment of comments) {
+      const body = comment.body?.storage?.value ? stripHtml(comment.body.storage.value) : '';
+      console.log(`  <comment id="${escapeXml(comment.id)}">`);
+      if (body) console.log(`    <body>${escapeXml(body)}</body>`);
+      if (comment.authorId) console.log(`    <authorId>${escapeXml(comment.authorId)}</authorId>`);
+      if (comment.createdAt) console.log(`    <createdAt>${escapeXml(comment.createdAt)}</createdAt>`);
+      console.log('  </comment>');
+    }
+    console.log('</comments>');
+    return;
+  }
+
+  if (comments.length === 0) {
+    console.log('No comments found.');
+    return;
+  }
+
+  for (const comment of comments) {
+    const body = comment.body?.storage?.value ? stripHtml(comment.body.storage.value) : '';
+    console.log(chalk.gray(`--- ${comment.id} ---`));
+    if (body) console.log(body);
+    if (comment.authorId) console.log(chalk.gray(`Author: ${comment.authorId}`));
+    if (comment.createdAt) console.log(chalk.gray(`Date: ${comment.createdAt}`));
+    console.log();
+  }
+}

package/src/cli/commands/create.ts

@@ -0,0 +1,58 @@
+import chalk from 'chalk';
+import { ConfluenceClient } from '../../lib/confluence-client/index.js';
+import { ConfigManager } from '../../lib/config.js';
+import { EXIT_CODES } from '../../lib/errors.js';
+import { readSpaceConfig } from '../../lib/space-config.js';
+import { openUrl } from '../utils/browser.js';
+
+export interface CreateCommandOptions {
+  space?: string;
+  parent?: string;
+  open?: boolean;
+}
+
+export async function createCommand(title: string, options: CreateCommandOptions = {}): Promise<void> {
+  const configManager = new ConfigManager();
+  const config = await configManager.getConfig();
+
+  if (!config) {
+    console.error(chalk.red('Not configured. Run: cn setup'));
+    process.exit(EXIT_CODES.CONFIG_ERROR);
+  }
+
+  const client = new ConfluenceClient(config);
+  let spaceId: string | undefined;
+
+  if (options.space) {
+    const space = await client.getSpaceByKey(options.space);
+    spaceId = space.id;
+  } else {
+    const spaceConfig = readSpaceConfig(process.cwd());
+    if (!spaceConfig) {
+      console.error(chalk.red('Not in a cloned space directory. Use --space to specify a space key.'));
+      process.exit(EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    spaceId = spaceConfig.spaceId;
+  }
+
+  const page = await client.createPage({
+    spaceId,
+    status: 'current',
+    title,
+    parentId: options.parent,
+    body: {
+      representation: 'storage',
+      value: '',
+    },
+  });
+
+  console.log(`${chalk.green('Created:')} ${chalk.bold(page.title)}  ${chalk.gray(page.id)}`);
+  if (page._links?.webui) {
+    const url = `${config.confluenceUrl}/wiki${page._links.webui}`;
+    console.log(`URL: ${chalk.blue(url)}`);
+
+    if (options.open) {
+      openUrl(url);
+    }
+  }
+}

package/src/cli/commands/delete.ts

@@ -0,0 +1,46 @@
+import chalk from 'chalk';
+import { confirm } from '@inquirer/prompts';
+import { ConfluenceClient } from '../../lib/confluence-client/index.js';
+import { ConfigManager } from '../../lib/config.js';
+import { EXIT_CODES } from '../../lib/errors.js';
+import { resolvePageTarget } from '../../lib/resolve-page-target.js';
+
+export interface DeleteCommandOptions {
+  force?: boolean;
+}
+
+export async function deleteCommand(target: string, options: DeleteCommandOptions = {}): Promise<void> {
+  const configManager = new ConfigManager();
+  const config = await configManager.getConfig();
+
+  if (!config) {
+    console.error(chalk.red('Not configured. Run: cn setup'));
+    process.exit(EXIT_CODES.CONFIG_ERROR);
+  }
+
+  const pageId = resolvePageTarget(target);
+  const client = new ConfluenceClient(config);
+
+  if (!options.force) {
+    let page: Awaited<ReturnType<typeof client.getPage>>;
+    try {
+      page = await client.getPage(pageId, false);
+    } catch {
+      console.error(chalk.red(`Page not found: ${pageId}`));
+      process.exit(EXIT_CODES.PAGE_NOT_FOUND);
+    }
+
+    const confirmed = await confirm({
+      message: `Delete "${page.title}" (${pageId})?`,
+      default: false,
+    });
+
+    if (!confirmed) {
+      console.log('Cancelled.');
+      return;
+    }
+  }
+
+  await client.deletePage(pageId);
+  console.log(`${chalk.green('Deleted:')} ${pageId}`);
+}