@aaronshaf/confluence-cli 0.1.15 → 1.0.1

package/README.md

@@ -1,40 +1,39 @@
-# cn
+# confluence-cli
 
-CLI for syncing Confluence spaces to local markdown.
-
-## Install
+## Installation
 
 ```bash
+# Install Bun runtime
+curl -fsSL https://bun.sh/install | bash
+
+# Install confluence-cli
 bun install -g @aaronshaf/confluence-cli
 ```
 
 ## Getting Started
 
 ```bash
-# 1. Configure your Confluence credentials
+# Configure your Confluence credentials
 cn setup
 
-# 2. Clone a Confluence space
-cn clone <SPACE_KEY>
+# Search pages
+cn search "authentication"
 
-# 3. Pull pages as markdown
-cd <SPACE_KEY>
-cn pull
-```
+# Open a page in the browser
+cn open "Getting Started"
 
-The space key is the identifier in your Confluence URL:
-`https://yoursite.atlassian.net/wiki/spaces/<SPACE_KEY>/...`
+# Create a page
+cn create "My Page" --space ENG
 
-Credentials are stored in `~/.cn/config.json`. Space configuration is saved to `.confluence.json` in the synced directory.
+# List spaces
+cn spaces
+```
 
 ## 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 |
@@ -42,20 +41,19 @@ Credentials are stored in `~/.cn/config.json`. Space configuration is saved to `
 | `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 create <title>` | Create a new page (pipe content via stdin) |
+| `cn update <id>` | Update an existing page (pipe content via stdin) |
 | `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 |
+| `cn folder <subcommand>` | Manage folders (create, list, delete, move) |
+| `cn clone <SPACE_KEY>` | Clone a space to a new folder |
+| `cn pull` | Pull changes from Confluence as markdown |
 
 Run `cn <command> --help` for details on each command.
 
-## Requirements
-
-- Bun 1.2.0+
-- Confluence Cloud account
-
 ## Development
 
 ```bash
