roam-research-mcp 2.4.3 → 2.13.0

package/build/Roam_Markdown_Cheatsheet.md

@@ -69,6 +69,13 @@ const x = 1;
 ### Calculator
 `{{[[calc]]: 2 + 2}}`
 
+### Codeblock
+Roam uses "shell" not "bash". Other common languages okay, including "plain text".
+```shell
+echo "Hello world!"
+```
+
+
 ## Complex Structures
 
 ### Tables
@@ -250,6 +257,11 @@ ASK YOURSELF:
 | `#single-word` | Simple, unambiguous category |
 | Attribute `Type::` | Structured metadata for queries |
 
+### WHEN creating Endnotes/Footnotes:
+- Find/Create the block with heading "Footnotes::" and nest footnote item below. (Footnotes do not need to be on the same page as the block to which it references. Typically on the same page unless instructed otherwise.)
+- If not known, retrieve the block_uid reference for this footnote item.
+- In the block referencing the footnote, append the reference with footnote-item-block_id, example: "- <block_text> #ref ((block_uid))"
+
 ### Structural Tagging (Beyond Content)
 
 Tag by **patterns and mechanisms**, not just subjects:
@@ -295,6 +307,9 @@ Always include 2-3 relevant hashtags after quotes.
 ```
 
 ### Scheduled Reviews
+
+- Any block tagged with a date will show on that respective daily page.
+
 ```
 [[For review]]: [[Date in ordinal format]]
 ```
@@ -321,6 +336,7 @@ When a tag would awkwardly affect sentence capitalization:
 - **Use inconsistent capitalization** — Tags are lowercase unless proper nouns
 - **Create orphan tags** — Check if existing page/tag serves the purpose
 - **Bold Attributes** - ❌ `**Attribute**::`, ✅ `Attribute::` (Roam auto-formats)
+- **Separators** - `---` Don't use them.
 
 ### DO
 - **Think retrieval-first** — How will you search for this later?
@@ -345,7 +361,7 @@ CUSTOMIZE THIS SECTION with your specific conventions:
 
 **Books:**
 ```
-[[Book: Title by Author]]
+[[Book/<title> | <author>]]
 Type:: Book
 Author:: [[Author Name]]
 Status:: Reading | Completed | Abandoned
