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
search-pages	Multi-query search aggregated by page, with daily page drill-down
q	Run raw datalog query
save	Save GFM markdown as a page, daily page (--to-daily-page / --today), or under a parent block; --under finds-or-creates a child block
journal	Read daily journaling blocks
block find	Find block UID by text on a page/daily note
block create	Create block(s) — single, nested tree, or with --attach-to
block update/delete/move/get	Low-level single-block operations
batch run	Batch actions from JSON array

Run roam-cli help <category> for categorized usage examples. Categories: read, write, workflow, or all.

Search Strategy

Use search-pages for broad retrieval, search for targeted lookup.

Scenario	Use this
Find pages related to a topic across the whole graph	search-pages with multiple query args
Find specific blocks containing exact terms	search
Search within a known page	search --page "Page Title"

search-pages — multi-query page-level search

Each positional argument is an independent query. Terms within one argument are AND-matched (block must contain all terms). Results are deduplicated, aggregated by page, and sorted by queries matched then hit count.

# Multiple independent queries — results merged and ranked
roam-cli search-pages "SaaS 倒闭" "AI 贷款" "SaaS shutdown" -i

# With --json for structured output (pipe to rerank tools)
roam-cli search-pages "query1" "query2" -i --json

# Limit results
roam-cli search-pages "broad term" -i --limit 20

Daily page handling: Daily pages (e.g. "March 8th, 2026") are automatically drilled down to show sections instead of the whole page.

# Default: aggregate at first-level children of daily pages
roam-cli search-pages "AI 贷款" -i

# Drill deeper: aggregate at second level, filter first level by topic
roam-cli search-pages "AI 贷款" -i --daily-depth 2 --daily-topic "📖 Daily Reading"

Flag	Purpose
--daily-depth N	Aggregation depth for daily pages (default 1)
--daily-topic TEXT	Filter daily page sections at level 1 by topic text
--limit N	Max results to return (0 = unlimited)
-i	Case-insensitive search
--json	Structured JSON output

Output includes ((block_uid)) for each result — use roam-cli get "((uid))" to retrieve full content with children.

Write Strategy (critical — read this first)

Minimize API calls. Every tool call costs tokens. Use the highest-level command that fits.

Scenario	Use this	NOT this
Save content to today's daily page	save --today	journal → parse UID → save --parent
Save content to a specific daily page	save --to-daily-page 2026-03-14	block find --daily → save --parent
Save under a section in today's daily page	save --today --under '[[Section]]'	block find → block create --parent
Save under a section in any page	save --title "Page" --under '[[Section]]'	block find → block create --parent
Save a long document/article as a page	save --title "Page Name"	Sequential block create
Create a parent with children	block create --parent <uid> --file tree.json	block create parent → block create child × N
Insert under existing section	block create --parent <uid> --attach-to "[[Section]]"	block find → block create --parent
Multiple heterogeneous writes	batch run	Multiple individual write calls
Single block, no children	block create --parent <uid> --text "foo"	(this is fine)

block create modes

# Single block
roam-cli block create --parent <uid> --text "Hello"

# Nested tree (JSON input via file or stdin)
echo '{"text":"Root","children":[{"text":"Child"}]}' | roam-cli block create --parent <uid>
roam-cli block create --parent <uid> --file tree.json

# Attach-to: find or create a section block, then insert under it
roam-cli block create --parent <page-uid> --attach-to "[[📽 Journaling]]" --text "new item"
roam-cli block create --parent <page-uid> --attach-to "[[📽 Journaling]]" --file items.json

--attach-to finds an existing block with matching text under --parent. If not found, creates it first. Then creates the content under that block.

Daily page operations

Use --today or --to-daily-page for one-shot writes to daily pages. Do NOT manually construct Roam daily page titles like "March 14th, 2026" — the CLI handles this internally. Pages are automatically upserted (created if missing, appended to if existing).

# Save markdown to today's daily page
echo "- entry" | roam-cli save --today

# Save to a specific date
cat note.md | roam-cli save --to-daily-page 2026-03-14

# Save under a section in today's daily page (find-or-create)
echo "- journal entry" | roam-cli save --today --under '[[📽 Journaling]]'

# Save under a section in a named page
cat note.md | roam-cli save --title "Project Notes" --under '[[Tasks]]'