@@ -64,6 +62,10 @@ bun run cn --help
 bun test
 ```
 
+## See also
+
+- [pchuri/confluence-cli](https://github.com/pchuri/confluence-cli)
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aaronshaf/confluence-cli",
-  "version": "0.1.15",
+  "version": "1.0.1",
   "description": "Confluence CLI for syncing spaces and local markdown files",
   "type": "module",
   "bin": {

package/src/cli/commands/create.ts

@@ -4,11 +4,13 @@ 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';
+import { VALID_FORMATS, isValidFormat, readStdin } from '../utils/stdin.js';
 
 export interface CreateCommandOptions {
   space?: string;
   parent?: string;
   open?: boolean;
+  format?: string;
 }
 
 export async function createCommand(title: string, options: CreateCommandOptions = {}): Promise<void> {
@@ -20,6 +22,23 @@ export async function createCommand(title: string, options: CreateCommandOptions
     process.exit(EXIT_CODES.CONFIG_ERROR);
   }
 
+  const rawFormat = options.format ?? 'storage';
+  if (!isValidFormat(rawFormat)) {
+    console.error(chalk.red(`Invalid format: ${rawFormat}`));
+    console.log(chalk.gray(`Valid formats: ${VALID_FORMATS.join(', ')}`));
+    process.exit(EXIT_CODES.INVALID_ARGUMENTS);
+  }
+  const representation = rawFormat;
+
+  let bodyValue = '';
+  if (!process.stdin.isTTY) {
+    bodyValue = await readStdin();
+    if (bodyValue.trim().length === 0) {
+      console.error(chalk.red('Stdin is empty. Provide content to create a page with body.'));
+      process.exit(EXIT_CODES.INVALID_ARGUMENTS);
+    }
+  }
+
   const client = new ConfluenceClient(config);
   let spaceId: string | undefined;
 
@@ -41,8 +60,8 @@ export async function createCommand(title: string, options: CreateCommandOptions
     title,
     parentId: options.parent,
     body: {
-      representation: 'storage',
-      value: '',
+      representation,
+      value: bodyValue,
     },
   });
 

package/src/cli/commands/folder.ts

@@ -0,0 +1,189 @@
+import { confirm } from '@inquirer/prompts';
+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 { readSpaceConfig } from '../../lib/space-config.js';
+
+/**
+ * Extract a flag value from an args array, e.g. --space DOCS -> "DOCS"
+ */
+function getFlagValue(args: string[], flag: string): string | undefined {
+  const idx = args.indexOf(flag);
+  if (idx !== -1 && idx + 1 < args.length && !args[idx + 1].startsWith('--')) {
+    return args[idx + 1];
+  }
+  return undefined;
+}
+
+/**
+ * Get positional args by stripping flags and their values
+ */
+function getPositionals(args: string[], flagsWithValues: string[]): string[] {
+  const result: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith('--')) {
+      if (flagsWithValues.includes(args[i])) {
+        i++; // skip the value too
+      }
+    } else {
+      result.push(args[i]);
+    }
+  }
+  return result;
+}
+
+export async function folderCommand(subcommand: string, subArgs: string[], allArgs: string[]): 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);
+
+  switch (subcommand) {
+    case 'create': {
+      const positionals = getPositionals(subArgs, ['--space', '--parent']);
+      const title = positionals[0];
+      if (!title) {
+        console.error(chalk.red('Folder title is required.'));
+        console.log(chalk.gray('Usage: cn folder create <title> --space <key>'));
+        process.exit(EXIT_CODES.INVALID_ARGUMENTS);
+      }
+
+      const spaceKeyArg = getFlagValue(allArgs, '--space');
+      const parentId = getFlagValue(allArgs, '--parent');
+
+      let spaceId: string;
+
+      if (spaceKeyArg) {
+        const space = await client.getSpaceByKey(spaceKeyArg);
+        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 folder = await client.createFolder({ spaceId, title, parentId });
+      console.log(`${chalk.green('Created:')} "${folder.title}" (${folder.id})`);
+      break;
+    }
+
+    case 'list': {
+      const spaceKeyArg = getFlagValue(allArgs, '--space');
+
+      let spaceKey: string;
+
+      if (spaceKeyArg) {
+        spaceKey = spaceKeyArg;
+      } 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);
+        }
+        spaceKey = spaceConfig.spaceKey;
+      }
+
+      const cql = `type=folder AND space="${spaceKey.replace(/"/g, '\\"')}"`;
+      const PAGE_SIZE = 100;
+      const allResults: (typeof firstPage.results)[number][] = [];
+      let start = 0;
+
+      const firstPage = await client.search(cql, PAGE_SIZE, start);
+      allResults.push(...firstPage.results);
+      const total = firstPage.totalSize ?? firstPage.results.length;
+
+      while (allResults.length < total) {
+        start += PAGE_SIZE;
+        const page = await client.search(cql, PAGE_SIZE, start);
+        if (page.results.length === 0) break;
+        allResults.push(...page.results);
+      }
+
+      const xml = allArgs.includes('--xml');
+
+      if (xml) {
+        console.log('<folders>');
+        for (const result of allResults) {
+          const c = result.content;
+          if (c) {
+            console.log(`  <folder>`);
+            console.log(`    <id>${escapeXml(c.id ?? '')}</id>`);
+            console.log(`    <title>${escapeXml(c.title ?? '')}</title>`);
+            console.log(`  </folder>`);
+          }
+        }
+        console.log('</folders>');
+      } else {
+        if (allResults.length === 0) {
+          console.log(chalk.gray('No folders found.'));
+        } else {
+          for (const result of allResults) {
+            const c = result.content;
+            if (c) {
+              console.log(`${chalk.cyan(c.id)}  ${c.title}`);
+            }
+          }
+        }
+      }
+      break;
+    }
+
+    case 'delete': {
+      const positionals = getPositionals(subArgs, []);
+      const folderId = positionals[0];
+      if (!folderId) {
+        console.error(chalk.red('Folder ID is required.'));
+        console.log(chalk.gray('Usage: cn folder delete <id>'));
+        process.exit(EXIT_CODES.INVALID_ARGUMENTS);
+      }
+
+      if (!allArgs.includes('--force')) {
+        const folder = await client.getFolder(folderId);
+        const confirmed = await confirm({
+          message: `Delete folder "${folder.title}" (${folderId})?`,
+          default: false,
+        });
+        if (!confirmed) {
+          console.log('Cancelled.');
+          return;
+        }
+      }
+
+      await client.deleteFolder(folderId);
+      console.log(`${chalk.green('Deleted:')} ${folderId}`);
+      break;
+    }
+
+    case 'move': {
+      const positionals = getPositionals(subArgs, []);
+      if (positionals.length < 2) {
+        console.error(chalk.red('Folder ID and parent ID are required.'));
+        console.log(chalk.gray('Usage: cn folder move <id> <parentId>'));
+        process.exit(EXIT_CODES.INVALID_ARGUMENTS);
+      }
+
+      const folderId = positionals[0] as string;
+      const parentId = positionals[1] as string;
+      const [folder, parent] = await Promise.all([client.getFolder(folderId), client.getFolder(parentId)]);
+
+      await client.movePage(folderId, parentId);
+      console.log(`${chalk.green('Moved:')} "${folder.title}" under "${parent.title}"`);
+      break;
+    }
+
+    default:
+      console.error(chalk.red(`Unknown folder subcommand: ${subcommand}`));
+      console.log(chalk.gray('Run "cn folder --help" for usage information.'));
+      process.exit(EXIT_CODES.INVALID_ARGUMENTS);
+  }
+}

