### Install Roam Research CLI

Source: https://context7.com/2b3pro/roam-research-mcp/llms.txt

Install the `roam` CLI globally to make its commands available in your shell. Verify the installed version.

```bash
npm install -g roam-research-mcp
roam --version   # 2.18.2
```

--------------------------------

### Multi-Graph Save Example

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/README.md

Example of saving content to a specific graph ('work') in multi-graph mode, requiring a write key for confirmation.

```bash
# Example: Save to work graph
roam save -g work --write-key confirm "Meeting notes"
```

--------------------------------

### Install Roam CLI

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/README.md

Installs the Roam CLI globally, making the `roam` command available in your terminal.

```bash
npm link  # Makes `roam` command globally available
```

--------------------------------

### Roam Import JSON Example

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/Roam Import JSON Schema.md

This example demonstrates the structure of a JSON array representing pages and their children for import into Roam. It includes page titles, creation times, and nested blocks with their own children.

```javascript
[{:title        "December 10th 2018"
  :create-email "josh@roamresearch.com"
  :create-time  1576025237000
  :children     [{:string   "[[Meeting]] with [[Tim]]"
                  :children [{:string "Meeting went well"}]}
                 {:string "[[Call]] with [[John]]"}]}
 {:title    "December 11th 2018"}]
```

--------------------------------

### Get All TODOs

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/ROAM-CLI-REFERENCE_LLM.md

List all TODO items across all your Roam graphs with the `roam get --todo` command.

```bash
roam get --todo
```

--------------------------------

### List Sub-pages

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/ROAM-CLI-REFERENCE_LLM.md

Enumerate all sub-pages that start with a given prefix using `roam get subpages "Prefix"`.

```bash
roam get subpages "Prefix"
```

--------------------------------

### Batch Operation Example

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/README.md

A JSON structure demonstrating various batch operations including creating a page, adding an outline, and creating a todo item.

```json
[
  {"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"}}
]
```

--------------------------------

### Install Roam Research MCP CLI

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/README.md

Install the 'roam' command-line tool globally using npm. This makes the 'roam' command available in your terminal.

```bash
npm install -g roam-research-mcp
# The 'roam' command is now available globally
```

--------------------------------

### Run Roam Research MCP Server

Source: https://context7.com/2b3pro/roam-research-mcp/llms.txt

Start the MCP server in different modes: stdio for local LLM integration, HTTP Stream for remote clients, or via Docker.

```bash
# Stdio mode (default, for local LLM integration)
npx roam-research-mcp

# HTTP Stream mode (for remote clients)
HTTP_STREAM_PORT=8088 npx roam-research-mcp

# Docker
docker run -p 8088:8088 --env-file .env roam-research-mcp
```

--------------------------------

### Get Subcommands

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/ROAM-CLI-REFERENCE_LLM.md

Specific subcommands for `roam get`, detailing how to fetch pages, full page views with references, and lists of sub-pages within a namespace.

```bash
- `roam get page <identifier>` - fetches page by UID, Roam URL, or title explicitly
- `roam get full <title>` - full page view: content + all linked references with breadcrumb context. Options: `-d N` depth (default 4), `-n N` max refs (default 200)
- `roam get subpages <prefix>` - list sub-pages under namespace prefix (e.g. "Project/"). Options: `--filter-tag <tag>`, `--content`
```

--------------------------------

### Roam Query Syntax Examples

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/Roam_Markdown_Cheatsheet.md

Construct queries using 'and', 'or', 'not', and 'between' operators to filter blocks. Ensure correct page references within queries.

```json
{{[[query]]: {and: [[tag1]] [[tag2]]}}}
{{[[query]]: {or: [[A]] [[B]]}}}
{{[[query]]: {not: [[exclude]]}}}
{{[[query]]: {between: [[January 1st, 2025]] [[January 31st, 2025]]}}}
```

--------------------------------

### Common Patterns

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/ROAM-CLI-REFERENCE_LLM.md

Illustrates common tasks and their corresponding ROAM CLI commands, covering getting page content, UIDs, TODOs, blocks with tags, saving notes, creating new pages, and finding references.

```APIDOC
## Common Patterns

| Task | Command |
|------|---------|
| Today's page content | `roam get today` |
| Page UID only | `roam get "Title" --uid` |
| All TODOs | `roam get --todo` |
| TODOs on page | `roam get --todo -p "Page"` |
| Blocks with tag | `roam get --tag "Tag"` |
| Multiple tags (AND) | `roam get --tag Tag1 --tag Tag2` |
| Multiple tags (OR) | `roam get --tag Tag1 --tag Tag2 --any` |
| Block + ancestors | `roam get <uid> -a` |
| Ancestors only | `roam get <uid> -a -d 0` |
| Full view + backlinks | `roam get full "Page"` |
| List sub-pages | `roam get subpages "Prefix"` |
| Quick note | `roam save "Note"` |
| Note to page | `roam save "Note" -p "Page"` |
| Under heading | `roam save --parent "## Section" "Note"` |
| TODO item | `roam save --todo "Task"` |
| New page | `roam save file.md --title "Page"` |
| Update page | `roam save file.md --title "Page" --update` |
| Find references | `roam refs "Page"` |
| Mark done | `roam update <uid> -D` |
```

--------------------------------

### Roam Batch Action UID Placeholder Example

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/Roam_Markdown_Cheatsheet.md

