RoamResearch Skill

Use this skill to perform Roam Research read/write/query workflows through roam-cli.

Prerequisites

roam-cli binary in PATH
Environment variables: ROAM_API_TOKEN, ROAM_API_GRAPH
Run roam-cli status to verify before any operations

If not set up, see references/installation.md.

Command Mapping

| Command | Purpose | |---|---| | get | Read page by title or block by UID | | search | Search blocks by terms | | q | Run raw datalog query | | save | Save GFM markdown as a page (--title) or under a parent block (--parent) | | journal | Read daily journaling blocks | | block find | Find block UID by text on a page/daily note | | block create-tree | Create nested block tree from JSON | | block create/update/delete/move/get | Low-level block operations | | batch run | Batch actions (native + create-with-children DSL) |

`block create-tree` Input Contract

Requires --parent <block-uid>.
JSON supports either a single object or an array of objects.
Node shape is:
- text (required): block text
- children (optional): nested nodes
CLI accepts both text and string in input JSON (text takes precedence when both are provided).

Example:

{
  "text": "Current State - 2026-02-24",
  "children": [
    {"text": "Project A", "children": [{"text": "Task 1"}]}
  ]
}

Recommended Workflow

Run roam-cli status first.
Prefer read commands first: get, search, q.
Prefer high-level writes: save, journal.
Use low-level APIs for deterministic control: block, batch.

Save Markdown (GFM format)

save accepts GFM (GitHub Flavored Markdown) and auto-converts to Roam blocks. Key rules:

Do NOT include # h1 — page title comes from --title
Headings ##–### become headed blocks (levels 4–6 capped to 3)
Lists (-/*/+) become nested child blocks; ordered lists preserve the 1. marker
Tables MUST use standard GFM pipe+separator format (header row, --- row, data rows)
Code blocks, blockquotes passed through; horizontal rules discarded

Full conversion rules: see references/gfm-format.md

Error Handling Rules

Missing credentials: explicitly report missing ROAM_API_TOKEN / ROAM_API_GRAPH.
API failures: include HTTP status code and response body.
Not found: clearly include the identifier/uid that was requested.

Output Rules

Preserve JSON output when --json is requested.
Keep default output concise and readable.
Never invent Roam data; only report real command results.

Detailed Examples

See references/usage-examples.md for full command examples.