package/src/cli/commands/spaces.ts

@@ -6,6 +6,8 @@ import { escapeXml } from '../../lib/formatters.js';
 
 export interface SpacesCommandOptions {
   xml?: boolean;
+  limit?: number;
+  page?: number;
 }
 
 export async function spacesCommand(options: SpacesCommandOptions = {}): Promise<void> {
@@ -17,8 +19,11 @@ export async function spacesCommand(options: SpacesCommandOptions = {}): Promise
     process.exit(EXIT_CODES.CONFIG_ERROR);
   }
 
+  const limit = options.limit ?? 25;
+  const page = options.page ?? 1;
   const client = new ConfluenceClient(config);
-  const spaces = await client.getAllSpaces();
+  const response = await client.getSpaces(limit, page);
+  const spaces = response.results;
 
   if (options.xml) {
     console.log('<spaces>');
@@ -39,4 +44,8 @@ export async function spacesCommand(options: SpacesCommandOptions = {}): Promise
   for (const space of spaces) {
     console.log(`${chalk.bold(space.key)}  ${space.name}  ${chalk.gray(space.id)}`);
   }
+
+  if (response.size === limit) {
+    console.log(chalk.gray(`\nPage ${page}. Use --page ${page + 1} for next page, --limit to change page size.`));
+  }
 }

package/src/cli/commands/update.ts