Demonstrates the use of `{{uid:name}}` placeholders for parent references in batch actions. The server response includes a `uid_map` to resolve these placeholders.

```json
[
  {"action": "create-block", "uid": "{{uid:parent}}", "string": "Parent", "location": {"parent-uid": "pageUid", "order": 0}},
  {"action": "create-block", "string": "Child", "location": {"parent-uid": "{{uid:parent}}", "order": 0}}
]
```

--------------------------------

### Get Command Options

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/ROAM-CLI-REFERENCE_LLM.md

Common options for the `roam get` command, including JSON output, depth control, ancestor retrieval, reference expansion, sorting, and grouping.

```bash
Options: -j json, -d N depth (0=no children), -a ancestors (chain to page root), -r [N] expand refs, -f flat, --sort created|modified|page, --group-by page|tag
```

--------------------------------

### Roam API Tool Selection Guide

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/Roam_Markdown_Cheatsheet.md

This list categorizes available Roam API tools for different operations like creation, searching, and revision. Choose the tool that best fits your specific task for optimal efficiency.

```text
CREATING:
├─ New page + structure → roam_create_page
├─ Add to existing page/block:
│   ├─ Simple outline → roam_create_outline
│   └─ Complex markdown → roam_import_markdown
├─ Revise entire page → roam_update_page_markdown
├─ Fine-grained CRUD → roam_process_batch_actions
├─ Table → roam_create_table
├─ Memory → roam_remember
└─ Todos → roam_add_todo

SEARCHING:
├─ By tag → roam_search_for_tag
├─ By text → roam_search_by_text
├─ By date → roam_search_by_date
├─ By status → roam_search_by_status
├─ Block refs → roam_search_block_refs
├─ Modified today → roam_find_pages_modified_today
├─ Page content → roam_fetch_page_by_title
├─ Block (children/ancestors) → roam_fetch_block
├─ Memories → roam_recall
└─ Complex → roam_datomic_query
```

--------------------------------

### Datalog Query: List Pages in Namespace

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/Roam_Research_Datalog_Cheatsheet.md

Retrieves titles, UIDs, and last edit dates for pages whose titles start with a specified namespace prefix.

```clojure
[:find ?title:name ?title:uid ?time:date
 :where
 [?page :node/title ?title:name]
 [?page :block/uid ?title:uid]
 [?page :edit/time ?time:date]
 [(clojure.string/starts-with? ?title:name "roam/")]]
```

--------------------------------

### Get Full Page View with Backlinks

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/ROAM-CLI-REFERENCE_LLM.md

Retrieve the complete content of a page, including its backlinks, using `roam get full "Page"`.

```bash
roam get full "Page"
```

--------------------------------

### Get Block and its Ancestors

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/ROAM-CLI-REFERENCE_LLM.md

Retrieve a specific block along with all its parent blocks (ancestors) using `roam get <uid> -a`.

```bash
roam get <uid> -a
```

--------------------------------

### Get Roam-Flavored Markdown Cheatsheet

Source: https://context7.com/2b3pro/roam-research-mcp/llms.txt

Retrieve the complete Roam-flavored markdown syntax reference using `roam_markdown_cheatsheet`. Load this before creating or updating content to prevent syntax errors.

```json
{
  "tool": "roam_markdown_cheatsheet",
  "arguments": {}
}
```

--------------------------------

### Get Page by Title or UID

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/ROAM-CLI-REFERENCE_LLM.md

Fetch pages by their title, or blocks by their unique identifier (UID). Supports various lookup methods including URL and explicit page identification.

```bash
roam get <title|today|yesterday|tomorrow>       # page by title
roam get <9-char-uid>                           # block by UID
roam get page <uid|url|title>                   # explicit page (URL/UID/title)
roam get full <title>                           # full view: content + linked refs
roam get subpages <prefix>                      # list namespace sub-pages
roam get --uid <title>                          # resolve title→UID only
roam get --todo [-p <page>] [-i terms] [-e terms]
roam get --done [-p <page>]
roam get --tag <tag> [--negtag <tag>] [-p <page>] [--any] [-n limit]
roam get --text <text> [-p <page>]
```

--------------------------------

### Run MCP Server in HTTP Stream Mode

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/README.md

Start the MCP server with HTTP streaming enabled on a specified port, suitable for remote access or web clients.

```bash
HTTP_STREAM_PORT=8088 npx roam-research-mcp
```

--------------------------------

### Get Subpages with roam_get_subpages

Source: https://context7.com/2b3pro/roam-research-mcp/llms.txt

Lists namespace sub-pages (e.g., 'Project/...') under a given prefix. Optional filtering by tag and content inclusion.

```json
{
  "tool": "roam_get_subpages",
  "arguments": {
    "prefix": "Project",
    "filter_tag": "active",
    "include_content": false
  }
}
```

--------------------------------

### Roam Fetch Block Response

Source: https://context7.com/2b3pro/roam-research-mcp/llms.txt

Example response for fetching a Roam block, including its string content, order, children, and ancestors.

```jsonc
// Response
{
  "uid": "abc123def",
  "string": "Meeting notes from kick-off",
  "order": 2,
  "children": [
    {"uid": "chld01xyz", "string": "Action item 1", "order": 0, "children": []}
  ],
  "ancestors": [
    {"uid": "prnt01xyz", "string": "## Sprint 42", "depth": 1},
    {"uid": "page01xyz", "title": "Work Log", "depth": 0}
  ]
}
```

--------------------------------

### Roam Process Batch Actions Response

