Heptabase CLI / MCP / DB Operations

本頁只整理 Heptabase 的操作面，不含 vault 架構規劃。

0) Scope 與版本基線

• 版本基線：2026-04 的 CLI 能力面（v0.1.0 指令介面）。
• 能力邊界：本頁只列可驗證的 CLI / 本機 DB 操作，不假設未公開 API。
• 判斷原則：若要確認能力是否仍可用，先跑 help dump（見文末版本巡檢）。

1) CLI 可直接執行的操作

啟動與連線

• heptabase start — 啟動 desktop app，等待本機 CLI server ready
  • 常用參數：--timeout-ms、--poll-interval-ms

卡片（card）

• heptabase card list — 支援分頁、排序、關鍵字過濾；輸出欄位：id、objectType、title、createdTime、lastEditedTime
• heptabase card trash <cardId>
• heptabase card restore <cardId>

AI Tutor（goal / course / lesson）

• heptabase goal list — 列頂層目標與其下課程
• heptabase course list
• heptabase course read <courseId> — 拿 syllabus 與 topic
• heptabase lesson list <courseId>
• heptabase lesson read <lessonId> — 拿 lesson plan 與 artifact card id
• heptabase lesson list-messages <lessonId> — 拿對話紀錄 markdown

Journal

• heptabase journal create
• heptabase journal read <date> — 回傳 contentMd5，供後續 save 衝突檢查用
• heptabase journal append <date> — 追加 markdown，不需讀取現有內容
• heptabase journal save <date> — 需帶最新 contentMd5

Note

• heptabase note create — 輸入 markdown
• heptabase note read <cardId> — 回傳 ProseMirror JSON + contentMd5
• heptabase note append <cardId> — 輸入 markdown
• heptabase note save <cardId> — 輸入 ProseMirror JSON，需帶最新 contentMd5

Tag

• heptabase tag create
• heptabase tag list
• heptabase tag cards <tagId> — 反查同標籤卡片
• heptabase tag add
• heptabase tag remove

CLI 資料格式

• 所有指令回傳 JSON。
• create、append 吃 markdown；read、save 用 ProseMirror JSON。
• save 一律需帶最新 contentMd5，先 read 取得再送出。

1.5) Command Matrix（用途速查）

2) MCP 操作面（以 CLI 能力為上限）

目前可確認的是本機 CLI server 能力，沒有獨立的 whiteboard MCP 指令組。

• 實務上，MCP 若要整合 Heptabase，通常是包裝上面同一組 CLI 操作。
• 因此 MCP 可做的操作面，等價於 CLI 已公開的 start/card/course/goal/journal/lesson/note/tag。

MCP 實務建議

• 以工具分層定義：
  • read tools：card list、note read、journal read、lesson read
  • write tools：note create/append/save、journal create/append/save、tag add/remove
  • admin tools：start
• 對 write tools 強制參數檢查：
  • 先 read 拿到最新 contentMd5
  • 再允許 save
• 對高風險操作加保護：
  • card trash 需二次確認
  • save 預設先備份讀取內容

3) DB（SQLite）操作面：whiteboard 讀取

CLI v0.1.0 沒有 whiteboard 指令；whiteboard 相關資訊需從本機 SQLite 查詢。

常見 DB 路徑

• Windows：%APPDATA%\\project-meta\\hepta.db
• macOS：~/Library/Application Support/project-meta/hepta.db

補充：

• 若路徑不一致，優先檢查 app 啟動參數中的 --user-data-dir。

Whiteboard 查詢流程

1. 啟動：heptabase start
2. 從 whiteboard URL 取 <whiteboardId>
3. 查名稱：

SELECT id, name
FROM whiteboard
WHERE id = '<whiteboardId>';

4. 查卡片與座標：

SELECT ci.card_id, c.title, ci.x, ci.y, ci.color
FROM card_instance ci
LEFT JOIN card c ON ci.card_id = c.id
WHERE ci.whiteboard_id = '<whiteboardId>'
ORDER BY ci.y, ci.x;

5. 查文字元素：

SELECT content, x, y
FROM text_element
WHERE whiteboard_id = '<whiteboardId>'
ORDER BY y;

6. 查子 whiteboard：

SELECT wi.container_id, w.name
FROM whiteboard_instance wi
JOIN whiteboard w ON wi.container_id = w.id
WHERE wi.whiteboard_id = '<whiteboardId>';

7. 逐卡讀內容：heptabase note read <card_id>

Schema 探索補充

• 列所有資料表：

.tables

• 常用表（依現有可見線索）：

  • whiteboard
  • card_instance
  • card
  • text_element
  • whiteboard_instance

• 常見關聯：

  • card_instance.card_id -> card.id
  • card_instance.whiteboard_id -> whiteboard.id

4) 可直接複製的操作配方

配方 A：列出最近更新卡片

heptabase start
heptabase card list --sort lastUpdatedTime --direction descending -l 20

配方 B：建立卡片並持續追加

heptabase note create -f draft.md
heptabase note append <card-id> -f patch.md
heptabase note read <card-id>

配方 C：tag-based 卡片批次盤點

heptabase tag list --name-filter engineer
heptabase tag cards <tag-id>

配方 D：AI Tutor lesson artifact 轉讀

heptabase course list
heptabase lesson list <course-id>
heptabase lesson read <lesson-id>
heptabase note read <artifact-card-id>

配方 E：whiteboard 座標抽取

sqlite3 "$DB" "SELECT ci.card_id, c.title, ci.x, ci.y, ci.color FROM card_instance ci LEFT JOIN card c ON ci.card_id = c.id WHERE ci.whiteboard_id = '<whiteboardId>' ORDER BY ci.y, ci.x;"

5) 已知限制（2026-04）

• 無法用 CLI 直接把卡片放進 whiteboard（UI-only）。
• markdown 內 card-id<!-- unpublished: card-id -->、@card-id 不會變成原生 mention。
• 可行替代：用一般 markdown link（heptabase://card/<id> 或 app URL）。

能力矩陣（可行 / 不可行）

6) 故障排查（Troubleshooting）

症狀：CLI 指令卡住或連不到

• 可能原因：desktop app 未就緒。
• 處理：先跑 heptabase start，加大 --timeout-ms。

症狀：save 失敗或衝突

• 可能原因：contentMd5 過期。
• 處理：先重新 read 取得最新 contentMd5，再重送 save。

症狀：找不到 hepta.db

• 可能原因：user data 目錄非預設路徑。
• 處理：檢查行程參數中的 --user-data-dir，再組合 DB 路徑。

症狀：whiteboard 查不到卡片

• 可能原因：whiteboardId 錯誤或 SQL 過濾條件不符。
• 處理：先驗證 whiteboard 表中 id/name，再查 card_instance。

7) 版本巡檢清單（每次升級後）

1. 跑 heptabase -h 看 command group 是否新增。
2. 逐組跑 <group> -h 更新參數與回傳結構認知。
3. 抽樣驗證：

• note create/read/append/save
• lesson read + artifact read
• tag add/remove

4. 若新增 whiteboard/mention 相關指令，更新本頁能力矩陣。

8) 參數附錄（實測 -h，2026-04-25）

本節只收錄已由終端機 -h 輸出驗證的參數與引數。

8.1 全域

8.2 start

8.3 card

8.4 note

8.5 journal

8.6 tag

8.7 course / lesson / goal

9) 來源

• heptabase-cli-deep-dive-2026-04-25
• heptabase-whiteboard-sqlite-windows-2026-04-25

10) 延伸閱讀

• heptabase-vault-integration-playbook-2026-04-25