@@ -0,0 +1,72 @@
+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 { VALID_FORMATS, isValidFormat, readStdin } from '../utils/stdin.js';
+
+export interface UpdateCommandOptions {
+  format?: string;
+  title?: string;
+  message?: string;
+}
+
+export async function updateCommand(pageId: string, options: UpdateCommandOptions = {}): 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);
+  }
+
+  if (process.stdin.isTTY) {
+    console.error(chalk.red('No content provided. Pipe content via stdin.'));
+    console.log(chalk.gray('Usage: echo "<p>Content</p>" | cn update <id>'));
+    process.exit(EXIT_CODES.INVALID_ARGUMENTS);
+  }
+
+  const rawFormat = options.format ?? 'storage';
+  if (!isValidFormat(rawFormat)) {
+    console.error(chalk.red(`Invalid format: ${rawFormat}`));
+    console.log(chalk.gray(`Valid formats: ${VALID_FORMATS.join(', ')}`));
+    process.exit(EXIT_CODES.INVALID_ARGUMENTS);
+  }
+  const representation = rawFormat;
+
+  const bodyValue = await readStdin();
+  if (bodyValue.trim().length === 0) {
+    console.error(chalk.red('Stdin is empty. Provide content to update the page.'));
+    process.exit(EXIT_CODES.INVALID_ARGUMENTS);
+  }
+
+  const client = new ConfluenceClient(config);
+  const current = await client.getPage(pageId, false);
+
+  if (!current) {
+    console.error(chalk.red(`Page not found: ${pageId}`));
+    process.exit(EXIT_CODES.GENERAL_ERROR);
+  }
+
+  const currentVersion = current.version?.number ?? 1;
+  const title = options.title ?? current.title;
+
+  const updated = await client.updatePage({
+    id: pageId,
+    status: 'current',
+    title,
+    body: {
+      representation,
+      value: bodyValue,
+    },
+    version: {
+      number: currentVersion + 1,
+      message: options.message,
+    },
+  });
+
+  console.log(`${chalk.green('Updated:')} ${chalk.bold(updated.title)}  ${chalk.gray(updated.id)}`);
+  if (updated._links?.webui) {
+    const url = `${config.confluenceUrl}/wiki${updated._links.webui}`;
+    console.log(`URL: ${chalk.blue(url)}`);
+  }
+}

package/src/cli/help.ts

@@ -89,41 +89,6 @@ ${chalk.yellow('Examples:')}
 `);
 }
 
-export function showPushHelp(): void {
-  console.log(`
-${chalk.bold('cn push - Push local markdown files to Confluence')}
-
-${chalk.yellow('Usage:')}
-  cn push [file] [options]
-
-${chalk.yellow('Description:')}
-  Push local markdown files to Confluence.
-
-  With a file argument: pushes that single file.
-  Without arguments: scans for changed files and prompts y/n for each.
-
-${chalk.yellow('Arguments:')}
-  file                      Path to markdown file (optional)
-
-${chalk.yellow('Options:')}
-  --force                   Ignore version conflicts and overwrite
-  --dry-run                 Preview changes without pushing
-  --help                    Show this help message
-
-${chalk.yellow('Examples:')}
-  cn push                          Scan and prompt for all changed files
-  cn push --dry-run                Preview what would be pushed
-  cn push ./docs/page.md           Push single page
-  cn push ./docs/page.md --force   Force push (ignore version conflict)
-
-${chalk.yellow('Notes:')}
-  - New files (no page_id) will be created on Confluence
-  - Modified files are detected by comparing file mtime vs synced_at
-  - Only basic markdown elements are fully supported
-  - Files are automatically renamed to match page titles (except index.md/README.md)
-`);
-}
-
 export function showStatusHelp(): void {
   console.log(`
 ${chalk.bold('cn status - Check connection and sync status')}
@@ -179,7 +144,8 @@ ${chalk.yellow('Usage:')}
   cn open [options]
 
 ${chalk.yellow('Description:')}
-  Opens a Confluence page in your default browser.
+  Opens a Confluence page in your default web browser (launches a browser window).
+  Not suitable for non-interactive environments (CI, bots, scripts).
   Without arguments, opens the space home page.
 
 ${chalk.yellow('Arguments:')}
@@ -254,6 +220,7 @@ ${chalk.bold('cn create - Create a new Confluence page')}
 
 ${chalk.yellow('Usage:')}
   cn create <title> [options]
+  echo "<p>Content</p>" | cn create <title> [options]
 
 ${chalk.yellow('Arguments:')}
   title                     Page title (required)
@@ -261,8 +228,37 @@ ${chalk.yellow('Arguments:')}
 ${chalk.yellow('Options:')}
   --space <key>             Space key (required if not in cloned dir)
   --parent <id>             Parent page ID
+  --format <format>         Body format: storage (default), wiki, atlas_doc_format
   --open                    Open page in browser after creation
   --help                    Show this help message