Source: https://context7.com/2b3pro/roam-research-mcp/llms.txt

Example response for processing batch actions, indicating success, validation status, number of actions attempted, and a map of generated UIDs.

```jsonc
// Response
{
  "success": true,
  "validation_passed": true,
  "actions_attempted": 5,
  "uid_map": {"section": "Xk7mN2pQ9"}
}
```

--------------------------------

### Roam Update Page Markdown Response

Source: https://context7.com/2b3pro/roam-research-mcp/llms.txt

Example response after updating a Roam page with markdown, showing success status, operation statistics, and preserved UIDs.

```jsonc
// Response
{
  "success": true,
  "stats": {"created": 1, "updated": 1, "moved": 0, "deleted": 0, "preserved": 4},
  "preservedUids": ["blk001xyz", "blk002xyz", "blk003xyz", "blk004xyz"],
  "summary": "1 created, 1 updated, 4 preserved"
}
```

--------------------------------

### Fetch Roam Pages and Blocks using `roam get`

Source: https://context7.com/2b3pro/roam-research-mcp/llms.txt

Retrieve pages by title (with date normalization), blocks by UID, or full graph views. Supports various options for filtering, sorting, and output format.

```bash
# Page by title
roam get "Project Alpha"

# Daily pages — all date formats auto-normalize
roam get today
roam get 2026-03-21          # → "March 21st, 2026"
roam get "03/21/2026"        # US format
roam get "March 21"          # Named, assumes current year

# Block by UID (raw or with (( )) wrapper)
roam get abc123def
roam get "((abc123def))"

# Block with full ancestor chain to page root
roam get abc123def -a
roam get abc123def -a -d 0   # Ancestors only, no children

# Explicit page by UID or Roam URL
roam get page abc123def
roam get page "https://roamresearch.com/#/app/my-graph/page/abc123def"

# Full view: page content + all linked references with breadcrumb context
roam get full "Project Alpha"
roam get full "Project Alpha" -d 2 -n 100   # depth=2, max 100 refs

# Namespace sub-pages
roam get subpages "Convention"
roam get subpages "Project" --filter-tag active --content

# Filter blocks by tag (AND by default, --any for OR)
roam get --tag "Project" --tag "Active" --sort created --group-by tag
roam get --tag "Project" --tag "Active" --any -n 50

# TODOs and DONEs
roam get --todo
roam get --todo -p "Work" -i "meeting,review" -e "archived"
roam get --done

# JSON output
roam get "Project Alpha" -j
roam get --todo -j

# Multi-graph
roam get "Page Title" -g work
```

--------------------------------

### Get Command Output in JSON Format

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/ROAM-CLI-REFERENCE_LLM.md

Utilize the `-j` or `--json` flag with various `roam` commands to receive output in a structured JSON format, suitable for programmatic use.

```bash
roam get page/block -j
```

```bash
roam get --tag/--text -j
```

```bash
roam get --todo/--done -j
```

```bash
roam search --json
```

```bash
roam refs --json
```

```bash
roam batch
```

--------------------------------

### Fetch Page by Title

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/README.md

Retrieves content for a specific page using its title.

```bash
roam get "Project Notes"                    # Page by title
```

--------------------------------

### Get Today's Page Content

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/ROAM-CLI-REFERENCE_LLM.md

Retrieve the content of the current day's page using the `roam get today` command.

```bash
roam get today
```

--------------------------------

### Run MCP Server using Docker

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/README.md

Deploy the MCP server using Docker, mapping the HTTP stream port and loading environment variables from a .env file.

```bash
docker run -p 8088:8088 --env-file .env roam-research-mcp
```

--------------------------------

### Get Ancestors Only

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/ROAM-CLI-REFERENCE_LLM.md

Fetch only the ancestor blocks of a given block UID, excluding the block itself, by using `roam get <uid> -a -d 0`.

```bash
roam get <uid> -a -d 0
```

--------------------------------

### Roam Output Convention: Open Question

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/Roam_Markdown_Cheatsheet.md

Format for posing open questions, using a TODO marker and a tag for tracking.

```text
Open question: {{[[TODO]]}} Research: <question> #[[open questions]]
```

--------------------------------

### Get Page UID

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/ROAM-CLI-REFERENCE_LLM.md

Fetch the unique identifier (UID) for a specific page by its title using `roam get "Page Title" --uid`.

```bash
roam get "Title" --uid
```

--------------------------------

### Get TODOs on a Specific Page

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/ROAM-CLI-REFERENCE_LLM.md

Filter and retrieve TODO items located on a particular page using `roam get --todo -p "Page"`.

```bash
roam get --todo -p "Page"
```

--------------------------------

### Run MCP Server in Stdio Mode

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/README.md

Execute the MCP server using npx for local integration with tools like Claude Desktop or IDE extensions. Stdio mode does not utilize network ports.

```bash
npx roam-research-mcp
```

--------------------------------

### Create a TODO Item on Daily Page

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/README.md

Use 'roam save --todo' to create a TODO item on the current day's Roam Research daily page. Content can be piped from stdin.

```bash
# Create a TODO item on today's daily page
echo "Buy milk" | roam save --todo
```

--------------------------------

### Get Blocks with a Specific Tag

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/ROAM-CLI-REFERENCE_LLM.md

Find all blocks containing a specified tag using `roam get --tag "Tag"`. Note that this command returns blocks with children by default.

```bash
roam get --tag "Tag"
```

