roam-research-mcp 2.4.0 → 2.4.3

package/build/cli/commands/get.js

@@ -4,6 +4,7 @@ import { BlockRetrievalOperations } from '../../tools/operations/block-retrieval
 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 { readStdin } from '../utils/input.js';
 import { resolveRefs } from '../../tools/helpers/refs.js';
 import { resolveRelativeDate } from '../../utils/helpers.js';
 // Block UID pattern: 9 alphanumeric characters, optionally wrapped in (( ))
@@ -29,7 +30,7 @@ async function resolveBlocksRefs(graph, blocks, maxDepth) {
 export function createGetCommand() {
     return new Command('get')
         .description('Fetch pages, blocks, or TODO/DONE items with optional ref expansion')
-        .argument('[target]', 'Page title, block UID, or relative date (today/yesterday/tomorrow)')
+        .argument('[target]', 'Page title, block UID, or relative date. Reads from stdin if "-" or omitted.')
         .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)')
@@ -47,12 +48,16 @@ Examples:
   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
 
+  # Stdin / Batch Retrieval
+  echo "Project A" | roam get                 # Pipe page title
+  echo "abc123def" | roam get                 # Pipe block UID
+  cat uids.txt | roam get --json              # Fetch multiple blocks (NDJSON output)
+
   # Output options
   roam get "Page" -j                          # JSON output
   roam get "Page" -f                          # Flat list (no hierarchy)
@@ -64,8 +69,6 @@ Examples:
   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 {
@@ -81,11 +84,12 @@ Examples:
                 debug: options.debug
             };
             if (options.debug) {
-                printDebug('Target', target);
+                printDebug('Target', target || 'stdin');
                 printDebug('Graph', options.graph || 'default');
                 printDebug('Options', { depth, refs: refsDepth || 'off', ...outputOptions });
             }
-            // Handle --todo or --done flags
+            // Handle --todo or --done flags (these ignore target arg usually, but could filter by page if target is used as page?)
+            // The help says "-p" is for page. So we strictly follow flags.
             if (options.todo || options.done) {
                 const status = options.todo ? 'TODO' : 'DONE';
                 if (options.debug) {
@@ -96,61 +100,88 @@ Examples:
                 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}`);
+            // Determine targets
+            let targets = [];
+            if (target && target !== '-') {
+                targets = [target];
             }
-            // Check if target is a block UID
-            const uidMatch = resolvedTarget.match(BLOCK_UID_PATTERN);
-            if (uidMatch) {
-                // Fetch block by UID
-                const blockUid = uidMatch[1];
-                if (options.debug) {
-                    printDebug('Fetching block', { uid: blockUid, depth });
-                }
-                const blockOps = new BlockRetrievalOperations(graph);
-                let block = await blockOps.fetchBlockWithChildren(blockUid, depth);
-                if (!block) {
-                    exitWithError(`Block with UID "${blockUid}" not found`);
+            else {
+                // Read from stdin if no target or explicit '-'
+                if (process.stdin.isTTY && target !== '-') {
+                    // If TTY and no target, show error
+                    exitWithError('Target is required. Use: roam get <page-title>, roam get --todo, or pipe targets via stdin');
                 }
-                // Resolve block references if requested
-                if (refsDepth > 0) {
-                    block = await resolveBlockRefs(graph, block, refsDepth);
+                const input = await readStdin();
+                if (input) {
+                    targets = input.split('\n').map(t => t.trim()).filter(Boolean);
                 }
-                console.log(formatBlockOutput(block, outputOptions));
             }
-            else {
-                // Fetch page by title
-                if (options.debug) {
-                    printDebug('Fetching page', { title: resolvedTarget, depth });
+            if (targets.length === 0) {
+                exitWithError('No targets provided');
+            }
+            // Helper to process a single target
+            const processTarget = async (item) => {
+                // Resolve relative date keywords (today, yesterday, tomorrow)
+                const resolvedTarget = resolveRelativeDate(item);
+                if (options.debug && resolvedTarget !== item) {
+                    printDebug('Resolved date', `${item} → ${resolvedTarget}`);
                 }
-                const pageOps = new PageOperations(graph);
-                const result = await pageOps.fetchPageByTitle(resolvedTarget, 'raw');
-                // Parse the raw result
-                let blocks;
-                if (typeof result === 'string') {
-                    try {
-                        blocks = JSON.parse(result);
+                // Check if target is a block UID
+                const uidMatch = resolvedTarget.match(BLOCK_UID_PATTERN);
+                if (uidMatch) {
+                    // Fetch block by UID
+                    const blockUid = uidMatch[1];
+                    if (options.debug)
+                        printDebug('Fetching block', { uid: blockUid });
+                    const blockOps = new BlockRetrievalOperations(graph);
+                    let block = await blockOps.fetchBlockWithChildren(blockUid, depth);
+                    if (!block) {
+                        // If fetching multiple, maybe warn instead of exit?
+                        // For now, consistent behavior: print error message to stderr but continue?
+                        // Or simpler: just return a "not found" string/object.
+                        // formatBlockOutput doesn't handle null.
+                        return options.json ? JSON.stringify({ error: `Block ${blockUid} not found` }) : `Block ${blockUid} not found`;
                     }
-                    catch {
-                        // Result is already formatted as string (e.g., "Page Title (no content found)")
-                        console.log(result);
-                        return;
+                    // Resolve block references if requested
+                    if (refsDepth > 0) {
+                        block = await resolveBlockRefs(graph, block, refsDepth);
                     }
+                    return formatBlockOutput(block, outputOptions);
                 }
                 else {
-                    blocks = result;
-                }
-                // Resolve block references if requested
-                if (refsDepth > 0) {
-                    blocks = await resolveBlocksRefs(graph, blocks, refsDepth);
+                    // Fetch page by title
+                    if (options.debug)
+                        printDebug('Fetching page', { title: resolvedTarget });
+                    const pageOps = new PageOperations(graph);
+                    const result = await pageOps.fetchPageByTitle(resolvedTarget, 'raw');
+                    // Parse the raw result
+                    let blocks;
+                    if (typeof result === 'string') {
+                        try {
+                            blocks = JSON.parse(result);
+                        }
+                        catch {
+                            // Result is already formatted as string (e.g., "Page Title (no content found)")
+                            // But wait, fetchPageByTitle returns string if not found or empty?
+                            // Actually fetchPageByTitle 'raw' returns JSON string of blocks OR empty array JSON string?
+                            // Let's assume result is valid JSON or error message string.
+                            return options.json ? JSON.stringify({ title: resolvedTarget, error: result }) : result;
+                        }
+                    }
+                    else {
+                        blocks = result;
+                    }
+                    // Resolve block references if requested
+                    if (refsDepth > 0) {
+                        blocks = await resolveBlocksRefs(graph, blocks, refsDepth);
+                    }
+                    return formatPageOutput(resolvedTarget, blocks, outputOptions);
                 }
-                console.log(formatPageOutput(resolvedTarget, blocks, outputOptions));
+            };
+            // Execute sequentially
+            for (const t of targets) {
+                const output = await processTarget(t);
+                console.log(output);
             }
         }
         catch (error) {

package/build/cli/commands/refs.js

@@ -2,6 +2,7 @@ import { Command } from 'commander';
 import { SearchOperations } from '../../tools/operations/search/index.js';
 import { printDebug, exitWithError } from '../utils/output.js';
 import { resolveGraph } from '../utils/graph.js';
+import { readStdin } from '../utils/input.js';
 /**
  * Format results grouped by page (default output)
  */
@@ -72,7 +73,7 @@ function parseIdentifier(identifier) {
 export function createRefsCommand() {
     return new Command('refs')
         .description('Find all blocks that reference a page, tag, or block')
-        .argument('<identifier>', 'Page title, #tag, [[Page]], or ((block-uid))')
+        .argument('[identifier]', 'Page title, #tag, [[Page]], or ((block-uid)). Reads from stdin if "-" or omitted.')
         .option('-n, --limit <n>', 'Limit number of results', '50')
         .option('--json', 'Output as JSON array')
         .option('--raw', 'Output raw UID + content lines (no grouping)')
@@ -82,49 +83,66 @@ export function createRefsCommand() {
 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
 
+  # Stdin / Batch references
+  echo "Project A" | roam refs            # Pipe page title
+  cat uids.txt | roam refs --json         # Find refs for multiple UIDs
+
   # 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 = 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);
-            }
-            const searchOps = new SearchOperations(graph);
-            const result = await searchOps.searchBlockRefs({ block_uid, title });
-            if (options.debug) {
-                printDebug('Total matches', result.matches.length);
+            // Determine identifiers
+            let identifiers = [];
+            if (identifier && identifier !== '-') {
+                identifiers = [identifier];
             }
-            // Apply limit
-            const limitedMatches = result.matches.slice(0, limit);
-            // Format output
-            if (options.json) {
-                const jsonOutput = limitedMatches.map(m => ({
-                    uid: m.block_uid,
-                    content: m.content,
-                    page: m.page_title
-                }));
-                console.log(JSON.stringify(jsonOutput, null, 2));
+            else {
+                if (process.stdin.isTTY && identifier !== '-') {
+                    exitWithError('Identifier is required. Use: roam refs <title> or pipe identifiers via stdin');
+                }
+                const input = await readStdin();
+                if (input) {
+                    identifiers = input.split('\n').map(t => t.trim()).filter(Boolean);
+                }
             }
-            else if (options.raw) {
-                console.log(formatRaw(limitedMatches));
+            if (identifiers.length === 0) {
+                exitWithError('No identifiers provided');
             }
-            else {
-                console.log(formatGrouped(limitedMatches));
+            const searchOps = new SearchOperations(graph);
+            // Helper to process a single identifier
+            const processIdentifier = async (id) => {
+                const { block_uid, title } = parseIdentifier(id);
+                if (options.debug) {
+                    printDebug('Identifier', id);
+                    printDebug('Parsed', { block_uid, title });
+                }
+                const result = await searchOps.searchBlockRefs({ block_uid, title });
+                const limitedMatches = result.matches.slice(0, limit);
+                if (options.json) {
+                    return JSON.stringify(limitedMatches.map(m => ({
+                        uid: m.block_uid,
+                        content: m.content,
+                        page: m.page_title
+                    })));
+                }
+                else if (options.raw) {
+                    return formatRaw(limitedMatches);
+                }
+                else {
+                    return formatGrouped(limitedMatches);
+                }
+            };
+            // Execute
+            for (const id of identifiers) {
+                const output = await processIdentifier(id);
+                console.log(output);
+                if (identifiers.length > 1 && !options.json)
+                    console.log('\n---\n');
             }
         }
         catch (error) {

package/build/cli/commands/save.js

@@ -7,6 +7,7 @@ import { BatchOperations } from '../../tools/operations/batch.js';
 import { parseMarkdown, generateBlockUid, parseMarkdownHeadingLevel } from '../../markdown-utils.js';
 import { printDebug, exitWithError } from '../utils/output.js';
 import { resolveGraph } from '../utils/graph.js';
+import { readStdin } from '../utils/input.js';
 import { formatRoamDate } from '../../utils/helpers.js';
 import { q, createPage as roamCreatePage } from '@roam-research/roam-api-sdk';
 /**
@@ -26,16 +27,6 @@ function flattenNodes(nodes, baseLevel = 1) {
     }
     return result;
 }
-/**
- * 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');
-}
 /**
  * Check if a string looks like a Roam block UID (9 alphanumeric chars with _ or -)
  */
@@ -169,6 +160,11 @@ Examples:
   roam save notes.md --title "My Notes" --update  # Smart update (preserves UIDs)
   cat data.json | roam save --json                # Pipe JSON blocks
 
+  # Stdin operations
+  echo "Task from CLI" | roam save --todo         # Pipe to TODO
+  cat note.md | roam save --title "From Pipe"     # Pipe file content to new page
+  echo "Quick capture" | roam save -p "Inbox"     # Pipe to specific page
+
   # Combine options
   roam save -p "Work" --parent "## Today" "Done with task" -c "wins"
 
@@ -219,7 +215,7 @@ JSON format (--json):
             let content;
             let isFile = false;
             let sourceFilename;
-            if (input) {
+            if (input && input !== '-') {
                 // Check if input is a file path that exists
                 if (existsSync(input)) {
                     isFile = true;
@@ -237,8 +233,8 @@ JSON format (--json):
                 }
             }
             else {
-                // Read from stdin
-                if (process.stdin.isTTY) {
+                // Read from stdin (or if input is explicit '-')
+                if (process.stdin.isTTY && input !== '-') {
                     exitWithError('No input. Use: roam save "text", roam save <file>, or pipe content');
                 }
                 content = await readStdin();

package/build/cli/commands/search.js

@@ -2,6 +2,7 @@ import { Command } from 'commander';
 import { SearchOperations } from '../../tools/operations/search/index.js';
 import { formatSearchResults, printDebug, exitWithError } from '../utils/output.js';
 import { resolveGraph } from '../utils/graph.js';
+import { readStdin } from '../utils/input.js';
 /**
  * Normalize a tag by stripping #, [[, ]] wrappers
  */
@@ -20,7 +21,7 @@ function contentHasTag(content, tag) {
 export function createSearchCommand() {
     return new Command('search')
         .description('Search blocks by text, tags, Datalog queries, or within specific pages')
-        .argument('[terms...]', 'Search terms (multiple terms use AND logic)')
+        .argument('[terms...]', 'Search terms (multiple terms use AND logic). Reads from stdin if omitted.')
         .option('--tag <tag>', 'Filter by tag (repeatable, comma-separated). Default: AND logic', (val, prev) => {
         // Support both comma-separated and multiple flags
         const tags = val.split(',').map(t => t.trim()).filter(Boolean);
@@ -46,38 +47,17 @@ Examples:
   # Text search
   roam search "meeting notes"               # Find blocks containing text
   roam search api integration               # Multiple terms (AND logic)
-  roam search "bug fix" -i                  # Case-insensitive search
+
+  # Stdin search
+  echo "urgent project" | roam search       # Pipe terms
+  roam get today | roam search TODO         # Search within output
 
   # Tag search
   roam search --tag TODO                    # All blocks with #TODO
   roam search --tag "[[Project Alpha]]"     # Blocks with page reference
-  roam search --tag work --page "January 3rd, 2026"  # Tag on specific page
-
-  # Multiple tags
-  roam search --tag TODO --tag urgent       # Blocks with BOTH tags (AND)
-  roam search --tag "TODO,urgent,blocked"   # Comma-separated (AND)
-  roam search --tag TODO --tag urgent --any # Blocks with ANY tag (OR)
-
-  # Exclude tags
-  roam search --tag TODO --negtag done      # TODOs excluding #done
-  roam search --tag TODO --negtag "someday,maybe"  # Exclude multiple
-
-  # Combined filters
-  roam search urgent --tag TODO             # Text + tag filter
-  roam search "review" --page "Work"        # Search within page
-
-  # Output options
-  roam search "design" -n 50                # Limit to 50 results
-  roam search "api" --json                  # JSON output
 
   # Datalog queries (advanced)
-  roam search -q '[:find ?title :where [?e :node/title ?title]]'
-  roam search -q '[:find ?s :in $ ?term :where [?b :block/string ?s] [(clojure.string/includes? ?s ?term)]]' --inputs '["TODO"]'
-  roam search -q '[:find ?uid ?s :where [?b :block/uid ?uid] [?b :block/string ?s]]' --regex "meeting" --regex-flags "i"
-
-Datalog tips:
-  Common attributes: :node/title, :block/string, :block/uid, :block/page, :block/children
-  Predicates: clojure.string/includes?, clojure.string/starts-with?, <, >, =
+  roam search -q '[:find ?uid ?s :where [?b :block/uid ?uid] [?b :block/string ?s]]' --regex "meeting"
 `)
         .action(async (terms, options) => {
         try {
@@ -87,14 +67,21 @@ Datalog tips:
                 json: options.json,
                 debug: options.debug
             };
+            let searchTerms = terms;
+            // If no terms provided as args, try stdin
+            if (searchTerms.length === 0 && !process.stdin.isTTY && !options.query && (options.tag?.length === 0)) {
+                const input = await readStdin();
+                if (input) {
+                    searchTerms = input.trim().split(/\s+/);
+                }
+            }
             if (options.debug) {
-                printDebug('Search terms', terms);
+                printDebug('Search terms', searchTerms);
                 printDebug('Graph', options.graph || 'default');
                 printDebug('Options', options);
             }
             const searchOps = new SearchOperations(graph);
             // Datalog query mode (bypasses other search options)
-            // See for query construction - Roam_Research_Datalog_Cheatsheet.md
             if (options.query) {
                 // Parse inputs if provided
                 let inputs;
@@ -109,11 +96,6 @@ Datalog tips:
                         exitWithError('Invalid JSON in --inputs');
                     }
                 }
-                if (options.debug) {
-                    printDebug('Datalog query', options.query);
-                    printDebug('Inputs', inputs || 'none');
-                    printDebug('Regex filter', options.regex || 'none');
-                }
                 const result = await searchOps.executeDatomicQuery({
                     query: options.query,
                     inputs,
@@ -126,7 +108,6 @@ Datalog tips:
                 // Apply limit and format output
                 const limitedMatches = result.matches.slice(0, limit);
                 if (options.json) {
-                    // For JSON output, parse the content back to objects
                     const parsed = limitedMatches.map(m => {
                         try {
                             return JSON.parse(m.content);
@@ -138,7 +119,6 @@ Datalog tips:
                     console.log(JSON.stringify(parsed, null, 2));
                 }
                 else {
-                    // For text output, show raw results
                     if (limitedMatches.length === 0) {
                         console.log('No results found.');
                     }
@@ -153,34 +133,22 @@ Datalog tips:
             }
             // Determine search type based on options
             const tags = options.tag || [];
-            if (tags.length > 0 && terms.length === 0) {
+            if (tags.length > 0 && searchTerms.length === 0) {
                 // Tag-only search
                 const normalizedTags = tags.map(normalizeTag);
                 const useOrLogic = options.any || false;
-                if (options.debug) {
-                    printDebug('Tag search', {
-                        tags: normalizedTags,
-                        logic: useOrLogic ? 'OR' : 'AND',
-                        page: options.page
-                    });
-                }
-                // Search for first tag, then filter by additional tags
                 const result = await searchOps.searchForTag(normalizedTags[0], options.page);
                 let matches = result.matches;
-                // Apply multi-tag filter if more than one tag
                 if (normalizedTags.length > 1) {
                     matches = matches.filter(m => {
                         if (useOrLogic) {
-                            // OR: has at least one tag
                             return normalizedTags.some(tag => contentHasTag(m.content, tag));
                         }
                         else {
-                            // AND: has all tags
                             return normalizedTags.every(tag => contentHasTag(m.content, tag));
                         }
                     });
                 }
-                // Apply negtag filter (exclude blocks with any of these tags)
                 const negTags = options.negtag || [];
                 if (negTags.length > 0) {
                     const normalizedNegTags = negTags.map(normalizeTag);
@@ -189,24 +157,18 @@ Datalog tips:
                 const limitedMatches = matches.slice(0, limit);
                 console.log(formatSearchResults(limitedMatches, outputOptions));
             }
-            else if (terms.length > 0) {
-                // Text search (with optional tag filter)
-                const searchText = terms.join(' ');
-                if (options.debug) {
-                    printDebug('Text search', { text: searchText, page: options.page, tag: options.tag });
-                }
+            else if (searchTerms.length > 0) {
+                // Text search
+                const searchText = searchTerms.join(' ');
                 const result = await searchOps.searchByText({
                     text: searchText,
                     page_title_uid: options.page
                 });
-                // Apply client-side filters
                 let matches = result.matches;
-                // Case-insensitive filter if requested
                 if (options.caseInsensitive) {
                     const lowerSearchText = searchText.toLowerCase();
                     matches = matches.filter(m => m.content.toLowerCase().includes(lowerSearchText));
                 }
-                // Tag filter if provided
                 if (tags.length > 0) {
                     const normalizedTags = tags.map(normalizeTag);
                     const useOrLogic = options.any || false;
@@ -219,13 +181,11 @@ Datalog tips:
                         }
                     });
                 }
-                // Negtag filter (exclude blocks with any of these tags)
                 const negTags = options.negtag || [];
                 if (negTags.length > 0) {
                     const normalizedNegTags = negTags.map(normalizeTag);
                     matches = matches.filter(m => !normalizedNegTags.some(tag => contentHasTag(m.content, tag)));
                 }
-                // Apply limit
                 console.log(formatSearchResults(matches.slice(0, limit), outputOptions));
             }
             else {