+
+${chalk.yellow('Examples:')}
+  cn create "My Page" --space ENG
+  echo "<p>Hello</p>" | cn create "My Page" --space ENG
+  echo "h1. Hello" | cn create "Wiki Page" --space ENG --format wiki
+`);
+}
+
+export function showUpdateHelp(): void {
+  console.log(`
+${chalk.bold('cn update - Update an existing Confluence page')}
+
+${chalk.yellow('Usage:')}
+  echo "<p>Content</p>" | cn update <id> [options]
+
+${chalk.yellow('Arguments:')}
+  id                        Page ID (required)
+
+${chalk.yellow('Options:')}
+  --format <format>         Body format: storage (default), wiki, atlas_doc_format
+  --title <title>           New page title (default: keep existing title)
+  --message <msg>           Version message
+  --help                    Show this help message
+
+${chalk.yellow('Examples:')}
+  echo "<p>Updated content</p>" | cn update 123456
+  echo "<p>New content</p>" | cn update 123456 --title "New Title"
+  echo "h1. Hello" | cn update 123456 --format wiki --message "Updated via automation"
 `);
 }
 
@@ -316,6 +312,35 @@ ${chalk.yellow('Options:')}
 `);
 }
 
+export function showFolderHelp(): void {
+  console.log(`
+${chalk.bold('cn folder - Manage Confluence folders')}
+
+${chalk.yellow('Usage:')}
+  cn folder <subcommand> [options]
+
+${chalk.yellow('Subcommands:')}
+  create <title>            Create a new folder
+  list                      List folders in a space
+  delete <id>               Delete a folder
+  move <id> <parentId>      Move a folder to a new parent
+
+${chalk.yellow('Options:')}
+  --space <key>             Space key (required for create/list if not in cloned dir)
+  --parent <id>             Parent folder ID (for create)
+  --force                   Skip confirmation prompt (for delete)
+  --xml                     Output in XML format (for list)
+  --help                    Show this help message
+
+${chalk.yellow('Examples:')}
+  cn folder create "My Folder" --space DOCS
+  cn folder create "Nested" --space DOCS --parent 123456
+  cn folder list --space DOCS
+  cn folder delete 123456
+  cn folder move 123456 789012
+`);
+}
+
 export function showMoveHelp(): void {
   console.log(`
 ${chalk.bold('cn move - Move a page to a new parent')}
@@ -386,7 +411,7 @@ ${chalk.yellow('Commands:')}
   cn setup                  Configure Confluence credentials
   cn clone                  Clone a space to a new folder
   cn pull                   Pull space to local folder
-  cn push                   Push local file to Confluence
+  cn folder                 Manage Confluence folders
   cn status                 Check connection and sync status
   cn tree                   Display page hierarchy
   cn open                   Open page in browser
@@ -395,6 +420,7 @@ ${chalk.yellow('Commands:')}
   cn spaces                 List available spaces
   cn info                   Show page info and labels
   cn create                 Create a new page
+  cn update                 Update an existing page
   cn delete                 Delete a page
   cn comments               Show page comments
   cn labels                 Manage page labels
@@ -414,10 +440,14 @@ ${chalk.yellow('Environment Variables:')}
 
 ${chalk.yellow('Examples:')}
   cn setup                  Configure credentials
-  cn clone DOCS             Clone DOCS space to ./DOCS
-  cn pull                   Pull changes
-  cn tree                   Show page hierarchy
+  cn spaces                 List available spaces
+  cn search "my topic"      Search across all spaces
+  cn search "api" --space ENG  Search within a space
+  cn info 123456            Show page info
   cn open "My Page"         Open page in browser
+  cn create "New Page" --space ENG  Create a page
+  cn clone DOCS             Clone DOCS space locally
+  cn pull                   Pull changes
 
 ${chalk.gray('For more information on a command, run: cn <command> --help')}
 ${chalk.gray('Confluence REST API reference: https://docs.atlassian.com/atlassian-confluence/REST/6.6.0/')}