@@ -358,14 +374,18 @@ Rating:: X/5
 Type:: Person
 Context:: How I know them
 ```
-
+- When linking bibliographic references —>
+  Example: `McAdams, D.P. (2001) [The Psychology of Life Stories](https://journals.sagepub.com/doi/10.1037/1089-2680.5.2.100) — foundational paper`
+  - [McAdams, D.P.]([[Dan McAdams]]) - author's name in the graph
+  - If source URL, link to source: [The Psychology of Life Stories](https://journals.sagepub.com/doi/10.1037/1089-2680.5.2.100)
+  - If notes page exists or will exist in Roam: append ` | [Notes]([[Article/The Psychology of Life Stories]]), if not, just leave it without link.
+  
 **Projects:**
 ```
-[[Project: Name]]
+[[Project/<project anme>]]
 Status:: Active | Paused | Completed
 Start:: [[Date]]
 ```
-
 ---
 
 ## Integration Notes

package/build/cache/page-uid-cache.js

@@ -1,11 +1,16 @@
 /**
- * Simple in-memory cache for page title -> UID mappings.
+ * Simple in-memory cache for page title -> UID mappings and UID existence tracking.
  * Pages are stable entities that rarely get deleted, making them safe to cache.
  * This reduces redundant API queries when looking up the same page multiple times.
+ *
+ * The cache tracks two things:
+ * 1. Title -> UID mappings (for getPageUid lookups)
+ * 2. Known existing UIDs (for existence validation before batch operations)
  */
 class PageUidCache {
     constructor() {
         this.cache = new Map(); // title (lowercase) -> UID
+        this.knownUids = new Set(); // UIDs confirmed to exist
     }
     /**
      * Get a cached page UID by title.
@@ -17,11 +22,13 @@ class PageUidCache {
     }
     /**
      * Cache a page title -> UID mapping.
+     * Also marks the UID as known to exist.
      * @param title - Page title (will be stored lowercase)
      * @param uid - Page UID
      */
     set(title, uid) {
         this.cache.set(title.toLowerCase(), uid);
+        this.knownUids.add(uid);
     }
     /**
      * Check if a page title is cached.
@@ -30,6 +37,30 @@ class PageUidCache {
     has(title) {
         return this.cache.has(title.toLowerCase());
     }
+    /**
+     * Check if a UID is known to exist.
+     * @param uid - Page or block UID
+     */
+    hasUid(uid) {
+        return this.knownUids.has(uid);
+    }
+    /**
+     * Mark a UID as known to exist (without title mapping).
+     * Use this when you've verified a UID exists but don't know/need its title.
+     * @param uid - Page or block UID
+     */
+    addUid(uid) {
+        this.knownUids.add(uid);
+    }
+    /**
+     * Mark multiple UIDs as known to exist.
+     * @param uids - Array of page or block UIDs
+     */
+    addUids(uids) {
+        for (const uid of uids) {
+            this.knownUids.add(uid);
+        }
+    }
     /**
      * Called when a page is created - immediately add to cache.
      * @param title - Page title
@@ -43,13 +74,20 @@ class PageUidCache {
      */
     clear() {
         this.cache.clear();
+        this.knownUids.clear();
     }
     /**
-     * Get the current cache size.
+     * Get the current title cache size.
      */
     get size() {
         return this.cache.size;
     }
+    /**
+     * Get the current known UIDs cache size.
+     */
+    get uidCacheSize() {
+        return this.knownUids.size;
+    }
 }
 // Singleton instance - shared across all operations
 export const pageUidCache = new PageUidCache();

package/build/cli/batch/translator.js

@@ -296,7 +296,7 @@ function translateRemember(cmd, context) {
         const tags = params.categories.map(cat => `#[[${cat}]]`).join(' ');
         memoryText = `${params.text} ${tags}`;
     }
-    // Add MEMORIES_TAG if configured (we'll handle this in the CLI command)
+    // Add ROAM_MEMORIES_TAG if configured (we'll handle this in the CLI command)
     // For now, just create the block
     let parentUid;
     // If heading is specified, we'd need to look it up or create it

package/build/cli/commands/batch.js

@@ -160,6 +160,8 @@ Example:
     {"command": "outline", "params": {"parent": "{{overview}}", "items": ["Goal 1", "Goal 2"]}},
     {"command": "todo", "params": {"text": "Review project"}}
   ]