--------------------------------

### `roam get` - Fetch

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/ROAM-CLI-REFERENCE_LLM.md

Fetches pages, blocks, or other data from Roam based on various identifiers and filters.

```APIDOC
## `roam get` - Fetch Data

### Description
Retrieves data from Roam, including pages by title or UID, blocks, and related information.

### Usage
- `roam get <title|today|yesterday|tomorrow>`: Get a page by its title or a daily note.
- `roam get <9-char-uid>`: Get a block by its UID.
- `roam get page <uid|url|title>`: Explicitly fetch a page using its UID, URL, or title.
- `roam get full <title>`: Fetch the full content of a page, including linked references.
- `roam get subpages <prefix>`: List sub-pages under a given namespace prefix.
- `roam get --uid <title>`: Resolve a page title to its UID.
- `roam get --todo [-p <page>] [-i terms] [-e terms]`: Get TODO items, optionally filtered by page or terms.
- `roam get --done [-p <page>]`: Get DONE items, optionally filtered by page.
- `roam get --tag <tag> [--negtag <tag>] [-p <page>] [--any] [-n limit]`: Get items associated with a specific tag.
- `roam get --text <text> [-p <page>]`: Get items containing specific text.

### Options
- `-j` or `--json`: Output in JSON format.
- `-d N` or `--depth N`: Set the depth for fetching children (0 means no children).
- `-a` or `--ancestors`: Include ancestors in the output chain.
- `-r [N]` or `--expand-refs [N]`: Expand references up to a certain level.
- `-f` or `--flat`: Flatten the output structure.
- `--sort created|modified|page`: Sort the results by creation date, modification date, or page title.
- `--group-by page|tag`: Group the results by page or tag.

### Subcommands
- `roam get page <identifier>`: Fetches a page by UID, Roam URL, or title.
- `roam get full <title>`: Fetches the full page view including content and linked references. Options: `-d N` (default 4), `-n N` (default 200).
- `roam get subpages <prefix>`: Lists sub-pages under a namespace. Options: `--filter-tag <tag>`, `--content`.
```

--------------------------------

### Compute and Apply Block Tree Differences

Source: https://context7.com/2b3pro/roam-research-mcp/llms.txt

This snippet demonstrates the full workflow of using the diff module: fetching existing page data, parsing it, converting new markdown, computing the difference, generating batch actions, and optionally applying them if the diff is not empty. Ensure necessary imports are present.

```typescript
import {
  parseExistingBlocks,
  markdownToBlocks,
  diffBlockTrees,
  generateBatchActions,
  getDiffStats,
  isDiffEmpty,
  summarizeActions
} from 'roam-research-mcp/diff';
import { q } from '@roam-research/roam-api-sdk';

// 1. Fetch existing page data via Datalog pull
const pageData = await q(graph,
  `[:find (pull ?page [{:block/children ...} :block/uid :block/string :block/order :block/heading]) .
   :where [?page :block/uid "${pageUid}"]]`,
  []
);

// 2. Parse existing blocks into the diff format
const existingBlocks = parseExistingBlocks(pageData);

// 3. Convert new markdown to block structure
const newBlocks = markdownToBlocks(updatedMarkdown, pageUid);

// 4. Compute diff (three-phase matching: exact → normalized → position-based)
const diff = diffBlockTrees(existingBlocks, newBlocks, pageUid);

// 5. Generate minimal ordered batch actions
const actions = generateBatchActions(diff);
// actions → [{action: 'create-block'|'update-block'|'move-block'|'delete-block', ...}]

// 6. Inspect stats
const stats = getDiffStats(diff);
// stats → { created: 1, updated: 2, moved: 0, deleted: 1, preserved: 8 }

if (!isDiffEmpty(diff)) {
  console.log(summarizeActions(actions));
  // e.g. "1 created, 2 updated, 1 deleted, 8 preserved"
  await batchActions(graph, { actions });
}
```

--------------------------------

### Configure Multi-Graph Mode Environment Variables

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/README.md

Define multiple Roam graphs and their configurations using this JSON string for the ROAM_GRAPHS environment variable. Specify the default graph and a system-wide write key for protected graphs.

```bash
ROAM_GRAPHS='{
  "personal": {"token": "token-1", "graph": "personal-db", "memoriesTag": "#[[Personal Memories]]"},
  "work": {"token": "token-2", "graph": "work-db", "protected": true, "memoriesTag": "#[[Work Memories]]"},
  "research": {"token": "token-3", "graph": "research-db"}
}'
ROAM_DEFAULT_GRAPH=personal
ROAM_SYSTEM_WRITE_KEY=your-secret-key
```

--------------------------------

### Fetch Roam Page by Title

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/README.md

Retrieve the content of a Roam Research page by its exact title using the 'roam get' command.

```bash
# Fetch a page by title
roam get "Roam Research"
```

--------------------------------

### Configure Single Graph Mode Environment Variables

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/README.md

Set these environment variables for a single Roam graph configuration. Use a .env file for local development.

```bash
ROAM_API_TOKEN=your-api-token
ROAM_GRAPH_NAME=your-graph-name
```

--------------------------------

### Bulk Operations with Batch

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/ROAM-CLI-REFERENCE_LLM.md

Perform bulk operations on Roam data using a JSON file or standard input. Includes options for dry runs and simulations.

```bash
roam batch commands.json                        # from file
echo '<json>' | roam batch                      # from stdin
roam batch --dry-run commands.json              # preview (resolves pages)
roam batch --simulate commands.json             # validate offline
```

