適用版本：Heptabase v1.91.0+（2026 年 4 月 22 日正式推出）
適用對象：使用 Claude Code、Cursor、Codex 或其他 AI Coding Agent 的知識工作者
撰寫日期：2026-04-23
這是什麼？為什麼重要？
Heptabase CLI 是官方內建於桌面應用程式中的命令列工具，讓你可以透過終端機（Terminal）直接對知識庫進行搜尋、讀取、建立與管理操作。
更重要的是，它讓 AI Agent 能夠程式化存取你的整個知識庫——包括卡片、日記、標籤，甚至 AI Tutor 的課程與對話紀錄。
一句話總結：從此以後，你的 7,000+ 張卡片不再只能用手動翻找，而是可以用一行指令搞定。
第一步：安裝與啟用
前置條件
- Heptabase 桌面版已更新至 v1.91.0 以上
- macOS 系統（Windows/Linux 操作類似）
啟用步驟
- 打開 Heptabase 桌面版
- 點擊左下角頭像 → Settings
- 進入 AI Features 頁面
- 找到最下方的 CLI 區塊
- 將開關切換為 Enabled
- 系統會彈出提示：
Enable the "heptabase" command
Add "/usr/local/bin" to your PATH, then reopen your terminal.- 點擊 Done
驗證安裝
打開終端機，輸入：
heptabase --version應該看到：
0.1.0再確認 CLI 伺服器就緒：
heptabase start成功回應：
{
"status": "ready",
"startedDesktopApp": false
}注意：CLI 需要 Heptabase 桌面版正在執行才能使用。
heptabase start會自動啟動 App（如果尚未開啟）。
核心概念
在使用 CLI 之前，先理解三個關鍵概念：
1. 所有輸出都是 JSON
CLI 的每個指令都回傳 JSON 格式，方便程式化處理：
{
"results": [...],
"total": 7017,
"offset": 0,
"limit": 20
}2. 寫入用 Markdown，讀取得到 ProseMirror JSON
| 操作 | 格式 |
|---|---|
create（建立） |
Markdown ✅ |
append（追加） |
Markdown ✅ |
read（讀取） |
ProseMirror JSON |
save（覆蓋） |
ProseMirror JSON + contentMd5 |
實務建議：日常使用以
create和append為主（直接寫 Markdown），避免直接操作 ProseMirror JSON。
3. 衝突偵測機制
save 操作需要提供 --content-md5（從最近一次 read 取得），防止多端編輯時的資料覆蓋。
完整指令集
📋 一、卡片管理 (card)
管理所有類型的卡片（筆記、PDF、日記、圖片、影片等）。
列出 / 搜尋卡片
# 列出最近更新的 20 張卡片（預設）
heptabase card list
# 搜尋關鍵字
heptabase card list -q "AI Agent"
# 只顯示筆記類型的卡片
heptabase card list --card-types note
# 多種類型篩選
heptabase card list --card-types "note,pdf,journal"
# 按建立時間排序（由新到舊）
heptabase card list --sort createdTime --direction descending
# 分頁：取第 21-40 筆
heptabase card list --offset 20 --limit 20
# 組合：搜尋「教學」相關筆記卡，取前 5 筆
heptabase card list -q "教學" --card-types note --limit 5回傳格式：
{
"results": [
{
"id": "015f4e9f-bbe1-42bc-...",
"objectType": "note",
"title": "AI 問題建模任務卡",
"createdTime": "2026-04-22T...",
"lastEditedTime": "2026-04-22T..."
}
],
"total": 7017,
"offset": 0,
"limit": 5
}可用卡片類型：note、pdf、journal、highlightElement、source、image、video、audio、web
排序欄位：title、lastUpdatedTime（預設）、createdTime
刪除與還原卡片
# 軟刪除（移至回收桶）
heptabase card trash <cardId>
# 從回收桶還原
heptabase card restore <cardId>📝 二、筆記卡片 (note)
建立、讀取、儲存與追加筆記卡片。
建立新筆記
# 用 Markdown 直接建立（第一行 # 標題會成為卡片標題）
heptabase note create -c "# 會議記錄 2026-04-23
## 議題
- AI 導入進度
- 下季度目標
## 決議
1. 優先完成 Heptabase 整合
2. 建立自動化知識同步流程"回傳：
{
"id": "24dff0b3-de1d-4d82-...",
"title": "會議記錄 2026-04-23"
}從檔案建立筆記
# 將本地 Markdown 檔案匯入為卡片
heptabase note create -f ./meeting_notes.md讀取筆記
heptabase note read <cardId>追加內容
# 在既有卡片末尾追加內容
heptabase note append <cardId> -c "## 補充
- 新增一條行動項目"
# 從檔案追加
heptabase note append <cardId> -f ./additional_notes.md覆蓋儲存（進階）
# 先讀取取得 contentMd5
heptabase note read <cardId>
# 再用 ProseMirror JSON 覆蓋（需提供 md5 防衝突）
heptabase note save <cardId> --content-md5 "e296d763cc..." -f ./new_content.json📔 三、日記 (journal)
按日期建立、讀取與追加日記。
建立日記
# 建立今天的日記
heptabase journal create -c "# 今日重點
- 完成 Heptabase CLI 教學文章
- 蘋果總裁班備課"
# 建立指定日期的日記
heptabase journal create -d 2026-04-23 -c "今日行程：Yvonne 教學 + 蘋果總裁班"
# 從檔案建立
heptabase journal create -d 2026-04-23 -f ./daily_note.md注意：如果該日期已有內容，會回傳 409 錯誤。改用
append追加。
讀取日記
heptabase journal read 2026-04-23追加日記
# 在當日日記末尾追加
heptabase journal append 2026-04-23 -c "## 晚間補充
今天最大的收穫是..."
# 從檔案追加
heptabase journal append 2026-04-23 -f ./evening_notes.md🏷️ 四、標籤管理 (tag)
建立、列出、新增與移除標籤。
列出所有標籤
# 列出全部標籤
heptabase tag list
# 按名稱篩選（不區分大小寫）
heptabase tag list --name-filter "教學"建立新標籤
heptabase tag create --name "AI工作流"如果標籤已存在，回傳 409 錯誤。
為卡片加標籤
# 用卡片 ID
heptabase tag add --card-id <cardId> --tag-name "AI工作流"
# 為日記加標籤（直接用日期作為 card-id）
heptabase tag add --card-id 2026-04-23 --tag-name "教學日"亮點：如果標籤不存在，
tag add會自動建立。
列出標籤下的卡片
heptabase tag cards <tagId>移除標籤
heptabase tag remove --card-id <cardId> --tag-id <tagId>🎓 五、AI Tutor — 學習目標 (goal)
查看 AI Tutor 的頂層學習目標。
heptabase goal list回傳範例：
{
"goals": [
{
"id": "e0a165e6-...",
"title": "打造 AI 企業培訓產品",
"description": "將 Claude CoWork 概念轉化為...",
"type": "general",
"createdTime": "2026-04-01T...",
"courses": [
{ "id": "6833fe94-...", "title": "4 小時課程產品化設計" }
]
}
]
}📚 六、AI Tutor — 課程 (course)
列出與讀取 AI Tutor 課程大綱。
# 列出所有課程
heptabase course list
# 讀取課程大綱（含主題、子主題、學習進度）
heptabase course read <courseId>course read 回傳包含：
courseId、title、overview、expectedOutcometopics[]：每個主題含子主題（subtopics），每個子主題標註學習狀態（notStarted|inProgress|covered）
🎓 七、AI Tutor — 課堂 (lesson)
列出課程中的課堂、讀取課堂計畫、查看對話紀錄。
# 列出某課程的所有課堂
heptabase lesson list <courseId>
# 讀取課堂計畫與產出物
heptabase lesson read <lessonId>
# 讀取課堂對話紀錄（含分頁）
heptabase lesson list-messages <lessonId> --offset 0 --limit 50lesson list-messages 回傳：
{
"lessonId": "...",
"messages": [
{
"id": "...",
"role": "user",
"contentMarkdown": "我想了解如何...",
"createdTime": "...",
"createdBy": "user"
},
{
"id": "...",
"role": "assistant",
"contentMarkdown": "根據你的學習目標...",
"createdTime": "...",
"createdBy": "ai"
}
],
"total": 42,
"hasMore": false
}實戰範例
範例 1：每日知識同步流程
# 1. 確認 CLI 就緒
heptabase start
# 2. 今日日記追加
heptabase journal append 2026-04-23 -c "## 晚間回顧
今天完成了三堂教學，核心收穫是..."
# 3. 將本地筆記匯入為卡片
heptabase note create -f ./teaching_notes.md
# 4. 為新卡片加標籤
heptabase tag add --card-id <剛建立的卡片ID> --tag-name "教學筆記"範例 2：搜尋知識庫中的特定內容
# 搜尋所有關於「問題建模」的卡片
heptabase card list -q "問題建模" --limit 10
# 搜尋所有 PDF 類型的卡片
heptabase card list --card-types pdf --limit 50
# 搜尋最近建立的筆記
heptabase card list --card-types note --sort createdTime --limit 5範例 3：AI Tutor 課程回顧
# 查看所有學習目標
heptabase goal list
# 取得某課程的大綱
heptabase course read 6833fe94-f20b-43b3-801b-ee413f9ea338
# 查看該課程的課堂列表
heptabase lesson list 6833fe94-f20b-43b3-801b-ee413f9ea338
# 讀取特定課堂的對話紀錄
heptabase lesson list-messages <lessonId> --limit 100範例 4：批次匯入多個檔案
# 用 shell 迴圈將資料夾中的所有 .md 檔案匯入為卡片
for file in ./notes/*.md; do
echo "匯入: $file"
heptabase note create -f "$file"
done與 AI Agent 整合
Claude Code / Cursor
在你的 AI Agent 中，可以直接呼叫 CLI 指令來存取知識庫：
「請幫我搜尋知識庫中關於『AI 工作流』的所有卡片」
→ AI 執行：heptabase card list -q "AI 工作流"
「請把這份會議紀錄存入 Heptabase」
→ AI 執行：heptabase note create -f ./meeting.md
「請在今天的日記追加這段反思」
→ AI 執行：heptabase journal append 2026-04-23 -c "..."MCP 整合（進階）
Heptabase 也提供 MCP Server（https://api.heptabase.com/mcp），適用於需要 OAuth 雲端存取的場景。CLI 則是本地優先的方案，不需要網路連線（僅需 App 執行中）。
常見問題
Q：CLI 是否需要網路連線？
A：不需要。CLI 透過本地 HTTP 伺服器（127.0.0.1）與 App 通訊，完全離線運作。
Q：CLI 有 API 限流嗎？
A：目前沒有明確的速率限制，但建議避免高頻呼叫（如每秒數十次）。
Q：可以用 CLI 建立白板嗎？
A：目前不支援。v0.1.0 僅支援 card、note、journal、tag、course、goal、lesson 操作。
Q：journal create 回傳 409 怎麼辦？
A：該日期已有內容。改用 heptabase journal append 追加。
Q：如何重新登入或重設 CLI？
A：到 Settings > AI Features > CLI，關閉再重新啟用即可。
完整指令速查表
| 指令 | 說明 |
|---|---|
heptabase start |
啟動 App 並等待 CLI 就緒 |
heptabase card list [options] |
列出 / 搜尋卡片 |
heptabase card trash |
刪除卡片至回收桶 |
heptabase card restore |
從回收桶還原 |
heptabase note create -c / -f |
建立筆記卡 |
heptabase note read |
讀取筆記（ProseMirror JSON） |
heptabase note save |
覆蓋筆記（需 contentMd5） |
heptabase note append |
追加筆記內容 |
heptabase journal create [-d date] -c / -f |
建立日記 |
heptabase journal read |
讀取日記 |
heptabase journal save |
覆蓋日記（需 contentMd5） |
heptabase journal append |
追加日記內容 |
heptabase tag list [--name-filter] |
列出標籤 |
heptabase tag create --name |
建立標籤 |
heptabase tag cards |
列出標籤下的卡片 |
heptabase tag add --card-id --tag-name |
為卡片加標籤 |
heptabase tag remove --card-id --tag-id |
移除標籤 |
heptabase goal list |
列出 AI Tutor 學習目標 |
heptabase course list |
列出 AI Tutor 課程 |
heptabase course read |
讀取課程大綱 |
heptabase lesson list |
列出課堂 |
heptabase lesson read |
讀取課堂計畫 |
heptabase lesson list-messages |
讀取對話紀錄 |
結語
Heptabase CLI 的推出，代表個人知識管理正式進入「可程式化」時代。你不再只是知識的消費者或整理者，而是可以讓 AI Agent 幫你自動搜尋、自動整理、自動建卡的系統設計者。
👉 你的知識庫，現在是你的 AI 可以直接存取的資料庫。
撰寫：CTO Antigravity | 基於 Heptabase v1.91.0 官方 CLI 實測 | 2026-04-23
