A fast, keyboard-driven terminal client, MCP server, and Rust SDK for Roam Research. Navigate, edit, and search your knowledge graph without leaving the terminal — connect AI assistants via MCP — or use the SDK to build your own tools.

Documentation | crates.io

┌─────────────────────────────────────────────────────────┐
│ roam-tui   [Graph: my-graph]              Feb 24, 2026  │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  February 24, 2026                                      │
│                                                         │
│  • Meeting notes with [[John]]                          │
│    • Discussed Q1 roadmap                               │
│    • Action items: ((ref-uid))                          │
│  ▸ Project ideas  [3 collapsed]                         │
│  • Read chapter 5 of **Deep Work**                      │
│    • Key insight: time blocking works                   │
│                                                         │
│  February 23, 2026                                      │
│                                                         │
│  • Finished migration to new API                        │
│  • {{DONE}} Review PR #42                               │
│                                                         │
├─────────────────────────────────────────────────────────┤
│ [i]edit  [o]new  [/]search  [?]help  [h/l]collapse/expand│
└─────────────────────────────────────────────────────────┘

roam-tui includes a built-in MCP server that exposes your Roam graph to AI assistants (Claude, Cursor, etc.). Connects directly to the Roam Research cloud API — no local Roam desktop app needed.

Add to your MCP client config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "roam": {
      "command": "npx",
      "args": ["-y", "roam-tui@latest", "--mcp"],
      "env": {
        "ROAM_GRAPH_NAME": "your-graph-name",
        "ROAM_GRAPH_API__TOKEN": "roam-graph-token-XXXXX"
      }
    }
  }
}

Or if you have the binary installed:

roam --mcp

All SDK operations are available as CLI subcommands. No subcommand launches the TUI.

roam journal add "Meeting with [[John]]"     # add to today's daily note
roam journal                                  # view today's note (JSON)
roam search "project" --blocks --limit 10     # search block content
roam get page "Books"                         # get a page with all blocks
roam get backlinks "Project Alpha"            # find references to a page
roam get stats                                # graph statistics
roam export --page "Books" --format json      # export page as JSON
roam query '[:find ?t :where [?e :node/title ?t]]'  # raw Datalog query
roam create page "New Project"                # create a page
roam create block --parent "uid" "Content"    # create a block
roam batch operations.json                    # batch write operations

Full reference: CLI docs

Roam Research is powerful but lives in the browser. If you spend most of your day in the terminal, context switching costs add up. roam-tui gives you direct access to your graph — fast, focused, and keyboard-first.

Not a replacement for the web UI. Use roam-tui for quick capture, daily note workflows, and navigating your graph. Use the web for complex queries, graph visualization, and plugin-heavy workflows.

npx roam-tui@latest --mcp

git clone https://github.com/avelino/roam-tui
cd roam-tui
cargo install --path .

• A Roam Research graph with an API token (how to get one)
• Rust 1.70+ (only for building from source)

Run roam for the first time — it creates a config file and tells you where:

roam
# → Created default config at: ~/.config/roam-tui/config.toml
# → Please edit it with your Roam graph name and API token, then run again.

Add your credentials:

# ~/.config/roam-tui/config.toml

[graph]
name = "your-graph-name"
api_token = "roam-graph-token-XXXXX"

Or use an environment variable:

export ROAM_GRAPH_API__TOKEN="roam-graph-token-XXXXX"

Run again:

roam

Your daily note loads. Start navigating.

Opens today's note on launch. Navigate to previous days with P / PageUp (vim) or scroll past the last block to auto-load older days. Jump back to today with G.

Full block editing with vim-style modal workflow:

• i to edit the selected block, Esc to save and exit
• o to create a new block below
• dd to delete a block
• Tab / Shift+Tab to indent/unindent
• Undo with u, redo with Ctrl+R
• Auto-pairing for (), [], {}
• {{TODO}} / {{DONE}} toggle with Alt+Enter or Ctrl+Enter

Blocks with children can be collapsed (h) and expanded (l). Press Enter to toggle. Collapsed blocks hide their children from navigation and display — just like the web UI.

Press / to open a search popup. Type to filter across all loaded blocks and cached references. Navigate results with arrow keys, press Enter to jump to the block.

Type (( in edit mode to open the autocomplete popup. Search for any block by content, select with Enter. References are resolved and displayed inline.

Blocks render with full Roam syntax support:

Fenced code blocks (```) render with syntax highlighting via tree-sitter. Supported languages: Rust, Python, JavaScript, TypeScript, Go, C, Bash, JSON, TOML, YAML, HTML, CSS, Markdown.

Press ? to see all keybindings for your current preset. Any key closes the help overlay.

API errors (rate limits, auth failures, network issues) appear as a popup overlay with a human-readable title and hint instead of raw JSON. Any key dismisses the popup.

Three built-in presets. Set with keybindings.preset in config.

Override any key in the config file:

[keybindings]
preset = "vim"

[keybindings.bindings]
quit = "Ctrl+q"
search = "Ctrl+f"

Config file location: ~/.config/roam-tui/config.toml

All options with defaults:

[graph]
name = ""                    # required — your Roam graph name
api_token = ""               # required — or set ROAM_GRAPH_API__TOKEN env var

[ui]
theme = "dark"               # dark | light
sidebar_default = true       # show sidebar on startup
sidebar_width_percent = 35   # sidebar width as percentage

[keybindings]
preset = "vim"               # vim | emacs | vscode

# [keybindings.bindings]     # override individual keys
# quit = "Ctrl+q"

Environment variables override config file values. Prefix with ROAM_, use __ for nesting:

ROAM_GRAPH_NAME=my-graph
ROAM_GRAPH_API__TOKEN=roam-graph-token-XXXXX

What's working now and what's next.

• Daily notes with multi-day navigation
• Block tree editing (create, edit, delete, indent, move)
• Collapse/expand blocks
• Undo/redo
• Full-text search across blocks
• Block reference autocomplete ((()
• Markdown + Roam syntax rendering
• Code block syntax highlighting (14 languages)
• Three keybinding presets (vim, emacs, vscode)
• Custom keybinding overrides
• Help overlay
• Optimistic UI updates (no lag on edits)
• Auto-refresh from API
• Page navigation (follow [[links]])
• Navigation history (back/forward)
• Cursor navigation (left/right within blocks)
• User-friendly error popups (rate limits, auth, network)
• Quick switcher (fuzzy page navigation)
• Linked references / backlinks panel
• Page creation from [[links]] and Quick Switcher
• MCP server (--mcp flag, 18 tools, npm distribution)
• Export to markdown and JSON (CLI + TUI keybinding)
• Multi-block selection with batch operations (Shift+Up/Down)

• Sidebar with page references
• Unlinked references
• Light theme
• Breadcrumb display

git clone https://github.com/avelino/roam-tui
cd roam-tui
cargo test     # 551 tests
cargo run      # requires config with valid API token

Tests run without network access — API interactions use wiremock for mocking.

MIT — see LICENSE for details.