--------------------------------

### Get Blocks with Multiple Tags (AND)

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/ROAM-CLI-REFERENCE_LLM.md

Retrieve blocks that contain all specified tags using multiple `--tag` flags. This performs an AND operation.

```bash
roam get --tag Tag1 --tag Tag2
```

--------------------------------

### Fetch Daily Notes

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/README.md

Fetches content for today's, yesterday's, or tomorrow's daily notes page.

```bash
roam get today                              # Today's daily page
```

```bash
roam get yesterday                          # Yesterday's daily page
```

```bash
roam get tomorrow                           # Tomorrow's daily page
```

--------------------------------

### Get Blocks with Multiple Tags (OR)

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/ROAM-CLI-REFERENCE_LLM.md

Find blocks containing any of the specified tags by adding the `--any` flag to multiple `--tag` flags. This performs an OR operation.

```bash
roam get --tag Tag1 --tag Tag2 --any
```

--------------------------------

### Roam Page Structure Format Response

Source: https://context7.com/2b3pro/roam-research-mcp/llms.txt

Example response when fetching a Roam page in 'structure' format. Other formats include 'raw' (full nested JSON) and 'markdown'.

```jsonc
// Response (structure format)
{
  "page_uid": "abc123def",
  "title": "Project Alpha",
  "block_count": 12,
  "blocks": [
    {"uid": "blk001xyz", "order": 0, "text": "## Overview", "depth": 0, "parent_uid": "abc123def", "heading": 2},
    {"uid": "blk002xyz", "order": 0, "text": "This project aims to...", "depth": 1, "parent_uid": "blk001xyz"}
  ]
}

// format: "raw"  → full nested JSON with UIDs and children arrays
// format: "markdown" → readable markdown string with # headings and - bullets
```

--------------------------------

### Fetch via Stdin

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/README.md

Reads targets (page titles or block UIDs) from standard input for batch retrieval.

```bash
echo "Project A" | roam get                 # Pipe page title
```

```bash
echo "abc123def" | roam get                 # Pipe block UID
```

```bash
cat uids.txt | roam get --json              # Fetch multiple blocks (NDJSON output)
```

--------------------------------

### Output as JSON

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/README.md

Formats the fetched data as JSON instead of markdown.

```bash
roam get "Page" -j                          # JSON output
```

--------------------------------

### Combined Retrieval Options with Roam CLI

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/README.md

Combine grouping and sorting options for more refined retrieval of blocks.

```bash
roam get --tag Convention --group-by tag --sort modified
```

--------------------------------

### Multi-Graph Mode

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/README.md

Information on how to use the Roam CLI with multiple graphs, including targeting specific graphs and confirming write access.

```APIDOC
## Multi-Graph Mode

All commands support `-g, --graph <name>` to target a specific graph when multiple graphs are configured.

For write operations on non-default graphs, use `--write-key <key>` to confirm write access.

```bash
# Example: Save to work graph
roam save -g work --write-key confirm "Meeting notes"
```

See the main project documentation for environment variable configuration.
```

--------------------------------

### Save a TODO Item

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/ROAM-CLI-REFERENCE_LLM.md

Create a new TODO item using `roam save --todo "Task"`.

```bash
roam save --todo "Task"
```

--------------------------------

### Quickly Save a Note

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/ROAM-CLI-REFERENCE_LLM.md

Add a short note to your Roam graph using the `roam save "Note"` command.

```bash
roam save "Note"
```

--------------------------------

### Search by Date with roam_search_by_date

Source: https://context7.com/2b3pro/roam-research-mcp/llms.txt

Searches for blocks or pages by creation or modification date. Specify start and end dates, type ('created' or 'modified'), scope ('blocks' or 'pages'), and whether to include content.

```json
{
  "tool": "roam_search_by_date",
  "arguments": {
    "start_date": "2026-03-01",
    "end_date": "2026-03-21",
    "type": "modified",
    "scope": "pages",
    "include_content": true
  }
}
```

--------------------------------

### Write to Protected Graphs

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/ROAM-CLI-REFERENCE_LLM.md

Use the `--write-key` option for operations on protected graphs like 'system'. Ensure the ROAM_SYSTEM_WRITE_KEY environment variable is set.

```bash
# Protected graphs (like "system") require write-key
roam save -g system --write-key "$ROAM_SYSTEM_WRITE_KEY" "content"
roam update -g system --write-key "$ROAM_SYSTEM_WRITE_KEY" <uid> "content"
roam batch -g system --write-key "$ROAM_SYSTEM_WRITE_KEY" commands.json
```

--------------------------------

### Configure Claude Desktop/Cline for Multi-Graph MCP Server

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/README.md

Configure Claude to connect to multiple Roam graphs using the MCP server. Ensure the ROAM_GRAPHS JSON string is properly escaped.

```json
{
  "mcpServers": {
    "roam-research": {
      "command": "npx",
      "args": ["-y", "roam-research-mcp"],
      "env": {
        "ROAM_GRAPHS": "{\"personal\":{\"token\":\"token-1\",\"graph\":\"personal-db\",\"memoriesTag\":\"#[[Memories]]\"},\"work\":{\"token\":\"token-2\",\"graph\":\"work-db\",\"protected\":true}}",
        "ROAM_DEFAULT_GRAPH": "personal",
        "ROAM_SYSTEM_WRITE_KEY": "your-secret-key"
      }
    }
  }
}
```

