@aaronshaf/confluence-cli 1.0.0 → 1.0.1

package/README.md

@@ -1,39 +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 status` | Check connection and sync status |
 | `cn tree` | Display page hierarchy |
 | `cn open [page]` | Open page in browser |
@@ -41,21 +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": "1.0.0",
+  "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/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

@@ -144,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:')}
@@ -219,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)
@@ -226,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"
 `);
 }
 
@@ -389,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
@@ -408,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/')}

package/src/cli/index.ts

@@ -23,6 +23,7 @@ import {
   showSpacesHelp,
   showStatusHelp,
   showTreeHelp,
+  showUpdateHelp,
 } from './help.js';
 import { attachmentsCommand } from './commands/attachments.js';
 import { cloneCommand } from './commands/clone.js';
@@ -41,6 +42,9 @@ import { setup } from './commands/setup.js';
 import { spacesCommand } from './commands/spaces.js';
 import { statusCommand } from './commands/status.js';
 import { treeCommand } from './commands/tree.js';
+import { updateCommand } from './commands/update.js';
+
+import { findPositional } from './utils/args.js';
 
 // Get version from package.json
 const __filename = fileURLToPath(import.meta.url);
@@ -210,7 +214,23 @@ async function main(): Promise<void> {
           showSpacesHelp();
           process.exit(EXIT_CODES.SUCCESS);
         }
-        await spacesCommand({ xml: args.includes('--xml') });
+        {
+          let limit: number | undefined;
+          const limitArg = args.find((a) => a.startsWith('--limit=') || a === '--limit');
+          if (limitArg) {
+            limit = limitArg.includes('=')
+              ? Number.parseInt(limitArg.split('=')[1], 10)
+              : Number.parseInt(args[args.indexOf('--limit') + 1], 10);
+          }
+          let page: number | undefined;
+          const pageArg = args.find((a) => a.startsWith('--page=') || a === '--page');
+          if (pageArg) {
+            page = pageArg.includes('=')
+              ? Number.parseInt(pageArg.split('=')[1], 10)
+              : Number.parseInt(args[args.indexOf('--page') + 1], 10);
+          }
+          await spacesCommand({ xml: args.includes('--xml'), limit, page });
+        }
         break;
 
       case 'search': {
@@ -271,8 +291,12 @@ async function main(): Promise<void> {
         if (parentIdx !== -1 && parentIdx + 1 < args.length) {
           parentId = args[parentIdx + 1];
         }
-        const createFlagValues = new Set([spaceKey, parentId].filter(Boolean));
-        const title = subArgs.find((arg) => !arg.startsWith('--') && !createFlagValues.has(arg));
+        let createFormat: string | undefined;
+        const createFormatIdx = args.indexOf('--format');
+        if (createFormatIdx !== -1 && createFormatIdx + 1 < args.length) {
+          createFormat = args[createFormatIdx + 1];
+        }
+        const title = findPositional(subArgs, ['--space', '--parent', '--format']);
         if (!title) {
           console.error(chalk.red('Page title is required.'));
           console.log(chalk.gray('Usage: cn create <title>'));
@@ -282,6 +306,7 @@ async function main(): Promise<void> {
           space: spaceKey,
           parent: parentId,
           open: args.includes('--open'),
+          format: createFormat,
         });
         break;
       }
@@ -393,6 +418,40 @@ async function main(): Promise<void> {
         break;
       }
 
+      case 'update': {
+        if (args.includes('--help')) {
+          showUpdateHelp();
+          process.exit(EXIT_CODES.SUCCESS);
+        }
+        let updateFormat: string | undefined;
+        const updateFormatIdx = args.indexOf('--format');
+        if (updateFormatIdx !== -1 && updateFormatIdx + 1 < args.length) {
+          updateFormat = args[updateFormatIdx + 1];
+        }
+        let updateTitle: string | undefined;
+        const updateTitleIdx = args.indexOf('--title');
+        if (updateTitleIdx !== -1 && updateTitleIdx + 1 < args.length) {
+          updateTitle = args[updateTitleIdx + 1];
+        }
+        let updateMessage: string | undefined;
+        const updateMessageIdx = args.indexOf('--message');
+        if (updateMessageIdx !== -1 && updateMessageIdx + 1 < args.length) {
+          updateMessage = args[updateMessageIdx + 1];
+        }
+        const updateId = findPositional(subArgs, ['--format', '--title', '--message']);
+        if (!updateId) {
+          console.error(chalk.red('Page ID is required.'));
+          console.log(chalk.gray('Usage: cn update <id>'));
+          process.exit(EXIT_CODES.INVALID_ARGUMENTS);
+        }
+        await updateCommand(updateId, {
+          format: updateFormat,
+          title: updateTitle,
+          message: updateMessage,
+        });
+        break;
+      }
+
       default:
         console.error(`Unknown command: ${command}`);
         console.log('Run "cn help" for usage information');

package/src/cli/utils/args.ts

@@ -0,0 +1,15 @@
+/**
+ * Find a positional argument in args, skipping flags and their values.
+ * --flag <value> pairs are identified by their indices so we never mistake
+ * a flag's value for a positional argument even if they are equal strings.
+ */
+export function findPositional(args: string[], flagsWithValues: string[]): string | undefined {
+  const flagValueIndices = new Set<number>();
+  for (const flag of flagsWithValues) {
+    const idx = args.indexOf(flag);
+    if (idx !== -1 && idx + 1 < args.length) {
+      flagValueIndices.add(idx + 1);
+    }
+  }
+  return args.find((arg, i) => !arg.startsWith('--') && !flagValueIndices.has(i));
+}

package/src/cli/utils/stdin.ts

@@ -0,0 +1,14 @@
+export async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString('utf-8');
+}
+
+export const VALID_FORMATS = ['storage', 'wiki', 'atlas_doc_format'] as const;
+export type ValidFormat = (typeof VALID_FORMATS)[number];
+
+export function isValidFormat(s: string): s is ValidFormat {
+  return (VALID_FORMATS as readonly string[]).includes(s);
+}