+
+Output (JSON): { success, pages_created, actions_executed, uid_map? }
 `)
         .action(async (file, options) => {
         try {

package/build/cli/commands/get.js

@@ -2,19 +2,24 @@ import { Command } from 'commander';
 import { PageOperations } from '../../tools/operations/pages.js';
 import { BlockRetrievalOperations } from '../../tools/operations/block-retrieval.js';
 import { SearchOperations } from '../../tools/operations/search/index.js';
-import { formatPageOutput, formatBlockOutput, formatTodoOutput, printDebug, exitWithError } from '../utils/output.js';
+import { formatPageOutput, formatBlockOutput, formatTodoOutput, formatGroupedOutput, flattenBlocks, blocksToMarkdown, 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';
+import { resolveRelativeDate, parseRoamUrl, isRoamUid } from '../../utils/helpers.js';
+import { SearchUtils } from '../../search/utils.js';
+import { sortResults, groupResults, getDefaultDirection } from '../utils/sort-group.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)));
+async function resolveBlockRefsInTree(graph, block, maxDepth) {
+    // Only resolve if string is valid
+    const resolvedString = typeof block.string === 'string'
+        ? await resolveRefs(graph, block.string, 0, maxDepth)
+        : block.string || '';
+    const resolvedChildren = await Promise.all((block.children || []).map(child => resolveBlockRefsInTree(graph, child, maxDepth)));
     return {
         ...block,
         string: resolvedString,
@@ -24,22 +29,186 @@ async function resolveBlockRefs(graph, block, maxDepth) {
 /**
  * Resolve refs in an array of blocks
  */
-async function resolveBlocksRefs(graph, blocks, maxDepth) {
-    return Promise.all(blocks.map(block => resolveBlockRefs(graph, block, maxDepth)));
+async function resolveBlocksRefsInTree(graph, blocks, maxDepth) {
+    return Promise.all(blocks.map(block => resolveBlockRefsInTree(graph, block, maxDepth)));
+}
+/**
+ * Normalize a tag by stripping #, [[, ]] wrappers
+ */
+function normalizeTag(tag) {
+    return tag.replace(/^#?\[?\[?/, '').replace(/\]?\]?$/, '');
+}
+/**
+ * Check if content contains a tag (handles #tag, [[tag]], #[[tag]] formats)
+ * Case-insensitive matching.
+ */
+function contentHasTag(content, tag) {
+    const normalized = normalizeTag(tag).toLowerCase();
+    const lowerContent = content.toLowerCase();
+    return (lowerContent.includes(`[[${normalized}]]`) ||
+        lowerContent.includes(`#${normalized}`) ||
+        lowerContent.includes(`#[[${normalized}]]`));
+}
+/**
+ * Create the 'page' subcommand for explicit page retrieval
+ */
+function createPageSubcommand() {
+    return new Command('page')
+        .description('Fetch a page by UID, URL, or title')
+        .argument('<identifier>', 'Page UID, Roam URL, or page title')
+        .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('-u, --uid', 'Return only the page UID')
+        .option('-g, --graph <name>', 'Target graph key (multi-graph mode)')
+        .option('--debug', 'Show query metadata')
+        .addHelpText('after', `
+Examples:
+  # By page title
+  roam get page "Project Notes"
+  roam get page "January 10th, 2026"
+
+  # By page UID
+  roam get page abc123def
+
+  # By Roam URL (copy from browser)
+  roam get page "https://roamresearch.com/#/app/my-graph/page/abc123def"
+
+  # Get just the page UID
+  roam get page "Project Notes" --uid
+`)
+        .action(async (identifier, options) => {
+        try {
+            const graph = resolveGraph(options, false);
+            const depth = parseInt(options.depth || '4', 10);
+            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,
+                debug: options.debug
+            };
+            if (options.debug) {
+                printDebug('Identifier', identifier);
+                printDebug('Graph', options.graph || 'default');
+            }
+            // Resolve identifier to page UID
+            let pageUid = null;
+            let pageTitle = null;
+            // 1. Check if it's a Roam URL
+            const urlParsed = parseRoamUrl(identifier);
+            if (urlParsed) {
+                pageUid = urlParsed.uid;
+                if (options.debug) {
+                    printDebug('Parsed URL', { uid: pageUid, graph: urlParsed.graph });
+                }
+            }
+            // 2. Check if it's a direct UID
+            else if (isRoamUid(identifier)) {
+                pageUid = identifier;
+                if (options.debug) {
+                    printDebug('Direct UID', pageUid);
+                }
+            }
+            // 3. Otherwise treat as page title
+            else {
+                pageTitle = resolveRelativeDate(identifier);
+                if (options.debug && pageTitle !== identifier) {
+                    printDebug('Resolved date', `${identifier} → ${pageTitle}`);
+                }
+            }
+            const pageOps = new PageOperations(graph);
+            // If --uid flag, just return the UID
+            if (options.uid) {
+                if (pageUid) {
+                    console.log(pageUid);
+                }
+                else if (pageTitle) {
+                    const uid = await pageOps.getPageUid(pageTitle);
+                    if (!uid) {
+                        exitWithError(`Page "${pageTitle}" not found`);
+                    }
+                    console.log(uid);
+                }
+                return;
+            }
+            // Fetch page content
+            let blocks;
+            let displayTitle;
+            if (pageUid) {
+                // Fetch by UID - first need to get page title for display
+                const result = await pageOps.fetchPageByUid(pageUid);
+                if (!result) {
+                    exitWithError(`Page with UID "${pageUid}" not found`);
+                }
+                blocks = result.blocks;
+                displayTitle = result.title;
+            }
+            else if (pageTitle) {
+                // Fetch by title
+                const result = await pageOps.fetchPageByTitle(pageTitle, 'raw');
+                if (typeof result === 'string') {
+                    try {
+                        blocks = JSON.parse(result);
+                    }
+                    catch {
+                        exitWithError(result);
+                        return;
+                    }
+                }
+                else {
+                    blocks = result;
+                }
+                displayTitle = pageTitle;
+            }
+            else {
+                exitWithError('Could not parse identifier');
+                return;
+            }
+            // Resolve block references if requested
+            if (refsDepth > 0) {
+                blocks = await resolveBlocksRefsInTree(graph, blocks, refsDepth);
+            }
+            console.log(formatPageOutput(displayTitle, blocks, outputOptions));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            exitWithError(message);
+        }
+    });
 }
 export function createGetCommand() {
-    return new Command('get')
+    const cmd = new Command('get')
         .description('Fetch pages, blocks, or TODO/DONE items with optional ref expansion')
         .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)')
         .option('-f, --flat', 'Flatten hierarchy to single-level list')