--------------------------------

### Configure Roam Research MCP Environment Variables

Source: https://context7.com/2b3pro/roam-research-mcp/llms.txt

Set environment variables for single-graph or multi-graph configurations. Multi-graph mode allows targeting several graphs with optional write protection.

```bash
# Single-graph mode
export ROAM_API_TOKEN=your-api-token
export ROAM_GRAPH_NAME=your-graph-name

# Multi-graph mode
export ROAM_GRAPHS='{
  "personal": {"token": "token-1", "graph": "personal-db", "memoriesTag": "#[[Memories]]"},
  "work":     {"token": "token-2", "graph": "work-db", "protected": true},
  "research": {"token": "token-3", "graph": "research-db"}
}'
export ROAM_DEFAULT_GRAPH=personal
export ROAM_SYSTEM_WRITE_KEY=your-secret-write-key

# Optional
export HTTP_STREAM_PORT=8088
export ROAM_MEMORIES_TAG=Memories
```

--------------------------------

### Fetch TODO Items

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/README.md

Retrieves all TODO items across the graph, or filters them by page, inclusion/exclusion terms.

```bash
roam get --todo                             # All TODOs across graph
```

```bash
roam get --done                             # All completed items
```

```bash
roam get --todo -p "Work"                   # TODOs on "Work" page
```

```bash
roam get --todo -i "urgent,blocker"         # TODOs containing these terms
```

```bash
roam get --todo -e "someday,maybe"          # Exclude items with terms
```

--------------------------------

### Configure Claude Desktop/Cline for Single Graph MCP Server

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/README.md

Add this JSON configuration to your Claude settings file to connect to a single Roam graph via the MCP server.

```json
{
  "mcpServers": {
    "roam-research": {
      "command": "npx",
      "args": ["-y", "roam-research-mcp"],
      "env": {
        "ROAM_API_TOKEN": "your-token",
        "ROAM_GRAPH_NAME": "your-graph"
      }
    }
  }
}
```

--------------------------------

### Roam Kanban Board Structure

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/Roam_Markdown_Cheatsheet.md

Create Kanban boards using nested bullets to define columns and cards. Each card is a bullet point within a column.

```markdown
{{[[kanban]]}}
    - Column 1
        - Card 1
        - Card 2
    - Column 2
        - Card 3
```

--------------------------------

### Create Table with roam_create_table

Source: https://context7.com/2b3pro/roam-research-mcp/llms.txt

Abstracts Roam's nested table structure, validating row/column consistency and converting empty cells to spaces. Requires a parent UID, headers, and rows with labels and cells.

```json
{
  "tool": "roam_create_table",
  "arguments": {
    "parent_uid": "page-or-block-uid",
    "order": "last",
    "headers": ["", "Q1", "Q2", "Q3"],
    "rows": [
      {"label": "Revenue",  "cells": ["$10k", "$12k", "$15k"]},
      {"label": "Expenses", "cells": ["$8k",  "$9k",  "$10k"]},
      {"label": "Profit",   "cells": ["$2k",  "$3k",  "$5k"]}
    ]
  }
}
```

--------------------------------

### Roam Output Convention: Definition

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/Roam_Markdown_Cheatsheet.md

Format for defining terms, followed by the definition and a tag.

```text
Definition: Term:: definition #definition
```

--------------------------------

### Bulk Operations with Roam Batch

Source: https://context7.com/2b3pro/roam-research-mcp/llms.txt

Use 'roam batch' for multiple operations from JSON files or stdin. Supports placeholders, dry-run, and simulate modes for safe execution.

```bash
roam batch commands.json
```

```bash
echo '[{"command":"todo","params":{"text":"Review PR"}}]' | roam batch
```

```bash
roam batch --dry-run commands.json
```

```bash
roam batch --simulate commands.json
```

```bash
roam batch commands.json -g work --write-key "$ROAM_SYSTEM_WRITE_KEY"
```

```json
[
  {"command": "page",    "params": {"title": "Sprint 42", "as": "sprint"}},
  {"command": "outline", "params": {"parent": "{{sprint}}", "items": ["Goal: Ship v3", "Timeline: 2 weeks"]}},
  {"command": "create",  "params": {"parent": "{{sprint}}", "text": "## Notes", "heading": 2, "as": "notes"}},
  {"command": "todo",    "params": {"text": "Kick-off meeting"}},
  {"command": "table",   "params": {
    "parent": "{{sprint}}",
    "headers": ["", "Owner", "Due"],
    "rows": [{"label": "Backend", "cells": ["Alice", "2026-04-01"]}]
  }},
  {"command": "remember","params": {"text": "Sprint 42 started", "categories": ["Sprint"]}},
  {"command": "codeblock","params": {"parent": "{{notes}}", "code": "npm run deploy", "language": "bash"}}
]
```

--------------------------------

### Roam Tooltip Component

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/Roam_Markdown_Cheatsheet.md

Implement tooltips that reveal hidden content upon clicking. Use the 'equal' component with the content separated by a pipe.

```plaintext
{{=:text|hidden content}}
```

--------------------------------

### roam_markdown_cheatsheet

Source: https://context7.com/2b3pro/roam-research-mcp/llms.txt

Returns the full Roam-flavored markdown syntax reference.