package/src/lib/confluence-client/client.ts

@@ -7,7 +7,7 @@ import {
   NetworkError,
   type PageNotFoundError,
   RateLimitError,
-  SpaceNotFoundError,
+  type SpaceNotFoundError,
   type VersionConflictError,
 } from '../errors.js';
 import {
@@ -34,13 +34,20 @@ import {
 import { searchEffect as searchEffectFn } from './search-operations.js';
 import { getAllFooterComments as getAllFooterCommentsFn } from './comment-operations.js';
 import { getUserEffect as getUserEffectFn } from './user-operations.js';
+import {
+  getAllSpaces as getAllSpacesFn,
+  getSpaces as getSpacesFn,
+  getSpacesEffect as getSpacesEffectFn,
+  getSpaceByKey as getSpaceByKeyFn,
+  getSpaceByKeyEffect as getSpaceByKeyEffectFn,
+  getSpaceByIdEffect as getSpaceByIdEffectFn,
+} from './space-operations.js';
 import {
   CommentsResponseSchema,
   FolderSchema,
   LabelsResponseSchema,
   PageSchema,
   PagesResponseSchema,
-  SpaceSchema,
   SpacesResponseSchema,
   type Attachment,
   type AttachmentsResponse,
@@ -109,8 +116,10 @@ export class ConfluenceClient {
   ): Effect.Effect<T, ApiError | AuthError | NetworkError | RateLimitError> {
     const url = `${this.baseUrl}/wiki/api/v2${path}`;
 
+    const verbose = process.env.CN_DEBUG === '1';
     const makeRequest = Effect.tryPromise({
       try: async () => {
+        if (verbose) process.stderr.write(`[debug] fetch: ${url}\n`);
         const response = await fetch(url, {
           ...options,
           headers: {
@@ -170,74 +179,36 @@ export class ConfluenceClient {
 
   /** Get all spaces (Effect version) */
   getSpacesEffect(limit = 25): Effect.Effect<SpacesResponse, ApiError | AuthError | NetworkError | RateLimitError> {
-    return this.fetchWithRetryEffect(`/spaces?limit=${limit}`, SpacesResponseSchema);
+    return getSpacesEffectFn(this.baseUrl, this.authHeader, limit, (path, schema) =>
+      this.fetchWithRetryEffect(path, schema),
+    );
   }
 
-  /** Get all spaces (async version) */
-  async getSpaces(limit = 25): Promise<SpacesResponse> {
-    return this.fetchWithRetry(`/spaces?limit=${limit}`, SpacesResponseSchema);
+  /** Get spaces with offset-based pagination via v1 API */
+  async getSpaces(limit = 25, page = 1): Promise<{ results: Space[]; start: number; limit: number; size: number }> {
+    return getSpacesFn(this.baseUrl, this.authHeader, limit, page);
   }
 
-  /** Get all spaces with pagination (async version) */
+  /** Get all spaces with full cursor pagination */
   async getAllSpaces(): Promise<Space[]> {
-    const allSpaces: Space[] = [];
-    let cursor: string | undefined;
-    do {
-      let path = '/spaces?limit=100';
-      if (cursor) path += `&cursor=${encodeURIComponent(cursor)}`;
-      const response = await this.fetchWithRetry(path, SpacesResponseSchema);
-      allSpaces.push(...response.results);
-      cursor = extractCursor(response._links?.next);
-    } while (cursor);
-    return allSpaces;
+    return getAllSpacesFn(this.baseUrl, this.authHeader, (path, schema) => this.fetchWithRetry(path, schema));
   }
 
   /** Get a space by key (Effect version) */
   getSpaceByKeyEffect(
     key: string,
   ): Effect.Effect<Space, ApiError | AuthError | NetworkError | RateLimitError | SpaceNotFoundError> {
-    return pipe(
-      this.fetchWithRetryEffect(`/spaces?keys=${key}&limit=1`, SpacesResponseSchema),
-      Effect.flatMap((response) => {
-        if (response.results.length === 0) {
-          return Effect.fail(new SpaceNotFoundError(key));
-        }
-        return Effect.succeed(response.results[0]);
-      }),
-    );
+    return getSpaceByKeyEffectFn(key, (path, schema) => this.fetchWithRetryEffect(path, schema));
   }
 
   /** Get a space by key (async version) */
   async getSpaceByKey(key: string): Promise<Space> {
-    const response = await this.fetchWithRetry(`/spaces?keys=${key}&limit=1`, SpacesResponseSchema);
-    if (response.results.length === 0) {
-      throw new SpaceNotFoundError(key);
-    }
-    return response.results[0];
+    return getSpaceByKeyFn(key, (path, schema) => this.fetchWithRetry(path, schema));
   }
 
   /** Get a space by ID (Effect version) */
-  getSpaceByIdEffect(
-    id: string,
-  ): Effect.Effect<Space, ApiError | AuthError | NetworkError | RateLimitError | SpaceNotFoundError> {
-    const baseUrl = this.baseUrl;
-    const authHeader = this.authHeader;
-    return Effect.tryPromise({
-      try: async () => {
-        const url = `${baseUrl}/wiki/api/v2/spaces/${id}`;
-        const response = await fetch(url, { headers: { Authorization: authHeader, Accept: 'application/json' } });
-        if (response.status === 404) throw new SpaceNotFoundError(id);
-        if (response.status === 401) throw new AuthError('Invalid credentials', 401);
-        if (response.status === 403) throw new AuthError('Access denied', 403);
-        if (!response.ok) throw new ApiError(`API error: ${response.status}`, response.status);
-        return Schema.decodeUnknownSync(SpaceSchema)(await response.json());
-      },
-      catch: (error) => {
-        if (error instanceof SpaceNotFoundError || error instanceof AuthError || error instanceof ApiError)
-          return error;
-        return new NetworkError(`Network error: ${error}`);
-      },
-    });
+  getSpaceByIdEffect(id: string): Effect.Effect<Space, ApiError | AuthError | NetworkError | SpaceNotFoundError> {
+    return getSpaceByIdEffectFn(id, this.baseUrl, this.authHeader);
   }
 
   /** Get a space by ID (async version) */

package/src/lib/confluence-client/index.ts

@@ -19,6 +19,7 @@ export type {
   SearchResultItem,
   Space,
   SpacesResponse,
+  SpacesV1Response,
   UpdatePageRequest,
   User,
   Version,

package/src/lib/confluence-client/space-operations.ts

@@ -0,0 +1,133 @@
+import { Effect, pipe, Schema } from 'effect';
+import { ApiError, AuthError, NetworkError, type RateLimitError, SpaceNotFoundError } from '../errors.js';
+import { SpaceSchema, SpacesResponseSchema, SpacesV1ResponseSchema, type Space, type SpacesResponse } from './types.js';
+
+function extractCursor(nextLink: string | undefined): string | undefined {
+  if (!nextLink) return undefined;
+  try {
+    const url = new URL(nextLink, 'https://placeholder.invalid');
+    return url.searchParams.get('cursor') ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function fetchV1<T>(baseUrl: string, authHeader: string, path: string, schema: Schema.Schema<T>): Promise<T> {
+  const url = `${baseUrl}/wiki/rest/api${path}`;
+  const verbose = process.env.CN_DEBUG === '1';
+  if (verbose) process.stderr.write(`[debug] fetchV1: ${url}\n`);
+  const response = await fetch(url, {
+    headers: { Authorization: authHeader, Accept: 'application/json' },
+  });
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new ApiError(`API request failed: ${response.status} ${errorText}`, response.status);
+  }
+  const data = await response.json();
+  return Effect.runPromise(
+    Schema.decodeUnknown(schema)(data).pipe(Effect.mapError((e) => new ApiError(`Invalid response: ${e}`, 500))),
+  );
+}
+
+export function getSpacesEffect(
+  _baseUrl: string,
+  _authHeader: string,
+  limit: number,
+  fetchWithRetryEffect: <T>(
+    path: string,
+    schema: Schema.Schema<T>,
+  ) => Effect.Effect<T, ApiError | AuthError | NetworkError | RateLimitError>,
+): Effect.Effect<SpacesResponse, ApiError | AuthError | NetworkError | RateLimitError> {
+  return fetchWithRetryEffect(`/spaces?limit=${limit}`, SpacesResponseSchema);
+}
+
+export async function getSpaces(
+  baseUrl: string,
+  authHeader: string,
+  limit = 25,
+  page = 1,
+): Promise<{ results: Space[]; start: number; limit: number; size: number }> {
+  const start = (page - 1) * limit;
+  const response = await fetchV1(baseUrl, authHeader, `/space?limit=${limit}&start=${start}`, SpacesV1ResponseSchema);
+  return {
+    ...response,
+    results: response.results.map((s) => ({ ...s, id: String(s.id) })),
+  };
+}
+
+export async function getAllSpaces(
+  baseUrl: string,
+  _authHeader: string,
+  fetchWithRetry: <T>(path: string, schema: Schema.Schema<T>) => Promise<T>,
+): Promise<Space[]> {
+  const verbose = process.env.CN_DEBUG === '1';
+  const allSpaces: Space[] = [];
+  let cursor: string | undefined;
+  let page = 1;
+  do {
+    let path = '/spaces?limit=20';
+    if (cursor) path += `&cursor=${encodeURIComponent(cursor)}`;
+    if (verbose) process.stderr.write(`[debug] getAllSpaces: fetching page ${page} (${baseUrl}/wiki/api/v2${path})\n`);
+    const response = await fetchWithRetry(path, SpacesResponseSchema);
+    if (verbose)
+      process.stderr.write(
+        `[debug] getAllSpaces: got ${response.results.length} spaces, next=${response._links?.next ?? 'none'}\n`,
+      );
+    allSpaces.push(...response.results);
+    cursor = extractCursor(response._links?.next);
+    page++;
+  } while (cursor);
+  if (verbose) process.stderr.write(`[debug] getAllSpaces: done, total=${allSpaces.length}\n`);
+  return allSpaces;
+}
+
+export function getSpaceByKeyEffect(
+  key: string,
+  fetchWithRetryEffect: <T>(
+    path: string,
+    schema: Schema.Schema<T>,
+  ) => Effect.Effect<T, ApiError | AuthError | NetworkError | RateLimitError>,
+): Effect.Effect<Space, ApiError | AuthError | NetworkError | RateLimitError | SpaceNotFoundError> {
+  return pipe(
+    fetchWithRetryEffect(`/spaces?keys=${key}&limit=1`, SpacesResponseSchema),
+    Effect.flatMap((response) => {
+      if (response.results.length === 0) {
+        return Effect.fail(new SpaceNotFoundError(key));
+      }
+      return Effect.succeed(response.results[0]);
+    }),
+  );
+}
+
+export async function getSpaceByKey(
+  key: string,
+  fetchWithRetry: <T>(path: string, schema: Schema.Schema<T>) => Promise<T>,
+): Promise<Space> {
+  const response = await fetchWithRetry(`/spaces?keys=${key}&limit=1`, SpacesResponseSchema);
+  if (response.results.length === 0) {
+    throw new SpaceNotFoundError(key);
+  }
+  return response.results[0];
+}
+
+export function getSpaceByIdEffect(
+  id: string,
+  baseUrl: string,
+  authHeader: string,
+): Effect.Effect<Space, ApiError | AuthError | NetworkError | SpaceNotFoundError> {
+  return Effect.tryPromise({
+    try: async () => {
+      const url = `${baseUrl}/wiki/api/v2/spaces/${id}`;
+      const response = await fetch(url, { headers: { Authorization: authHeader, Accept: 'application/json' } });
+      if (response.status === 404) throw new SpaceNotFoundError(id);
+      if (response.status === 401) throw new AuthError('Invalid credentials', 401);
+      if (response.status === 403) throw new AuthError('Access denied', 403);
+      if (!response.ok) throw new ApiError(`API error: ${response.status}`, response.status);
+      return Schema.decodeUnknownSync(SpaceSchema)(await response.json());
+    },
+    catch: (error) => {
+      if (error instanceof SpaceNotFoundError || error instanceof AuthError || error instanceof ApiError) return error;
+      return new NetworkError(`Network error: ${error}`);
+    },
+  });
+}

package/src/lib/confluence-client/types.ts

@@ -24,7 +24,7 @@ export const SpaceSchema = Schema.Struct({
   name: Schema.String,
   type: Schema.optional(Schema.String),
   status: Schema.optional(Schema.String),
-  homepageId: Schema.optional(Schema.String),
+  homepageId: Schema.optional(Schema.NullOr(Schema.String)),
   description: Schema.optional(
     Schema.NullOr(
       Schema.Struct({
@@ -57,6 +57,23 @@ export const SpacesResponseSchema = Schema.Struct({
 });
 export type SpacesResponse = Schema.Schema.Type<typeof SpacesResponseSchema>;
 
+const SpaceV1Schema = Schema.Struct({
+  id: Schema.Number,
+  key: Schema.String,
+  name: Schema.String,
+  type: Schema.optional(Schema.String),
+  status: Schema.optional(Schema.String),
+  _links: Schema.optional(Schema.Struct({ webui: Schema.optional(Schema.String) })),
+});
+
+export const SpacesV1ResponseSchema = Schema.Struct({
+  results: Schema.Array(SpaceV1Schema),
+  start: Schema.Number,
+  limit: Schema.Number,
+  size: Schema.Number,
+});
+export type SpacesV1Response = Schema.Schema.Type<typeof SpacesV1ResponseSchema>;
+
 /**
  * Page version information
  */
@@ -182,12 +199,19 @@ export interface VersionConflictResponse {
 /**
  * Request body for updating a page
  */
+export const RepresentationSchema = Schema.Union(
+  Schema.Literal('storage'),
+  Schema.Literal('wiki'),
+  Schema.Literal('atlas_doc_format'),
+);
+export type Representation = Schema.Schema.Type<typeof RepresentationSchema>;
+
 export const UpdatePageRequestSchema = Schema.Struct({
   id: Schema.String,
   status: Schema.String,
   title: Schema.String,
   body: Schema.Struct({
-    representation: Schema.Literal('storage'),
+    representation: RepresentationSchema,
     value: Schema.String,
   }),
   version: Schema.Struct({
@@ -206,7 +230,7 @@ export const CreatePageRequestSchema = Schema.Struct({
   title: Schema.String,
   parentId: Schema.optional(Schema.String),
   body: Schema.Struct({
-    representation: Schema.Literal('storage'),
+    representation: RepresentationSchema,
     value: Schema.String,
   }),
 });

package/src/test/confluence-client.test.ts

@@ -23,7 +23,7 @@ describe('ConfluenceClient', () => {
 
     test('throws AuthError on 401', async () => {
       server.use(
-        http.get('*/wiki/api/v2/spaces', () => {
+        http.get('*/wiki/rest/api/space', () => {
           return HttpResponse.json({ error: 'Unauthorized' }, { status: 401 });
         }),
       );
@@ -37,7 +37,7 @@ describe('ConfluenceClient', () => {
 
     test('throws AuthError on 403', async () => {
       server.use(
-        http.get('*/wiki/api/v2/spaces', () => {
+        http.get('*/wiki/rest/api/space', () => {
           return HttpResponse.json({ error: 'Forbidden' }, { status: 403 });
         }),
       );
@@ -63,16 +63,18 @@ describe('ConfluenceClient', () => {
 
     test('handles spaces with null description', async () => {
       server.use(
-        http.get('*/wiki/api/v2/spaces', () => {
+        http.get('*/wiki/rest/api/space', () => {
           return HttpResponse.json({
             results: [
               {
-                id: 'space-null-desc',
+                id: 99,
                 key: 'NULL',
                 name: 'Space with null description',
-                description: null,
               },
             ],
+            start: 0,
+            limit: 25,
+            size: 1,
           });
         }),
       );
@@ -82,7 +84,6 @@ describe('ConfluenceClient', () => {
 
       expect(response.results).toBeArray();
       expect(response.results[0].key).toBe('NULL');
-      expect(response.results[0].description).toBeNull();
     });
   });
 
@@ -425,7 +426,8 @@ describe('ConfluenceClient', () => {
       );
 
       const client = new ConfluenceClient(testConfig);
-      const response = await client.getSpaces();
+      const { Effect } = await import('effect');
+      const response = await Effect.runPromise(client.getSpacesEffect(1));
 
       expect(response.results).toBeArray();
       expect(requestCount).toBe(2);

package/src/test/mocks/handlers.ts

@@ -26,6 +26,18 @@ import {
  * Individual tests should override these with server.use() for specific test scenarios.
  */
 export const handlers = [
+  // Confluence v1 spaces mock (offset-based pagination)
+  http.get('*/wiki/rest/api/space', ({ request }) => {
+    const url = new URL(request.url);
+    const limit = Number(url.searchParams.get('limit') ?? 25);
+    const start = Number(url.searchParams.get('start') ?? 0);
+    const spaces = [
+      { id: 1, key: 'TEST', name: 'Test Space', type: 'global' },
+      { id: 2, key: 'DOCS', name: 'Documentation', type: 'global' },
+    ].slice(start, start + limit);
+    return HttpResponse.json({ results: spaces, start, limit, size: spaces.length });
+  }),
+
   // Confluence spaces mock
   http.get('*/wiki/api/v2/spaces', ({ request }) => {
     const url = new URL(request.url);

package/src/test/spaces.test.ts

@@ -42,7 +42,7 @@ describe('ConfluenceClient - spaces', () => {
 
   test('throws on 401', async () => {
     server.use(
-      http.get('*/wiki/api/v2/spaces', () => {
+      http.get('*/wiki/rest/api/space', () => {
         return HttpResponse.json({ error: 'Unauthorized' }, { status: 401 });
       }),
     );

package/src/test/update.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, test } from 'bun:test';
+import { HttpResponse, http } from 'msw';
+import { ConfluenceClient } from '../lib/confluence-client/client.js';
+import { server } from './setup-msw.js';
+import { createValidPage } from './msw-schema-validation.js';
+import { findPositional } from '../cli/utils/args.js';
+import { isValidFormat, VALID_FORMATS } from '../cli/utils/stdin.js';
+
+const testConfig = {
+  confluenceUrl: 'https://test.atlassian.net',
+  email: 'test@example.com',
+  apiToken: 'test-token',
+};
+
+describe('ConfluenceClient - updatePage', () => {
+  test('updates page successfully', async () => {
+    server.use(
+      http.put('*/wiki/api/v2/pages/:pageId', async ({ request, params }) => {
+        const body = (await request.json()) as { title: string; body: { value: string } };
+        const page = createValidPage({
+          id: params.pageId as string,
+          title: body.title,
+          version: 2,
+        });
+        return HttpResponse.json(page);
+      }),
+    );
+
+    const client = new ConfluenceClient(testConfig);
+    const result = await client.updatePage({
+      id: 'page-123',
+      status: 'current',
+      title: 'Updated Title',
+      body: { representation: 'storage', value: '<p>New content</p>' },
+      version: { number: 2 },
+    });
+
+    expect(result.id).toBe('page-123');
+  });
+
+  test('fetches page without body when includeBody=false', async () => {
+    let requestUrl = '';
+    server.use(
+      http.get('*/wiki/api/v2/pages/:pageId', ({ request }) => {
+        requestUrl = request.url;
+        const page = createValidPage({ id: 'page-123', version: 3 });
+        return HttpResponse.json(page);
+      }),
+    );
+
+    const client = new ConfluenceClient(testConfig);
+    await client.getPage('page-123', false);
+    expect(requestUrl).not.toContain('body-format');
+  });
+
+  test('throws on 404', async () => {
+    server.use(
+      http.put('*/wiki/api/v2/pages/:pageId', () => {
+        return HttpResponse.json({ message: 'Not found' }, { status: 404 });
+      }),
+    );
+
+    const client = new ConfluenceClient(testConfig);
+    await expect(
+      client.updatePage({
+        id: 'nonexistent',
+        status: 'current',
+        title: 'Title',
+        body: { representation: 'storage', value: '<p>x</p>' },
+        version: { number: 2 },
+      }),
+    ).rejects.toThrow();
+  });
+});
+
+describe('format validation', () => {
+  test('accepts valid formats', () => {
+    for (const fmt of VALID_FORMATS) {
+      expect(isValidFormat(fmt)).toBe(true);
+    }
+  });
+
+  test('rejects markdown', () => {
+    expect(isValidFormat('markdown')).toBe(false);
+  });
+
+  test('rejects unknown format', () => {
+    expect(isValidFormat('html')).toBe(false);
+  });
+});
+
+describe('findPositional', () => {
+  test('finds simple positional arg', () => {
+    expect(findPositional(['123456'], ['--format', '--title'])).toBe('123456');
+  });
+
+  test('skips flag and its value, not confusing them with positional', () => {
+    // cn update --title 123 123  =>  subArgs: ['--title', '123', '123']  =>  positional is second 123
+    expect(findPositional(['--title', '123', '123'], ['--title'])).toBe('123');
+  });
+
+  test('id equals title value — skips by index not value', () => {
+    // cn update 123 --title 123  =>  subArgs: ['123', '--title', '123']  =>  positional is first 123
+    expect(findPositional(['123', '--title', '123'], ['--title'])).toBe('123');
+  });
+
+  test('returns undefined when no positional', () => {
+    expect(findPositional(['--title', 'Some Title'], ['--title'])).toBeUndefined();
+  });
+
+  test('create: title equals space value', () => {
+    // cn create ENG --space ENG  =>  subArgs: ['ENG', '--space', 'ENG']  =>  positional is ENG
+    expect(findPositional(['ENG', '--space', 'ENG'], ['--space', '--parent', '--format'])).toBe('ENG');
+  });
+});