roam-research-mcp 1.6.0 → 2.4.0

package/build/cli/commands/batch.js

@@ -0,0 +1,352 @@
+import { Command } from 'commander';
+import { readFileSync } from 'fs';
+import { BatchOperations } from '../../tools/operations/batch.js';
+import { PageOperations } from '../../tools/operations/pages.js';
+import { printDebug, exitWithError } from '../utils/output.js';
+import { resolveGraph } from '../utils/graph.js';
+import { collectPageTitles, resolveAllPages, resolveDailyPageUid, needsDailyPage, createResolutionContext, getDailyPageTitle } from '../batch/resolver.js';
+import { translateAllCommands } from '../batch/translator.js';
+/** Read all input from stdin */
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString('utf-8');
+}
+// Required params per command type
+const REQUIRED_PARAMS = {
+    todo: ['text'],
+    create: ['parent', 'text'],
+    update: ['uid'],
+    delete: ['uid'],
+    move: ['uid', 'parent'],
+    page: ['title'],
+    outline: ['parent', 'items'],
+    table: ['parent', 'headers', 'rows'],
+    remember: ['text'],
+    codeblock: ['parent', 'code']
+};
+const VALID_COMMAND_TYPES = Object.keys(REQUIRED_PARAMS);
+/**
+ * Validate command structure and required params
+ */
+function validateCommands(commands) {
+    const validated = [];
+    for (let i = 0; i < commands.length; i++) {
+        const cmd = commands[i];
+        if (!cmd || typeof cmd !== 'object') {
+            throw new Error(`[${i}] Command must be an object`);
+        }
+        if (!cmd.command || typeof cmd.command !== 'string') {
+            throw new Error(`[${i}] Missing 'command' field`);
+        }
+        const cmdType = cmd.command;
+        if (!VALID_COMMAND_TYPES.includes(cmdType)) {
+            throw new Error(`[${i}] Unknown command type '${cmdType}'. Valid: ${VALID_COMMAND_TYPES.join(', ')}`);
+        }
+        if (!cmd.params || typeof cmd.params !== 'object') {
+            throw new Error(`[${i}] Missing 'params' field`);
+        }
+        // Check required params
+        const params = cmd.params;
+        const required = REQUIRED_PARAMS[cmdType];
+        for (const param of required) {
+            if (params[param] === undefined) {
+                throw new Error(`[${i}] ${cmdType}: missing required param '${param}'`);
+            }
+        }
+        validated.push(cmd);
+    }
+    return validated;
+}
+/**
+ * Validate placeholder references are defined before use
+ * Returns list of errors (empty = valid)
+ */
+function validatePlaceholders(commands) {
+    const errors = [];
+    const definedPlaceholders = new Set();
+    for (let i = 0; i < commands.length; i++) {
+        const cmd = commands[i];
+        const params = cmd.params;
+        // Collect placeholder definitions from 'as' params
+        if (typeof params.as === 'string') {
+            definedPlaceholders.add(params.as);
+        }
+        // Check placeholder references in 'parent' param
+        if (typeof params.parent === 'string') {
+            const match = params.parent.match(/^\{\{(\w+)\}\}$/);
+            if (match) {
+                const refName = match[1];
+                if (!definedPlaceholders.has(refName)) {
+                    errors.push(`[${i}] ${cmd.command}: placeholder "{{${refName}}}" used before definition`);
+                }
+            }
+        }
+    }
+    return errors;
+}
+/**
+ * Output partial results when a failure occurs mid-batch
+ * Helps user know what was created and may need manual cleanup
+ */
+function outputPartialResults(pageResults, failedPage, batchError) {
+    const output = {
+        success: false,
+        partial: true,
+        pages_created: pageResults.length,
+        ...(failedPage && { failed_at: `page: ${failedPage}` }),
+        ...(batchError && { failed_at: `batch: ${batchError}` })
+    };
+    if (pageResults.length > 0) {
+        output.created_pages = pageResults.map(p => ({
+            title: p.title,
+            uid: p.uid
+        }));
+        output.cleanup_hint = 'Pages listed above were created before failure. Delete manually if needed.';
+    }
+    console.error(JSON.stringify(output, null, 2));
+    process.exit(1);
+}
+/** Format action for dry-run display */
+function formatAction(action, index) {
+    const lines = [`  ${index + 1}. ${action.action}`];
+    if (action.string) {
+        const text = String(action.string);
+        const preview = text.length > 60 ? text.slice(0, 60) + '...' : text;
+        lines.push(`     text: "${preview}"`);
+    }
+    if (action.location) {
+        const loc = action.location;
+        lines.push(`     parent: ${loc['parent-uid']}`);
+    }
+    if (action.uid) {
+        lines.push(`     uid: ${action.uid}`);
+    }
+    return lines.join('\n');
+}
+export function createBatchCommand() {
+    return new Command('batch')
+        .description('Execute multiple block operations efficiently in a single API call')
+        .argument('[file]', 'JSON file with commands (or pipe via stdin)')
+        .option('--debug', 'Show debug information')
+        .option('--dry-run', 'Validate and show planned actions without executing')
+        .option('--simulate', 'Validate structure offline (no API calls)')
+        .option('-g, --graph <name>', 'Target graph key (for multi-graph mode)')
+        .option('--write-key <key>', 'Write confirmation key (for non-default graphs)')
+        .addHelpText('after', `
+Examples:
+  # From file
+  roam batch commands.json                # Execute commands from file
+  roam batch commands.json --dry-run      # Preview without executing (resolves pages)
+  roam batch commands.json --simulate     # Validate offline (no API calls)
+
+  # From stdin
+  cat commands.json | roam batch          # Pipe commands
+  echo '[{"command":"todo","params":{"text":"Task 1"}}]' | roam batch
+
+Command schemas:
+  todo:      {text}
+  create:    {parent, text, as?, heading?, order?}
+  update:    {uid, text?, heading?, open?}
+  delete:    {uid}
+  move:      {uid, parent, order?}
+  page:      {title, as?, content?: [{text, level, heading?}...]}
+  outline:   {parent, items: [string...]}
+  table:     {parent, headers: [string...], rows: [{label, cells: [string...]}...]}
+  remember:  {text, categories?: [string...]}
+  codeblock: {parent, code, language?}
+
+Parent accepts: block UID, "daily", page title, or {{placeholder}}
+
+Example:
+  [
+    {"command": "page", "params": {"title": "Project X", "as": "proj"}},
+    {"command": "create", "params": {"parent": "{{proj}}", "text": "# Overview", "as": "overview"}},
+    {"command": "outline", "params": {"parent": "{{overview}}", "items": ["Goal 1", "Goal 2"]}},
+    {"command": "todo", "params": {"text": "Review project"}}
+  ]
+`)
+        .action(async (file, options) => {
+        try {
+            // Read input
+            let rawInput;
+            if (file) {
+                try {
+                    rawInput = readFileSync(file, 'utf-8');
+                }
+                catch {
+                    exitWithError(`Could not read file: ${file}`);
+                }
+            }
+            else if (process.stdin.isTTY) {
+                exitWithError('No file specified and no input piped. Use: roam batch commands.json or cat commands.json | roam batch');
+            }
+            else {
+                rawInput = await readStdin();
+            }
+            // Parse JSON
+            let parsed;
+            try {
+                parsed = JSON.parse(rawInput);
+            }
+            catch (err) {
+                exitWithError(`Invalid JSON: ${err instanceof SyntaxError ? err.message : 'parse error'}`);
+            }
+            if (!Array.isArray(parsed)) {
+                exitWithError('Input must be a JSON array of commands');
+            }
+            if (parsed.length === 0) {
+                console.log('No commands to execute');
+                return;
+            }
+            // Validate and get typed commands
+            const commands = validateCommands(parsed);
+            // Upfront validation: check placeholder references
+            const placeholderErrors = validatePlaceholders(commands);
+            if (placeholderErrors.length > 0) {
+                exitWithError(`Placeholder validation failed:\n  ${placeholderErrors.join('\n  ')}`);
+            }
+            if (options.debug) {
+                printDebug('Commands', commands.length);
+                printDebug('Graph', options.graph || 'default');
+                printDebug('Mode', options.simulate ? 'simulate' : options.dryRun ? 'dry-run' : 'execute');
+            }
+            // Simulate mode: validate structure without connecting to Roam
+            if (options.simulate) {
+                const context = createResolutionContext();
+                const { actions, pageCommands } = translateAllCommands(commands, context);
+                console.log('\n[SIMULATE] Validation passed\n');
+                console.log(`Commands: ${commands.length}`);
+                console.log(`  Pages to create: ${pageCommands.length}`);
+                console.log(`  Batch actions: ${actions.length}`);
+                if (pageCommands.length > 0) {
+                    console.log('\nPage creations:');
+                    for (const pc of pageCommands) {
+                        const as = pc.params.as ? ` → {{${pc.params.as}}}` : '';
+                        console.log(`  - "${pc.params.title}"${as}`);
+                    }
+                }
+                console.log('\nNo API calls made. Use --dry-run to resolve page UIDs.');
+                return;
+            }
+            const graph = resolveGraph(options, true);
+            // Phase 1: Collect and resolve page titles
+            const context = createResolutionContext();
+            const pageTitles = collectPageTitles(commands);
+            if (pageTitles.size > 0) {
+                if (options.debug) {
+                    printDebug('Pages to resolve', Array.from(pageTitles));
+                }
+                const resolved = await resolveAllPages(graph, pageTitles);
+                for (const [title, uid] of resolved) {
+                    context.pageUids.set(title, uid);
+                }
+                // Check for unresolved pages
+                const unresolved = Array.from(pageTitles).filter(t => !context.pageUids.has(t));
+                if (unresolved.length > 0) {
+                    exitWithError(`Page(s) not found: ${unresolved.map(t => `"${t}"`).join(', ')}`);
+                }
+                if (options.debug) {
+                    printDebug('Resolved pages', Object.fromEntries(context.pageUids));
+                }
+            }
+            // Resolve daily page if needed
+            if (needsDailyPage(commands)) {
+                const dailyUid = await resolveDailyPageUid(graph);
+                if (!dailyUid) {
+                    exitWithError(`Daily page not found: "${getDailyPageTitle()}"`);
+                }
+                context.dailyPageUid = dailyUid;
+                context.pageUids.set(getDailyPageTitle(), dailyUid);
+                if (options.debug) {
+                    printDebug('Daily page UID', dailyUid);
+                }
+            }
+            // Phase 2: Translate commands to batch actions
+            const { actions, pageCommands } = translateAllCommands(commands, context);
+            if (options.debug) {
+                printDebug('Batch actions', actions.length);
+                printDebug('Page commands', pageCommands.length);
+            }
+            // Dry run: show actions and exit
+            if (options.dryRun) {
+                console.log('\n[DRY RUN] Planned actions:\n');
+                if (pageCommands.length > 0) {
+                    console.log('Page creations:');
+                    for (const pc of pageCommands) {
+                        const as = pc.params.as ? ` (as: {{${pc.params.as}}})` : '';
+                        console.log(`  - "${pc.params.title}"${as}`);
+                    }
+                    console.log('');
+                }
+                if (actions.length > 0) {
+                    console.log('Batch actions:');
+                    console.log(actions.map((a, i) => formatAction(a, i)).join('\n'));
+                }
+                console.log(`\nTotal: ${pageCommands.length} page(s), ${actions.length} action(s)`);
+                return;
+            }
+            // Phase 3: Execute page commands (in parallel where possible)
+            const pageResults = [];
+            if (pageCommands.length > 0) {
+                const pageOps = new PageOperations(graph);
+                // Execute page creations - must be sequential if they reference each other
+                for (const pc of pageCommands) {
+                    const result = await pageOps.createPage(pc.params.title, pc.params.content?.map(item => ({
+                        text: item.text,
+                        level: item.level,
+                        heading: item.heading
+                    })));
+                    if (!result.success) {
+                        // Report partial results before exiting
+                        outputPartialResults(pageResults, pc.params.title);
+                    }
+                    pageResults.push({ title: pc.params.title, uid: result.uid });
+                    if (pc.params.as) {
+                        context.placeholders.set(pc.params.as, result.uid);
+                    }
+                    if (options.debug) {
+                        printDebug(`Created "${pc.params.title}"`, result.uid);
+                    }
+                }
+            }
+            // Phase 4: Execute batch actions
+            let batchResult = { success: true, actions_attempted: 0 };
+            if (actions.length > 0) {
+                const batchOps = new BatchOperations(graph);
+                batchResult = await batchOps.processBatch(actions);
+                if (!batchResult.success) {
+                    const errorMsg = typeof batchResult.error === 'string'
+                        ? batchResult.error
+                        : batchResult.error?.message || 'Unknown error';
+                    // Report partial results (pages created before batch failed)
+                    outputPartialResults(pageResults, undefined, errorMsg);
+                }
+            }
+            // Build output
+            const uidMap = {};
+            for (const pr of pageResults) {
+                const pageCmd = pageCommands.find(pc => pc.params.title === pr.title);
+                if (pageCmd?.params.as) {
+                    uidMap[pageCmd.params.as] = pr.uid;
+                }
+            }
+            if (batchResult.uid_map) {
+                Object.assign(uidMap, batchResult.uid_map);
+            }
+            const output = {
+                success: true,
+                pages_created: pageResults.length,
+                actions_executed: actions.length,
+                ...(Object.keys(uidMap).length > 0 && { uid_map: uidMap })
+            };
+            console.log(JSON.stringify(output, null, 2));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            exitWithError(message);
+        }
+    });
+}