```APIDOC
## roam_markdown_cheatsheet

### Description
Retrieves the complete reference for Roam-flavored markdown syntax. It is recommended to load this before creating or updating Roam content to ensure correct formatting and avoid syntax errors.

### Arguments
This tool does not require any arguments.

### Example
```json
{
  "tool": "roam_markdown_cheatsheet",
  "arguments": {}
}
```
```

--------------------------------

### Find References to Content

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/ROAM-CLI-REFERENCE_LLM.md

Locate blocks that reference a specific page, contain a certain tag, or embed a given block.

```bash
roam refs "<page title>"                        # blocks linking to page
roam refs "#tag"                                # blocks with tag
roam refs "((uid))"                             # blocks embedding block
```

--------------------------------

### Smart Diff Module Functions

Source: https://context7.com/2b3pro/roam-research-mcp/llms.txt

This snippet demonstrates how to use the Smart Diff Module functions to compare block trees and generate update actions. It includes fetching page data, parsing blocks, computing the diff, generating batch actions, inspecting statistics, and summarizing the changes.

```APIDOC
## Smart Diff Module API (`roam-research-mcp/diff`)

Low-level diff engine used internally by `roam_update_page_markdown`. Can be used standalone to compute minimal update operations between two block trees.

```typescript
import {
  parseExistingBlocks,
  markdownToBlocks,
  diffBlockTrees,
  generateBatchActions,
  getDiffStats,
  isDiffEmpty,
  summarizeActions
} from 'roam-research-mcp/diff';
import { q } from '@roam-research/roam-api-sdk';

// 1. Fetch existing page data via Datalog pull
const pageData = await q(graph,
  `[:find (pull ?page [{:block/children ...} :block/uid :block/string :block/order :block/heading]) .
   :where [?page :block/uid "${pageUid}"]]`,
  []
);

// 2. Parse existing blocks into the diff format
const existingBlocks = parseExistingBlocks(pageData);

// 3. Convert new markdown to block structure
const newBlocks = markdownToBlocks(updatedMarkdown, pageUid);

// 4. Compute diff (three-phase matching: exact → normalized → position-based)
const diff = diffBlockTrees(existingBlocks, newBlocks, pageUid);

// 5. Generate minimal ordered batch actions
const actions = generateBatchActions(diff);
// actions → [{action: 'create-block'|'update-block'|'move-block'|'delete-block', ...}]

// 6. Inspect stats
const stats = getDiffStats(diff);
// stats → { created: 1, updated: 2, moved: 0, deleted: 1, preserved: 8 }

if (!isDiffEmpty(diff)) {
  console.log(summarizeActions(actions));
  // e.g. "1 created, 2 updated, 1 deleted, 8 preserved"
  await batchActions(graph, { actions });
}
```
```

--------------------------------

### Execute Batch Operations

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/README.md

Efficiently execute multiple block operations using a JSON file or stdin. Supports dry runs, simulation, and targeting specific graphs with a write key.

```bash
# From file
roam batch commands.json                # Execute commands from file
```

```bash
roam batch commands.json --dry-run      # Preview without executing (resolves pages)
```

```bash
roam batch commands.json --simulate     # Validate offline (no API calls)
```

```bash
# From stdin
cat commands.json | roam batch          # Pipe commands
```

```bash
echo '[{"command":"todo","params":{"text":"Task 1"}}]' | roam batch
```

--------------------------------

### Datalog Query: List Namespace Attributes

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/Roam_Research_Datalog_Cheatsheet.md

Retrieves all attributes present in the Datalog database along with their corresponding namespaces.

```clojure
[:find ?namespace ?attribute
 :where [_ ?attribute]
 [(namespace ?attribute) ?namespace]]
```

--------------------------------

### Output Formats

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/ROAM-CLI-REFERENCE_LLM.md

Details the output formats for various ROAM CLI commands, including the default format and the JSON flag (`-j` or `--json`) for structured data.

```APIDOC
## Output Formats

| Command | Default | JSON flag |
|---------|---------|-----------|
| `get` (page/block) | markdown | `-j` → full block structure with UIDs |
| `get --tag/--text` | markdown + count | `-j` → block array |
| `get --todo/--done` | markdown | `-j` → `[{block_uid, content, page_title}]` |
| `search` | flat list | `--json` → `[{block_uid, content, page_title}]` |
| `refs` | grouped by page | `--json` → `[{uid, content, page}]` |
| `batch` | always JSON | `{success, pages_created, actions_executed, uid_map?}` |
```

--------------------------------

### Refs Command Options

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/ROAM-CLI-REFERENCE_LLM.md

Options for the `roam refs` command, including limiting results, JSON output, and raw output.

```bash
Options: -n limit, --json, --raw
```

--------------------------------

### Roam Dropdown Component

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/Roam_Markdown_Cheatsheet.md

Create a dropdown list with selectable options using the 'or' component. Only the selected option is displayed.

```plaintext
{{or: option A|option B|option C}}
```

--------------------------------

### Parent Heading Syntax

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/ROAM-CLI-REFERENCE_LLM.md

Syntax for specifying a parent heading when saving content. The '#' prefix indicates the heading level, and it will be created if it doesn't exist.

```bash
Parent heading syntax: "## Section" (# prefix sets heading level, creates if missing)
```

--------------------------------

### Prepend Content to a Roam Page

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/README.md

Add new content to the beginning of a specified Roam Research page using 'roam save' with the --order first flag. Useful for logs or changelogs.

```bash
# Prepend to top of page (newest-first ordering)
roam save -p "Changelog" --order first "v2.18.0 release"
```