# Search/find on a daily page — pass ISO date, CLI auto-resolves
roam-cli search --page 2026-03-14 keyword
roam-cli block find --page 2026-03-14 --text "[[📖 Daily Reading]]"

--under finds an existing direct child block with matching text under the target page. If not found, creates it first. Then appends content under that block. This is the recommended way to write to daily page sections like [[📽 Journaling]].

Anti-patterns — do NOT do these

• Do NOT call block create in a loop to build a tree. Use JSON input with children.
• Do NOT fire multiple block create in parallel to the same parent. Use batch run or JSON tree input.
• Do NOT do multi-step "find block → then create under it". Use --attach-to.
• Do NOT do multi-step "find daily page UID → then write". Use save --today or save --to-daily-page.
• Do NOT do multi-step "find daily page → find section → write under it". Use save --today --under '[[Section]]'.
• Do NOT manually construct "Month DDth, YYYY" date strings. Pass ISO dates (YYYY-MM-DD) to --to-daily-page, --daily, or --page — the CLI converts them.
• Do NOT add --stdin when piping — it's automatic.

Pipeline Support

All commands that accept input (save, block create, batch run) read from stdin by default when --file is not given. No --stdin flag needed.

echo '{"text":"root","children":[{"text":"child"}]}' | roam-cli block create --parent <uid>
cat note.md | roam-cli save --title "Page Name"
echo '[...]' | roam-cli batch run

block create JSON Input Contract

• Requires --parent <block-uid>.
• Accepts JSON from pipe or --file.
• JSON supports either a single object or an array of objects.
• Node shape: text (required), children (optional array of nodes).
• Both text and string keys accepted (text takes precedence).

{"text": "headline", "children": [
  {"text": "point 1"},
  {"text": "point 2", "children": [{"text": "sub-point"}]}
]}

batch run Actions

Native actions (pass-through to Roam API):

• create-block — supports children in block field (auto-expanded) and attach-to in location
• update-block — requires block.uid and block.string
• delete-block — requires block.uid
• move-block — requires block.uid and location.parent-uid
• create-page — requires page.title

[
  {"action": "create-block",
   "location": {"parent-uid": "PAGE_UID", "attach-to": "[[📽 Journaling]]", "order": "last"},
   "block": {"string": "new item under Journaling"}},

  {"action": "create-block",
   "location": {"parent-uid": "PARENT_UID", "order": "last"},
   "block": {"string": "Parent", "children": [
     {"string": "Child 1"},
     {"string": "Child 2", "children": [{"string": "Grandchild"}]}
   ]}}
]

Date Handling

The CLI auto-resolves ISO dates (YYYY-MM-DD) to Roam daily page titles wherever a page reference is expected:

Flag	Input	Resolved to
save --to-daily-page / --today	2026-03-14 / today	Creates/finds page "March 14th, 2026"
search --page	2026-03-14	Searches in "March 14th, 2026"
block find --page	2026-03-14	Finds block in "March 14th, 2026"
block find --daily	2026-03-14	Finds by daily page UID (existing behavior)
journal --date	2026-03-14	Reads daily journal (existing behavior)

Recommended Workflow

1. roam-cli status — verify credentials.
2. Read: get, search, search-pages, q, journal, block find.
3. Write (pick one, in order of preference):
   • Daily page content → save --today or save --to-daily-page
   • Daily page section → save --today --under '[[Section]]'
   • Long markdown → save --title
   • Nested blocks / attach to existing section → block create (with JSON + --attach-to)
   • Mixed operations → batch run
   • Single block → block create --text

Save Markdown (GFM format)

save accepts GFM and auto-converts to Roam blocks:

• Do NOT include # h1 — title comes from --title or --to-daily-page
• ##–### → headed blocks (levels 4–6 capped to 3)
• Lists → nested child blocks; ordered lists preserve marker
• Tables → {{[[table]]}} blocks (must be valid GFM pipe+separator)
• Code blocks, blockquotes → passed through
• Horizontal rules → discarded

Full rules: references/gfm-format.md

Error Handling Rules

• Missing credentials: report missing ROAM_API_TOKEN / ROAM_API_GRAPH.
• API failures: include HTTP status code and response body.
• Not found: 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

Run roam-cli help all or see references/usage-examples.md.