使用 ChatGPT、Codex、Claude 或 Claude Code？ 官方 Heptabase plugin 是最簡單的開始方式，不需要 CLI，請參考在 ChatGPT 與 Codex 中使用 Heptabase 或在 Claude 與 Claude Code 中使用 Heptabase。如果你用的是在終端機裡工作的 coding agent，而且它和 Heptabase 桌面 app 在同一台電腦上，再考慮 CLI。
Heptabase CLI 讓 Claude Code、Codex 等 coding agent 透過桌面 app 操作你的 Heptabase 工作區。目前版本為 CLI 0.10.0，隨桌面版 v1.117.0 推出。
CLI 可以做什麼
建立及閱讀筆記卡片與日誌，也能只修改其中一部分、不必整份重寫，可以加入圖片、影片、音訊與附件
從檔案或網址建立 PDF、圖片、音訊、影片、網頁與 YouTube 卡片，並解析 PDF
逐頁讀取已解析的 PDF、音訊與影片卡片的逐字稿，以及一段日期範圍內的日誌
讀取卡片的劃記與反向連結
用關鍵字或語意搜尋，以及依類型、標籤或白板列出卡片
建立及編輯標籤資料庫、查詢其中的卡片、設定屬性值、替卡片加上或移除標籤、建立標籤群組，以及移動標籤
把卡片移到垃圾桶及還原
讀取及整理 Inbox
讀取及設定 Space Instructions
閱讀、建立及編輯白板：放置、移動、排列、對齊、縮放、變更顏色與移除物件；建立區塊、連線與心智圖；檢查排版並匯出示意截圖
閱讀 AI Tutor 課程、單元與對話紀錄
匯出電腦上已有的原始檔案，以及重新命名白板、區塊、標籤、對話與媒體卡片
安裝必要的 Skill
使用 CLI 前，請先安裝官方 Heptabase CLI Skills。
Skill 讓 coding agent 知道什麼時候該用 CLI，以及怎麼設定。從 CLI 0.10.0 開始，在 Heptabase 裡工作的詳細指南內建在 CLI 裡，稱為 system manual，Skill 會引導 agent 先讀它（heptabase system-manual read concepts）。更新 Heptabase 時 system manual 會跟著更新，所以不需要每次更新 Heptabase 都更新 Skill。
如果你在 CLI 0.10.0 之前安裝過 Skills，請現在更新。舊版本用到的部分指令，在 CLI 0.10.0 已經被取代。
啟用 CLI
使用 CLI 需要有效的 Heptabase 訂閱。使用單裝置模式且未開啟同步的早期使用者例外。其他帳號即使開啟 CLI，也會收到 403 錯誤。
開啟 Heptabase 桌面 app，並更新到最新版本。
前往 Settings → AI Features → CLI 並開啟。
macOS
heptabase 指令會自動安裝，可以直接使用。
Linux AppImage
在 Settings → AI Features → CLI 點選 Register。指令會安裝在 ~/.local/bin/heptabase。開啟新的終端機，執行 command -v heptabase 與 heptabase --version 確認。
Windows
你會看到類似這樣的設定提示：
Add C:\Users\<you>\.heptabase\bin to your PATH from System Settings > Environment Variables, then reopen your terminal.
最簡單的做法是把這段訊息貼給你的 coding agent，讓它幫你設定 PATH。
確認連線
開啟新的終端機，執行 heptabase start。
只使用官方 CLI 指令
請確認 agent 只透過 heptabase CLI 存取你的資料。不要讓它讀取或修改 Heptabase 的本機資料庫、app 儲存空間、快取檔案或內部端點，否則可能造成資料損毀。
如果 agent 發現 CLI 做不到你需要的事，不要讓它自己找替代做法。請先聯絡客服，我們會協助你找到安全的方式。
試試第一批任務
讓 agent 處理正式工作前，先讓它熟悉 CLI，並試幾個安全的操作。把以下提示貼給你的 agent：
探索：「用
heptabase system-manual read讀 Heptabase CLI 的 system manual，從 concepts 頁開始，再執行heptabase -h，整理 Heptabase CLI 能做哪些事。」讀取：「用 Heptabase CLI 列出我最近編輯的 5 張卡片，顯示標題和最後編輯時間。」
寫入：「用 Heptabase CLI 在今天的日誌加一行簡短的文字，例如『測試 Heptabase CLI』。」
存下 PDF：「用 Heptabase CLI 把這篇論文存成 PDF 卡片，解析後整理前 5 頁的重點：https://arxiv.org/pdf/1706.03762」
白板：「用 Heptabase CLI 列出我最近編輯的 10 個白板。挑一個讀取內容和版面，匯出示意截圖，並在不做任何修改的情況下提出排版建議。」
標籤資料庫：「用 Heptabase CLI 找一個我常用的標籤，例如
book，列出它的屬性，再讀取其中一張卡片的屬性值。」
等 agent 熟悉 CLI 之後，「幫我整理昨天加入的 PDF」或「把最新的會議筆記放到 Q2 規劃白板」這類要求會穩定許多。
指令參考
搜尋
heptabase search keyword "<query>" 用精確的關鍵字或短語，搜尋卡片、日誌、白板、區塊與標籤的標題和內容。PDF、影片與音訊卡片只比對標題。heptabase search semantic "<query>" 依語意搜尋，用詞不同也找得到。兩者都會回傳簡短摘錄，需要完整內容時請用 object read 讀取。
heptabase card list -q <keyword> 只比對卡片標題。
讀取內容
object read 會回傳含行號的內容，用 --offset 與 --limit 可以分段讀取長篇內容：
heptabase object read card <cardId> --offset 0 --limit 100
請使用對應的物件類型，例如劃記用 highlightElement，日誌用 journal 加上 YYYY-MM-DD 日期。白板請用 whiteboard read，PDF 頁面與逐字稿請用 pdf、audio 與 video 指令。若要讀取一段日期範圍內的日誌，請用 journal read-range --start-date <YYYY-MM-DD> --end-date <YYYY-MM-DD>，每次最多 185 天。
編輯筆記與日誌
note create 用 Markdown 建立筆記卡片。note edit 與 journal edit 用 Markdown 修改筆記或日誌的一部分，不必整份重寫：取代指定的文字、在最後加入內容，或改寫整份內容。同一份筆記的所有修改請放在同一次呼叫裡，這些修改會一起儲存，有一處失敗就都不儲存。那天還沒有日誌時，journal edit 會一併建立。修改前請先用 object read card <cardId> 或 object read journal <YYYY-MM-DD> 讀取目前的內容。CLI 0.10.0 起，這兩個指令取代了 note append、journal create 與 journal append。
Markdown 無法表達的修改，才用 note save 與 journal save，它們會用 ProseMirror JSON 取代整份文件。請先讀取最新內容與 contentMd5，在保留結構的前提下編輯文件，儲存時再帶上這個 hash：
heptabase note read <cardId> > note.json
jq -r .content note.json > content.json
編輯 content.json 後儲存：
heptabase note save <cardId> --content-md5 "$(jq -r .contentMd5 note.json)" --content-file content.json
如果讀取後筆記又被修改過，儲存會被拒絕。請重新讀取，把修改套用到最新版本。
加入檔案與媒體
先從電腦或網址匯入檔案，再用對應類型的指令建立卡片：
heptabase file import ./paper.pdf
heptabase pdf create --file-uri <fileUri>
匯入結果會告訴你檔案類型：pdf、image、audio、video 或 file。檔案最大 2,000 MB。若要存下網頁或 YouTube 影片，請用 heptabase web create --url <url> 或 heptabase video create --url <url>。若要在筆記或日誌中放入匯入的圖片、影片、音訊或附件，請在內容中使用它的 file URI。
Markdown 中的卡片提及
type="card" 只代表筆記卡片。請使用與目標相符的提及類型：
目標 | 提及類型 |
筆記卡片 |
|
PDF 卡片 |
|
圖片卡片 |
|
影片卡片 |
|
音訊卡片 |
|
<hepta-mention type="videoCard" id="<VIDEO_CARD_ID>">Video title</hepta-mention>
對媒體卡片的 ID 使用 type="card"，會產生顯示「Invalid card」的錯誤提及。
note read 只能讀取筆記卡片。其他類型的卡片，請用 object read 搭配對應類型，或該類型專屬的指令，例如 pdf metadata。note read 回傳「Card not found」不代表卡片已被刪除。
劃記
card highlights <cardId> 會讀取筆記卡片或 PDF 卡片上的劃記與劃記筆記。劃記的文字無法透過 CLI 編輯；如果需要修改後的版本，請另外建立筆記卡片。
移到垃圾桶與還原
card trash <cardIds...> 會把卡片移到垃圾桶，card restore <cardIds...> 會還原卡片。移到垃圾桶的卡片仍會留在原本的白板上，所以還原後會回到原位。移到垃圾桶的結果會列出這些位置；如果不想保留，可以用 whiteboard remove-objects 移除。日誌無法移到垃圾桶。
如果卡片是 agent 自己挑出來的，請先讓它列出清單，等你確認後再移到垃圾桶。
白板截圖
whiteboard screenshot 會匯出簡化的 PNG，用來檢查排版。截圖不會像 app 一樣顯示卡片內容，太小的標題也可能被省略。排版時請搭配 whiteboard read --mode content 與 whiteboard read-layout 使用。
Inbox
inbox list 列出 Inbox 裡的項目：你加入的卡片和訊息，以及提及、回覆、引用與邀請。inbox add 把卡片或日誌加入 Inbox，可以用 --remind-date 指定提醒日期。inbox update 把項目標成完成、已讀或未讀，或設定、清除提醒日期。inbox remove 把你加入的卡片和訊息從 Inbox 移除，卡片和訊息本身不會被刪除；提及、回覆、引用與邀請只能標成完成。
把卡片標成完成不代表已經歸檔。若要整理它，請先讓 agent 把它放到白板上或加上標籤。
Space Instructions
Space Instructions 是你為 AI 在這個空間怎麼工作所訂的規則。space-instructions read 會讀取這些規則，system manual 會要 agent 在每個 session 開始時先讀取並遵守。space-instructions set <cardId> 會把一張既有的筆記卡片設為 Space Instructions。若要新增規則，請用 note edit 編輯那張卡片。
匯出原始檔案
若要把原始的 PDF、圖片、音訊或影片檔交給 agent，請先找到檔案 ID 再匯出：
heptabase file list --card-id <cardId>
heptabase file export <fileId> --output-dir /absolute/path/to/existing-folder
請選擇 purpose: "content" 的檔案；媒體卡片可能還有封面檔。輸出資料夾必須已經存在。只能匯出你自己工作區中、已經在電腦上的檔案。如果檔案不在電腦上，請先在 Heptabase 開啟或同步它。
重新命名物件
object rename 可以重新命名白板、區塊、標籤、對話，以及 PDF、網頁、圖片、影片、音訊卡片：
heptabase object rename whiteboard <whiteboardId> --new-name "Renewable energy research"
若要重新命名筆記卡片，請編輯它的第一個標題。
檢查指令結果
指令結果與請求錯誤都以 JSON 回傳。錯誤會是一個 error 字串，或包含 code、message 與 retryable 的 error 物件。重試前請先查看錯誤內容與處理建議。
批次指令（例如白板編輯）即使整體成功，結果中仍可能有失敗的項目。請讓 agent 檢查每一個項目後，再回報批次已完成。
標籤資料庫
CLI 可以建立及編輯標籤資料庫：
建立標籤資料庫（
tag create），再新增屬性、選項與檢視（tag edit）讀取屬性（
tag properties），並用篩選與排序條件查詢卡片（tag query）讀取及設定卡片的屬性值（
card properties、card set-property）建立標籤群組（
tag create-group），以及把標籤移到另一個標籤底下或移進群組（tag move）替卡片加上或移除標籤（
tag add、tag remove）
新標籤會建立在最上層。若要放到另一個標籤底下，請建立後再用 tag move 移動。
CLI 與 MCP
兩者都能讓 AI 操作你的 Heptabase 工作區，能做的事也大致相同。差別在 agent 在哪裡執行：
MCP 透過 Heptabase 的伺服器連線，可以在 ChatGPT、Claude 等聊天 app 和 coding agent 中使用，不需要安裝任何東西。編輯白板等少數操作需要開著 Heptabase 桌面 app 或網頁版。在 ChatGPT、Claude、Codex，以及 Claude 桌面 app 裡的 Claude Code 中，MCP 還能直接在對話裡打開白板。請參考 Heptabase MCP。
CLI 在你的電腦上透過 Heptabase 桌面 app 執行，桌面 app 必須開著。適合在終端機裡工作的 coding agent，也能讀取 AI Tutor 課程，以及匯出電腦上的檔案。
疑難排解
Linux AppImage
如果終端機顯示
heptabase: command not found，請確認~/.local/bin在 PATH 中，再開啟新的終端機。如果
command -v heptabase找得到指令，但執行時顯示Heptabase runtime was not found，代表 PATH 沒有問題。儲存的註冊資訊可能指向 Heptabase 重新啟動後就不存在的 AppImage 路徑。請開啟 Settings → AI Features → CLI 重新註冊。在我們修正之前，每次重新啟動後可能都需要再註冊一次。
Agent 連不上 CLI
如果 agent 已經裝好 Skill，卻仍無法連上 CLI，請檢查它的 sandbox 設定。有些 agent 預設在唯讀的 sandbox 中執行，會擋住 CLI。
以 Codex 桌面 app 為例，請前往 Settings → Configuration → Sandbox settings，把 Read only 改成 Full access，然後重新啟動 Heptabase 與 Codex app，再試一次。
如果你做出了有趣的應用，或遇到任何問題，歡迎透過 app 內的客服告訴我們。