--------------------------------

### Search Roam Pages by Namespace

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/README.md

Find all Roam Research pages that match a given namespace prefix using the 'roam search --namespace' command.

```bash
# Search for pages by namespace prefix
roam search --namespace "Convention"    # Finds all Convention/* pages
```

--------------------------------

### Fetch Roam Daily Pages by Date

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/README.md

Retrieve Roam Research daily pages using various date formats. The CLI automatically normalizes ISO, US, and named date inputs.

```bash
# Fetch daily pages using any date format (auto-normalized)
roam get today                          # Today's daily page
roam get 2026-03-21                     # ISO date → "March 21st, 2026"
roam get "03/21/2026"                   # US date → "March 21st, 2026"
roam get "March 21"                     # Named (assumes current year)
```

--------------------------------

### Resolve Page Title to UID

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/README.md

Obtains the unique identifier (UID) for a given page title.

```bash
roam get "Project Notes" --uid              # Returns just the page UID
```

```bash
roam get today -u                           # Today's daily page UID
```

--------------------------------

### Save Note to a Specific Page

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/ROAM-CLI-REFERENCE_LLM.md

Append a note to a designated page with `roam save "Note" -p "Page"`.

```bash
roam save "Note" -p "Page"
```

--------------------------------

### Roam Document Mode

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/Roam_Markdown_Cheatsheet.md

Activate an inline WYSIWYG text editor within a block by using the ':document' command.

```plaintext
':document
```

--------------------------------

### Save Content to Roam

Source: https://context7.com/2b3pro/roam-research-mcp/llms.txt

Use 'roam save' to create new blocks or pages from text, files, or stdin. Supports markdown hierarchy, TODOs, categories, and smart updates.

```bash
roam save "Idea: use batch operations for efficiency"
```

```bash
roam save "Reviewed PR #42" -p "Work Log"
```

```bash
roam save --parent "## Meetings" "Discussed roadmap"
```

```bash
roam save "First item" -p "Changelog" --order first
```

```bash
roam save --todo "Buy groceries"
```

```bash
echo "Fix bug #123" | roam save --todo
```

```bash
cat meeting_notes.md | roam save --title "Meeting: 2026-03-21"
```

```bash
roam save meeting_notes.md --title "Meeting: 2026-03-21"
```

```bash
roam save updated_doc.md --title "My Document" --update
```

```bash
roam save "Insight about caching" -c "Architecture,Performance"
```

```bash
echo '[{"text":"Block 1","level":1},{"text":"Sub-block","level":2}]' | roam save --json --title "Outline"
```

```bash
printf "Line 1\nLine 2\nLine 3" | roam save --lines -p "Notes"
```

```bash
roam save "Sensitive note" -g work --write-key "$ROAM_SYSTEM_WRITE_KEY"
```

--------------------------------

### Save Note Under a Heading

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/ROAM-CLI-REFERENCE_LLM.md

Add a note as a child block under a specific heading on a page using `roam save --parent "## Section" "Note"`. The heading will be created if it doesn't exist.

```bash
roam save --parent "## Section" "Note"
```

--------------------------------

### Raw Datalog Queries with Roam Search

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/README.md

Execute advanced searches using raw Datalog queries. Supports passing inputs and client-side regex filtering.

```bash
roam search -q '[:find ?title :where [?e :node/title ?title]]'
```

```bash
roam search -q '[:find ?s :in $ ?term :where [?b :block/string ?s] [(clojure.string/includes? ?s ?term)]]' --inputs '["TODO"]'
```

```bash
roam search -q '[:find ?uid ?s :where [?b :block/uid ?uid] [?b :block/string ?s]]' --regex "meeting" --regex-flags "i"
```

--------------------------------

### Roam Daily Template Component

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/Roam_Markdown_Cheatsheet.md

Add a '+' button to daily notes to insert a predefined template. Reference the template block using its UID.

```plaintext
{{x-daily-template: ((roam/template block ref))}}
```

--------------------------------

### `roam batch` - Bulk Operations

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/ROAM-CLI-REFERENCE_LLM.md

Performs multiple Roam operations in a single batch, either from a file or standard input.

```APIDOC
## `roam batch` - Bulk Operations

### Description
Executes a series of Roam commands in a batch, read from a file or standard input.

### Usage
- `roam batch commands.json`: Execute commands from a JSON file.
- `echo '<json>' | roam batch`: Execute commands piped from standard input.
- `roam batch --dry-run commands.json`: Perform a dry run to preview operations without making changes.
- `roam batch --simulate commands.json`: Simulate the batch operation offline to validate commands.
```

--------------------------------

### Mark a TODO Item as Done

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/ROAM-CLI-REFERENCE_LLM.md

Update a block's status to 'done' by providing its UID and using the `-D` flag with `roam update <uid> -D`.

```bash
roam update <uid> -D
```

--------------------------------

### Fetch Block by UID

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/README.md

Retrieves a specific block using its unique identifier (UID).

```bash
roam get abc123def                          # Block by UID
```

```bash
roam get "((abc123def))"                    # UID with wrapper
```

--------------------------------

### Output Options with Roam Search

Source: https://github.com/2b3pro/roam-research-mcp/blob/main/src/cli/README.md

Control the number of results returned and the output format. Use -n for limiting results and --json for JSON output.

```bash
roam search "design" -n 50                # Limit to 50 results
```

```bash
roam search "api" --json                  # JSON output
```