package/build/cli/commands/get.js

@@ -1,27 +1,80 @@
 import { Command } from 'commander';
-import { initializeGraph } from '@roam-research/roam-api-sdk';
-import { API_TOKEN, GRAPH_NAME } from '../../config/environment.js';
 import { PageOperations } from '../../tools/operations/pages.js';
 import { BlockRetrievalOperations } from '../../tools/operations/block-retrieval.js';
-import { formatPageOutput, formatBlockOutput, printDebug, exitWithError } from '../utils/output.js';
+import { SearchOperations } from '../../tools/operations/search/index.js';
+import { formatPageOutput, formatBlockOutput, formatTodoOutput, printDebug, exitWithError } from '../utils/output.js';
+import { resolveGraph } from '../utils/graph.js';
+import { resolveRefs } from '../../tools/helpers/refs.js';
+import { resolveRelativeDate } from '../../utils/helpers.js';
 // Block UID pattern: 9 alphanumeric characters, optionally wrapped in (( ))
 const BLOCK_UID_PATTERN = /^(?:\(\()?([a-zA-Z0-9_-]{9})(?:\)\))?$/;
+/**
+ * Recursively resolve block references in a RoamBlock tree
+ */
+async function resolveBlockRefs(graph, block, maxDepth) {
+    const resolvedString = await resolveRefs(graph, block.string, 0, maxDepth);
+    const resolvedChildren = await Promise.all((block.children || []).map(child => resolveBlockRefs(graph, child, maxDepth)));
+    return {
+        ...block,
+        string: resolvedString,
+        children: resolvedChildren
+    };
+}
+/**
+ * Resolve refs in an array of blocks
+ */
+async function resolveBlocksRefs(graph, blocks, maxDepth) {
+    return Promise.all(blocks.map(block => resolveBlockRefs(graph, block, maxDepth)));
+}
 export function createGetCommand() {
     return new Command('get')
-        .description('Fetch a page or block from Roam')
-        .argument('<target>', 'Page title or block UID (e.g., "Page Title" or "((AbCdEfGhI))")')
-        .option('--json', 'Output as JSON instead of markdown')
-        .option('--depth <n>', 'Child levels to fetch (default: 4)', '4')
-        .option('--refs <n>', 'Block ref expansion depth (default: 1)', '1')
-        .option('--flat', 'Flatten hierarchy to single-level list')
+        .description('Fetch pages, blocks, or TODO/DONE items with optional ref expansion')
+        .argument('[target]', 'Page title, block UID, or relative date (today/yesterday/tomorrow)')
+        .option('-j, --json', 'Output as JSON instead of markdown')
+        .option('-d, --depth <n>', 'Child levels to fetch (default: 4)', '4')
+        .option('-r, --refs [n]', 'Expand ((uid)) refs in output (default depth: 1, max: 4)')
+        .option('-f, --flat', 'Flatten hierarchy to single-level list')
+        .option('--todo', 'Fetch TODO items')
+        .option('--done', 'Fetch DONE items')
+        .option('-p, --page <ref>', 'Filter TODOs/DONEs by page title or UID')
+        .option('-i, --include <terms>', 'Include items matching these terms (comma-separated)')
+        .option('-e, --exclude <terms>', 'Exclude items matching these terms (comma-separated)')
+        .option('-g, --graph <name>', 'Target graph key (multi-graph mode)')
         .option('--debug', 'Show query metadata')
+        .addHelpText('after', `
+Examples:
+  # Fetch pages
+  roam get "Project Notes"                    # Page by title
+  roam get today                              # Today's daily page
+  roam get yesterday                          # Yesterday's daily page
+  roam get tomorrow                           # Tomorrow's daily page
+
+  # Fetch blocks
+  roam get abc123def                          # Block by UID
+  roam get "((abc123def))"                    # UID with wrapper
+
+  # Output options
+  roam get "Page" -j                          # JSON output
+  roam get "Page" -f                          # Flat list (no hierarchy)
+  roam get abc123def -d 2                     # Limit depth to 2 levels
+  roam get "Page" -r                          # Expand block refs (depth 1)
+  roam get "Page" -r 3                        # Expand refs up to 3 levels deep
+
+  # TODO/DONE items (refs auto-expanded)
+  roam get --todo                             # All TODOs across graph
+  roam get --done                             # All completed items
+  roam get --todo -p "Work"                   # TODOs on "Work" page
+  roam get --todo -i "urgent,blocker"         # TODOs containing these terms
+  roam get --todo -e "someday,maybe"          # Exclude items with terms
+`)
         .action(async (target, options) => {
         try {
-            const graph = initializeGraph({
-                token: API_TOKEN,
-                graph: GRAPH_NAME
-            });
+            const graph = resolveGraph(options, false);
             const depth = parseInt(options.depth || '4', 10);
+            // Parse refs: true/string means enabled, number sets max depth (default 1, max 4)
+            const refsDepth = options.refs !== undefined
+                ? Math.min(4, Math.max(1, parseInt(options.refs, 10) || 1))
+                : 0;
             const outputOptions = {
                 json: options.json,
                 flat: options.flat,
@@ -29,10 +82,31 @@ export function createGetCommand() {
             };
             if (options.debug) {
                 printDebug('Target', target);
-                printDebug('Options', { depth, refs: options.refs, ...outputOptions });
+                printDebug('Graph', options.graph || 'default');
+                printDebug('Options', { depth, refs: refsDepth || 'off', ...outputOptions });
+            }
+            // Handle --todo or --done flags
+            if (options.todo || options.done) {
+                const status = options.todo ? 'TODO' : 'DONE';
+                if (options.debug) {
+                    printDebug('Status search', { status, page: options.page, include: options.include, exclude: options.exclude });
+                }
+                const searchOps = new SearchOperations(graph);
+                const result = await searchOps.searchByStatus(status, options.page, options.include, options.exclude);
+                console.log(formatTodoOutput(result.matches, status, outputOptions));
+                return;
+            }
+            // For page/block fetching, target is required
+            if (!target) {
+                exitWithError('Target is required. Use: roam get <page-title> or roam get --todo');
+            }
+            // Resolve relative date keywords (today, yesterday, tomorrow)
+            const resolvedTarget = resolveRelativeDate(target);
+            if (options.debug && resolvedTarget !== target) {
+                printDebug('Resolved date', `${target} → ${resolvedTarget}`);
             }
             // Check if target is a block UID
-            const uidMatch = target.match(BLOCK_UID_PATTERN);
+            const uidMatch = resolvedTarget.match(BLOCK_UID_PATTERN);
             if (uidMatch) {
                 // Fetch block by UID
                 const blockUid = uidMatch[1];
@@ -40,19 +114,23 @@ export function createGetCommand() {
                     printDebug('Fetching block', { uid: blockUid, depth });
                 }
                 const blockOps = new BlockRetrievalOperations(graph);
-                const block = await blockOps.fetchBlockWithChildren(blockUid, depth);
+                let block = await blockOps.fetchBlockWithChildren(blockUid, depth);
                 if (!block) {
                     exitWithError(`Block with UID "${blockUid}" not found`);
                 }
+                // Resolve block references if requested
+                if (refsDepth > 0) {
+                    block = await resolveBlockRefs(graph, block, refsDepth);
+                }
                 console.log(formatBlockOutput(block, outputOptions));
             }
             else {
                 // Fetch page by title
                 if (options.debug) {
-                    printDebug('Fetching page', { title: target, depth });
+                    printDebug('Fetching page', { title: resolvedTarget, depth });
                 }
                 const pageOps = new PageOperations(graph);
-                const result = await pageOps.fetchPageByTitle(target, 'raw');
+                const result = await pageOps.fetchPageByTitle(resolvedTarget, 'raw');
                 // Parse the raw result
                 let blocks;
                 if (typeof result === 'string') {
@@ -68,7 +146,11 @@ export function createGetCommand() {
                 else {
                     blocks = result;
                 }
-                console.log(formatPageOutput(target, blocks, outputOptions));
+                // Resolve block references if requested
+                if (refsDepth > 0) {
+                    blocks = await resolveBlocksRefs(graph, blocks, refsDepth);
+                }
+                console.log(formatPageOutput(resolvedTarget, blocks, outputOptions));
             }
         }
         catch (error) {

package/build/cli/commands/refs.js

@@ -1,8 +1,7 @@
 import { Command } from 'commander';
-import { initializeGraph } from '@roam-research/roam-api-sdk';
-import { API_TOKEN, GRAPH_NAME } from '../../config/environment.js';
 import { SearchOperations } from '../../tools/operations/search/index.js';
 import { printDebug, exitWithError } from '../utils/output.js';
+import { resolveGraph } from '../utils/graph.js';
 /**
  * Format results grouped by page (default output)
  */
@@ -72,22 +71,36 @@ function parseIdentifier(identifier) {
 }
 export function createRefsCommand() {
     return new Command('refs')
-        .description('Find blocks referencing a page or block')
-        .argument('<identifier>', 'Page title or block UID (use ((uid)) for block refs)')
+        .description('Find all blocks that reference a page, tag, or block')
+        .argument('<identifier>', 'Page title, #tag, [[Page]], or ((block-uid))')
         .option('-n, --limit <n>', 'Limit number of results', '50')
         .option('--json', 'Output as JSON array')
         .option('--raw', 'Output raw UID + content lines (no grouping)')
         .option('--debug', 'Show query metadata')
+        .option('-g, --graph <name>', 'Target graph key (for multi-graph mode)')
+        .addHelpText('after', `
+Examples:
+  # Page references
+  roam refs "Project Alpha"               # Blocks linking to page
+  roam refs "[[Meeting Notes]]"           # With bracket syntax
+  roam refs "#TODO"                       # Blocks with #TODO tag
+
+  # Block references
+  roam refs "((abc123def))"               # Blocks embedding this block
+
+  # Output options
+  roam refs "Work" --json                 # JSON array output
+  roam refs "Ideas" --raw                 # Raw UID + content (no grouping)
+  roam refs "Tasks" -n 100                # Limit to 100 results
+`)
         .action(async (identifier, options) => {
         try {
-            const graph = initializeGraph({
-                token: API_TOKEN,
-                graph: GRAPH_NAME
-            });
+            const graph = resolveGraph(options, false);
             const limit = parseInt(options.limit || '50', 10);
             const { block_uid, title } = parseIdentifier(identifier);
             if (options.debug) {
                 printDebug('Identifier', identifier);
+                printDebug('Graph', options.graph || 'default');
                 printDebug('Parsed', { block_uid, title });
                 printDebug('Options', options);
             }

package/build/cli/commands/rename.js

@@ -0,0 +1,58 @@
+import { Command } from 'commander';
+import { updatePage } from '@roam-research/roam-api-sdk';
+import { printDebug, exitWithError } from '../utils/output.js';
+import { resolveGraph } from '../utils/graph.js';
+export function createRenameCommand() {
+    return new Command('rename')
+        .description('Rename a page')
+        .argument('<old-title>', 'Current page title (or use --uid for UID)')
+        .argument('<new-title>', 'New page title')
+        .option('-u, --uid <uid>', 'Use page UID instead of title')
+        .option('-g, --graph <name>', 'Target graph key (multi-graph mode)')
+        .option('--write-key <key>', 'Write confirmation key (non-default graphs)')
+        .option('--debug', 'Show debug information')
+        .addHelpText('after', `
+Examples:
+  # Rename by title
+  roam rename "Old Page Name" "New Page Name"
+
+  # Rename by UID
+  roam rename --uid abc123def "New Page Name"
+
+  # Multi-graph
+  roam rename "Draft" "Published" -g work --write-key confirm
+`)
+        .action(async (oldTitle, newTitle, options) => {
+        try {
+            if (options.debug) {
+                printDebug('Old title', oldTitle);
+                printDebug('New title', newTitle);
+                printDebug('UID', options.uid || 'none (using title)');
+                printDebug('Graph', options.graph || 'default');
+            }
+            const graph = resolveGraph(options, true); // Write operation
+            // Build the page identifier
+            const pageIdentifier = options.uid
+                ? { uid: options.uid }
+                : { title: oldTitle };
+            if (options.debug) {
+                printDebug('Page identifier', pageIdentifier);
+            }
+            const success = await updatePage(graph, {
+                page: pageIdentifier,
+                title: newTitle
+            });
+            if (success) {
+                const identifier = options.uid ? `((${options.uid}))` : `"${oldTitle}"`;
+                console.log(`Renamed ${identifier} → "${newTitle}"`);
+            }
+            else {
+                exitWithError('Failed to rename page (API returned false)');
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            exitWithError(message);
+        }
+    });
+}