+        .option('-u, --uid', 'Return only the page UID (resolve title to UID)')
         .option('--todo', 'Fetch TODO items')
         .option('--done', 'Fetch DONE items')
-        .option('-p, --page <ref>', 'Filter TODOs/DONEs by page title or UID')
+        .option('-p, --page <ref>', 'Scope to page title or UID (for TODOs, tags, text)')
         .option('-i, --include <terms>', 'Include items matching these terms (comma-separated)')
         .option('-e, --exclude <terms>', 'Exclude items matching these terms (comma-separated)')
+        .option('--tag <tag>', 'Get blocks with tag (repeatable, comma-separated)', (val, prev) => {
+        const tags = val.split(',').map(t => t.trim()).filter(Boolean);
+        return prev ? [...prev, ...tags] : tags;
+    }, [])
+        .option('--text <text>', 'Get blocks containing text')
+        .option('--any', 'Use OR logic for multiple tags (default is AND)')
+        .option('--negtag <tag>', 'Exclude blocks with tag (repeatable, comma-separated)', (val, prev) => {
+        const tags = val.split(',').map(t => t.trim()).filter(Boolean);
+        return prev ? [...prev, ...tags] : tags;
+    }, [])
+        .option('-n, --limit <n>', 'Limit number of blocks fetched (default: 20 for tag/text)', '20')
+        .option('--showall', 'Show all results (no limit)')
+        .option('--sort <field>', 'Sort results by: created, modified, page')
+        .option('--asc', 'Sort ascending (default for page)')
+        .option('--desc', 'Sort descending (default for dates)')
+        .option('--group-by <field>', 'Group results by: page, tag')
         .option('-g, --graph <name>', 'Target graph key (multi-graph mode)')
         .option('--debug', 'Show query metadata')
         .addHelpText('after', `
@@ -49,6 +218,14 @@ Examples:
   roam get today                              # Today's daily page
   roam get yesterday                          # Yesterday's daily page
 
+  # Fetch page by UID or URL (see 'roam get page --help')
+  roam get page abc123def                     # Page by UID
+  roam get page "https://roamresearch.com/#/app/my-graph/page/abc123def"
+
+  # Resolve page title to UID
+  roam get "Project Notes" --uid              # Returns just the page UID
+  roam get today -u                           # Today's daily page UID
+
   # Fetch blocks
   roam get abc123def                          # Block by UID
   roam get "((abc123def))"                    # UID with wrapper
@@ -69,6 +246,42 @@ Examples:
   roam get --todo                             # All TODOs across graph
   roam get --done                             # All completed items
   roam get --todo -p "Work"                   # TODOs on "Work" page
+
+  # Tag-based retrieval (returns blocks with children)
+  roam get --tag TODO                         # Blocks tagged with #TODO
+  roam get --tag Project,Active              # Blocks with both tags (AND)
+  roam get --tag Project --tag Active --any   # Blocks with either tag (OR)
+  roam get --tag Task --negtag Done           # Tasks excluding Done
+  roam get --tag Meeting -p "Work"            # Meetings on Work page
+
+  # Text-based retrieval
+  roam get --text "urgent"                    # Blocks containing "urgent"
+  roam get --text "meeting" --tag Project     # Combine text + tag filter
+  roam get --text "TODO" -p today             # Text search on today's page
+
+  # Sorting
+  roam get --tag Convention --sort created    # Sort by creation date (newest first)
+  roam get --todo --sort modified --asc       # Sort by edit date (oldest first)
+  roam get --tag Project --sort page          # Sort alphabetically by page
+
+  # Grouping
+  roam get --tag Convention --group-by page   # Group by source page
+  roam get --tag Convention --group-by tag    # Group by subtags (Convention/*)
+
+  # Combined
+  roam get --tag Convention --group-by tag --sort modified
+
+Output format:
+  Markdown: Content with hierarchy (no UIDs). Use --json for UIDs.
+  JSON:     Full block structure including uid field.
+
+JSON output fields:
+  Page:      { title, children: [Block...] }
+  Block:     { uid, string, order, heading?, children: [Block...] }
+  TODO/DONE: [{ block_uid, content, page_title }]
+  Tag/Text:  [{ uid, string, order, heading?, children: [...] }]
+
+Note: For flat results with UIDs, use 'roam search' instead.
 `)
         .action(async (target, options) => {
         try {
@@ -86,18 +299,189 @@ Examples:
             if (options.debug) {
                 printDebug('Target', target || 'stdin');
                 printDebug('Graph', options.graph || 'default');
-                printDebug('Options', { depth, refs: refsDepth || 'off', ...outputOptions });
+                printDebug('Options', { depth, refs: refsDepth || 'off', uid: options.uid || false, ...outputOptions });
             }
+            // Handle --uid flag: return just the page UID
+            if (options.uid) {
+                if (!target || target === '-') {
+                    exitWithError('--uid requires a page title argument');
+                }
+                const resolvedTarget = resolveRelativeDate(target);
+                if (options.debug && resolvedTarget !== target) {
+                    printDebug('Resolved date', `${target} → ${resolvedTarget}`);
+                }
+                // Check if target is already a block UID
+                const uidMatch = resolvedTarget.match(BLOCK_UID_PATTERN);
+                if (uidMatch) {
+                    // Already a UID, just output it
+                    console.log(uidMatch[1]);
+                    return;
+                }
+                const pageOps = new PageOperations(graph);
+                const pageUid = await pageOps.getPageUid(resolvedTarget);
+                if (!pageUid) {
+                    exitWithError(`Page "${resolvedTarget}" not found`);
+                }
+                console.log(pageUid);
+                return;
+            }
+            // Parse sort/group options
+            const sortField = options.sort;
+            const groupByField = options.groupBy;
+            const sortDirection = sortField
+                ? (options.asc ? 'asc' : options.desc ? 'desc' : getDefaultDirection(sortField))
+                : undefined;
             // 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) {
                     printDebug('Status search', { status, page: options.page, include: options.include, exclude: options.exclude });
+                    if (sortField)
+                        printDebug('Sort', { field: sortField, direction: sortDirection });
+                    if (groupByField)
+                        printDebug('Group by', groupByField);
                 }
                 const searchOps = new SearchOperations(graph);
                 const result = await searchOps.searchByStatus(status, options.page, options.include, options.exclude);
-                console.log(formatTodoOutput(result.matches, status, outputOptions));
+                let matches = result.matches;
+                // Apply sorting
+                if (sortField && sortDirection) {
+                    matches = sortResults(matches, { field: sortField, direction: sortDirection });
+                }
+                // Apply grouping
+                if (groupByField) {
+                    // For TODO/DONE, only page grouping makes sense (no tags on search results)
+                    if (groupByField === 'tag') {
+                        exitWithError('--group-by tag is not supported for TODO/DONE search. Use --group-by page instead.');
+                    }
+                    const grouped = groupResults(matches, { by: groupByField });
+                    console.log(formatGroupedOutput(grouped, outputOptions));
+                }
+                else {
+                    console.log(formatTodoOutput(matches, status, outputOptions));
+                }
+                return;
+            }
+            // Handle --tag and/or --text flags (search-based retrieval with full children)
+            const tags = options.tag || [];
+            if (tags.length > 0 || options.text) {
+                const searchOps = new SearchOperations(graph);
+                const blockOps = new BlockRetrievalOperations(graph);
+                const limit = options.showall ? Infinity : parseInt(options.limit || '20', 10);
+                const useOrLogic = options.any || false;
+                // Resolve page scope
+                const pageScope = options.page ? resolveRelativeDate(options.page) : undefined;
+                if (options.debug) {
+                    printDebug('Tag/Text search', {
+                        tags,
+                        text: options.text,
+                        page: pageScope,
+                        any: useOrLogic,
+                        negtag: options.negtag,
+                        limit
+                    });
+                    if (sortField)
+                        printDebug('Sort', { field: sortField, direction: sortDirection });
+                    if (groupByField)
+                        printDebug('Group by', groupByField);
+                }
+                // Get initial matches
+                let matches = [];
+                if (options.text) {
+                    // Text search
+                    const result = await searchOps.searchByText({
+                        text: options.text,
+                        page_title_uid: pageScope
+                    });
+                    matches = result.matches;
+                }
+                else if (tags.length > 0) {
+                    // Tag search (use first tag as primary)
+                    const normalizedTags = tags.map(normalizeTag);
+                    const result = await searchOps.searchForTag(normalizedTags[0], pageScope);
+                    matches = result.matches;
+                }
+                // Apply additional tag filters
+                if (tags.length > 0 && matches.length > 0) {
+                    const normalizedTags = tags.map(normalizeTag);
+                    // For text search with tags, filter by ALL tags
+                    // For tag search with multiple tags, filter by remaining tags based on --any
+                    if (options.text || normalizedTags.length > 1) {
+                        matches = matches.filter(m => {
+                            if (useOrLogic) {
+                                return normalizedTags.some(tag => contentHasTag(m.content, tag));
+                            }
+                            else {
+                                return normalizedTags.every(tag => contentHasTag(m.content, tag));
+                            }
+                        });
+                    }
+                }
+                // Apply negative tag filter
+                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 sorting before limit (so we get the top N sorted items)
+                if (sortField && sortDirection) {
+                    matches = sortResults(matches, { field: sortField, direction: sortDirection });
+                }
+                // Apply limit
+                const limitedMatches = matches.slice(0, limit);
+                if (limitedMatches.length === 0) {
+                    console.log(options.json ? '[]' : 'No blocks found matching criteria.');
+                    return;
+                }
+                // For tag grouping, fetch all tags for matched blocks
+                if (groupByField === 'tag') {
+                    const blockUids = limitedMatches.map(m => m.block_uid);
+                    const tagMap = await SearchUtils.fetchBlockTags(graph, blockUids);
+                    // Attach tags to matches
+                    for (const match of limitedMatches) {
+                        match.tags = tagMap.get(match.block_uid) || [];
+                    }
+                    // Group and output
+                    const primaryTag = tags.length > 0 ? normalizeTag(tags[0]) : '';
+                    const grouped = groupResults(limitedMatches, { by: 'tag', searchTag: primaryTag });
+                    console.log(formatGroupedOutput(grouped, outputOptions));
+                    return;
+                }
+                // For page grouping, output grouped matches
+                if (groupByField === 'page') {
+                    const grouped = groupResults(limitedMatches, { by: 'page' });
+                    console.log(formatGroupedOutput(grouped, outputOptions));
+                    return;
+                }
+                // Standard output: fetch full blocks with children
+                const blocks = [];
+                for (const match of limitedMatches) {
+                    let block = await blockOps.fetchBlockWithChildren(match.block_uid, depth);
+                    if (block) {
+                        // Resolve refs if requested (default: enabled for tag/text search)
+                        const effectiveRefsDepth = refsDepth > 0 ? refsDepth : 1;
+                        block = await resolveBlockRefsInTree(graph, block, effectiveRefsDepth);
+                        blocks.push(block);
+                    }
+                }
+                // Output
+                if (options.json) {
+                    const data = options.flat
+                        ? blocks.flatMap(b => flattenBlocks([b]))
+                        : blocks;
+                    console.log(JSON.stringify(data, null, 2));
+                }
+                else {
+                    const displayBlocks = options.flat
+                        ? blocks.flatMap(b => flattenBlocks([b]))
+                        : blocks;
+                    // Show count header
+                    const countMsg = matches.length > limit
+                        ? `Found ${matches.length} blocks (showing first ${limit}):\n\n`
+                        : `Found ${blocks.length} block(s):\n\n`;
+                    console.log(countMsg + blocksToMarkdown(displayBlocks));
+                }
                 return;
             }
             // Determine targets
@@ -109,7 +493,7 @@ Examples:
                 // 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');
+                    exitWithError('Target is required. Use: roam get <page-title>, roam get --todo, roam get --tag <tag>, roam get --text <text>, or pipe targets via stdin');
                 }
                 const input = await readStdin();
                 if (input) {
@@ -144,7 +528,7 @@ Examples:
                     }
                     // Resolve block references if requested
                     if (refsDepth > 0) {
-                        block = await resolveBlockRefs(graph, block, refsDepth);
+                        block = await resolveBlockRefsInTree(graph, block, refsDepth);
                     }
                     return formatBlockOutput(block, outputOptions);
                 }
@@ -173,7 +557,7 @@ Examples:
                     }
                     // Resolve block references if requested
                     if (refsDepth > 0) {
-                        blocks = await resolveBlocksRefs(graph, blocks, refsDepth);
+                        blocks = await resolveBlocksRefsInTree(graph, blocks, refsDepth);
                     }
                     return formatPageOutput(resolvedTarget, blocks, outputOptions);
                 }
@@ -189,4 +573,7 @@ Examples:
             exitWithError(message);
         }
     });
+    // Add subcommands
+    cmd.addCommand(createPageSubcommand());
+    return cmd;
 }