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

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

Write Strategy (critical — read this first)

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

Daily page operations

Use --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.

# Save markdown to today's daily page
cat note.md | roam-cli save --to-daily-page

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

# 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]]"

Anti-patterns — do NOT do these

• Do NOT call block create in a loop to build a tree. Use block create-tree.
• Do NOT fire multiple block create in parallel to the same parent. Use batch run or block create-tree.
• Do NOT do multi-step "find daily page UID → then write". Use save --to-daily-page.
• 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-tree, 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-tree --parent <uid>
cat note.md | roam-cli save --title "Page Name"
echo '[...]' | roam-cli batch run

block create-tree 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"}]}
]}

Date Handling

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

Recommended Workflow

1. roam-cli status — verify credentials.
2. Read: get, search, q, journal, block find.
3. Write (pick one, in order of preference):
   • Daily page content → save --to-daily-page
   • Long markdown → save --title
   • Structured tree → block create-tree
   • Mixed operations → batch run
   • Single block → block create

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.