目前 CLI 版本：0.6.0

CLI 可以做什麼

任何能存取終端機的 AI 程式開發 Agent 都可以：

建立、閱讀及編輯筆記卡片與日誌
列出及閱讀劃記卡片
依卡片標題搜尋卡片庫
管理標籤
閱讀、建立及編輯白板與版面，包括放置、移動、排列、對齊、縮放、變更顏色與移除物件；建立區塊與連線；以及操作可編輯的心智圖
讀取標籤資料庫結構，以及讀寫每張卡片的屬性值
逐頁讀取 PDF 卡片已解析的文字內容（v0.4.0 新增）
讀取音訊與影片卡片的逐字稿（v0.4.0 新增）
閱讀 AI Tutor 課程、單元與對話紀錄
匯出本機已有的原始 PDF 與媒體檔案
以逐行分頁讀取支援的物件，並重新命名白板、區塊、標籤、對話與媒體卡片

指令結果與請求錯誤以 JSON 回傳。參數解析錯誤（如無效的選項值）可能是純文字。錯誤格式與部分失敗的說明，請參閱下方檢查指令結果。

安裝必要的 Skill

使用 CLI 前，請先安裝官方 Heptabase CLI Skills。

這些 Skills 會教導相容的 AI 程式開發 Agent 安全且可靠地使用 Heptabase CLI。若要讓 CLI 順利搭配 Claude Code、Codex CLI 等 Agent，先安裝 Skill 是必要步驟。請在要求 Agent 操作工作區前完成。

啟用 CLI

CLI 請求需要有效的 Heptabase 訂閱；符合資格、使用不含同步之單一裝置模式的早期使用者例外。不符合條件的帳戶，即使已啟用 CLI，也會收到 403 錯誤。

開啟 Heptabase 桌面版（至少需 v1.91.0）。
前往 Settings → AI Features → CLI 並開啟。

macOS

macOS 會自動安裝 heptabase 指令，可以立即使用。

Linux AppImage

Linux AppImage 請前往 Settings → AI Features → CLI，點擊 Register。啟動器會安裝在 ~/.local/bin/heptabase。開啟新終端機，執行 command -v heptabase 與 heptabase --version 確認。

Windows

Windows 會顯示類似以下的設定提示：
從 System Settings > Environment Variables 將 C:\Users\<you>\.heptabase\bin 加入 PATH，再重新開啟終端機。

最簡單的方式是複製完整訊息，貼給 AI 程式開發 Agent（例如 Claude Code），它可以協助設定 PATH。

確認連接

開啟新終端機，執行 heptabase start 確認正常運作。

重要：只能透過官方 CLI 指令存取 Heptabase 資料

使用 AI Agent 操作 Heptabase 時，請確保它只透過 heptabase CLI 存取資料。

不要要求或允許 Agent 透過本機資料庫檔案、應用程式儲存空間、快取檔案、內部端點或任何非 CLI 方法，直接讀取、寫入或修改 Heptabase 資料。繞過 CLI 可能造成資料損壞、狀態不一致或非預期行為。

如果想執行的操作目前不受 CLI 支援，不要急著採用替代做法。建議先聯絡客服，確認是否支援該操作，並討論最安全的進行方式。

試試你的第一個任務

交付實際任務前，建議先暖身：請 Agent 查看 CLI 說明指令、嘗試一項安全的唯讀操作，再整理可用功能。

可以貼給 Agent 的提示詞範例：

1. 探索 CLI 功能

執行 heptabase -h，再查看每個子指令的說明。整理 Heptabase CLI 的功能，方便後續對話參考。

2. 嘗試讀取

使用 Heptabase CLI 列出我最近編輯的 5 張卡片，顯示標題與最後編輯時間。

3. 嘗試寫入

使用 Heptabase CLI 在今天的日誌附加一行筆記，確認寫入正常。保持簡短且容易辨識，例如「已測試 Heptabase CLI」。

4. 嘗試白板操作

使用 Heptabase CLI 列出我最近編輯的 10 個白板。選一個，讀取語意內容與精確版面，匯出示意截圖，並在不修改任何內容的情況下提出排版建議。

5. 嘗試讀寫標籤屬性

使用 Heptabase CLI 找出我常用的一個標籤（例如 book），列出屬性欄位，再選一張該標籤下的卡片讀取屬性值。接著設定該卡片的一個屬性，例如將「Read?」核取方塊設為 true。

6. 嘗試讀取 PDF 卡片（v0.4.0 新增）

使用 Heptabase CLI 找出我的一張 PDF 卡片，用 pdf metadata 檢查總頁數，再用 pdf read 讀取前 5 頁並說明內容。

對話有了這些背景後，後續請求（如「為今天的會議建立日誌」、「摘要昨天加入的 200 頁 PDF」、「從一小時的 Podcast 找出關於 X 的引言」、「把最新會議筆記加入 Q2 規劃白板」）會更可靠，因為 Agent 已了解可用功能。

指令參考

搜尋卡片

heptabase card list -q <keyword> 搜尋的是儲存的卡片標題，不是內文或語意。如果筆記儲存的標題為空，即使內文包含關鍵字也不會符合。請讀取符合的卡片以取得內容；需要完整結果時，請使用分頁。

閱讀內容

若要取得支援物件的易讀內容，請使用 object read 並指定物件類型與 ID。回傳內容附有行號，並支援 --offset 與 --limit，方便分段閱讀長篇內容。例如：

heptabase object read card <cardId> --offset 0 --limit 100

請使用對應的物件類型，例如劃記使用 highlightElement，日誌使用 journal 並搭配 YYYY-MM-DD 日期。白板請使用 whiteboard read，來源內容則使用 PDF 或音訊／影片專用指令。

若要進行結構化編輯，請讀取原始 ProseMirror 文件：

heptabase note read <cardId> 回傳外層 JSON 物件。其 content 欄位是以 JSON 編碼的 ProseMirror 文件字串，不是巢狀物件。

heptabase note read <cardId> | jq '.content | fromjson'

若要取得純文字檢視：

heptabase note read <cardId> | jq -r '.content | fromjson | .. | objects | .text? // empty'

純文字檢視會遺失資訊，無法保留原始 ProseMirror 結構。

編輯筆記與日誌內容

note save 與 journal save 會以 ProseMirror JSON 取代整份文件。請先讀取最新內容及其 contentMd5，保留結構進行編輯，再於儲存時傳入該雜湊值。筆記範例：

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

如果內容在讀取後已變更，儲存會因衝突被拒絕。請重新讀取，將變更套用至最新文件後再試。不要使用會遺失資訊的純文字輸出取代文件。若只想新增文字，note append 與 journal append 支援 Markdown。

Markdown 卡片提及

type="card" 專指筆記卡片。請依目標物件使用對應的提及類型：

目標	提及類型
筆記卡片	`card`
PDF 卡片	`pdfCard`
圖片卡片	`imageCard`
影片卡片	`videoCard`
音訊卡片	`audioCard`

範例：

<hepta-mention type="videoCard" id="<VIDEO_CARD_ID>">Video title</hepta-mention>

將 type="card" 搭配媒體卡片 ID 使用，會建立筆記卡片提及，可能顯示「Invalid card」。變更 blockId 不會改變目標類型。

heptabase note read <cardId> 只讀取筆記卡片。其他卡片類型請使用對應類型的 object read、類型專用指令（如 video metadata、audio metadata 或 pdf metadata），或 card properties。note read 回傳「Card not found」，本身不代表卡片已被刪除。

劃記卡片

CLI 中的劃記卡片內文為唯讀。CLI 可以列出及閱讀劃記，但無法編輯從 PDF 或 Readwise 擷取的劃記內文。如果自動化流程需要修改後的文字，請建立或更新獨立筆記卡片。這會建立副本，不會修改原始劃記。若要修改原始劃記，請使用 Heptabase 應用程式。

目前也未提供 PDF 劃記的來源對應資訊。CLI 讀取 PDF 劃記時，不會回傳來源 PDF ID、頁碼、劃記區域座標或同等精確的深層連結。沒有針對這些定位資訊的白板範圍匯出；如有需要，目前必須匯出完整帳戶。

提供精確 ID 時，通用卡片指令可以將劃記卡片移至垃圾桶或還原：heptabase card trash <cardId> 與 heptabase card restore <cardId>。這些指令不會編輯劃記內文。

產品內的 AI Agent 不提供移至垃圾桶／刪除工具。這些指令供使用官方 Heptabase CLI 的外部 AI 程式開發 Agent 使用。

清理前

請 Agent 分頁讀取完整候選清單，列出精確卡片 ID、數量與 createdTime 範圍供核准。
逐一將核准的 ID 移至垃圾桶。
遇到任何失敗或不確定結果時應停止。保留來源 PDF 與較舊劃記，並在驗證結果前不要清空垃圾桶。

CLI 沒有 PDF／來源 ID 篩選，也沒有不可分割的批次移至垃圾桶操作。

白板截圖

白板截圖是示意圖。whiteboard screenshot 會匯出簡化的 PNG 供視覺檢查，不會像桌面版完整呈現卡片內文，顯示太小時也可能省略物件標題。使用 AI 協助排版時，請搭配 whiteboard read --mode content 與 whiteboard read-layout。

Inbox

CLI 目前不支援 Inbox。無法列出 Inbox 項目、檢查既有卡片是否在 Inbox，或將卡片加入／移出 Inbox。這些操作請使用 Heptabase 應用程式。

匯出原始檔案

若要讓 Agent 處理原始 PDF、圖片、音訊或影片檔案，請先找到檔案 ID，再透過 CLI 匯出：

heptabase file list --card-id <cardId>
heptabase file export <fileId> --output-dir /absolute/path/to/existing-folder

原始檔案請選擇 purpose: "content" 的檔案；媒體卡片可能另有封面檔案。匯出會回傳 Agent 可讀取的絕對 path。輸出目錄必須已存在。

只能匯出自己工作區中已在本機可用的檔案。此功能不會從雲端下載缺少的檔案，也不能匯出共享工作區的檔案。如果檔案尚未快取，請先在 Heptabase 開啟或同步，再重試。不支援的卡片類型會回傳空的檔案清單。

重新命名物件

使用 object rename 重新命名白板、區塊、標籤、對話，或 PDF、網頁、圖片、影片、音訊卡片。例如：

heptabase object rename whiteboard <whiteboardId> --new-name "Renewable energy research"

請使用對應物件類型，例如 PDF 使用 pdfCard。此指令不能重新命名筆記卡片，也不會編輯資料庫屬性欄位。

檢查指令結果

請求錯誤可能包含 error 字串，或含有 code、message 與 retryable 欄位的 error 物件。重試前請檢查回傳錯誤與復原指引。

白板操作中，收到 HTTP 回應本身不代表變更成功。頂層 status: "failed" 會產生結束代碼 1，但頂層成功的結果仍可能包含個別項目失敗，並以代碼 0 結束。請 Agent 檢查每個項目的結果，再回報整批完成。

標籤資料庫

CLI 可以建立簡單的標籤資料庫，並操作既有資料庫。它可以：

建立簡單的新標籤資料庫（tag create --name）
讀取標籤資料庫的屬性結構（tag properties）
讀取該標籤下任一卡片的屬性值（card properties、tag cards --include-properties）
一次設定卡片的一個屬性值（card set-property）

它無法：

建立巢狀父子標籤關係，或在建立標籤時指定 parentTagId。請先在桌面版建立並整理巢狀結構。
定義、重新命名或刪除屬性欄位。請先在桌面版建立及編輯標籤資料庫結構，再讓 Agent 填入值。
新增、重新命名或刪除 Select／Multi-select 屬性的選項；選項清單也必須先在桌面版設定。如果 Agent 嘗試設定不存在的選項值（例如尚未定義「Reading」選項，就將 Progress 設為「Reading」），CLI 會以明確錯誤拒絕。
依屬性值篩選或查詢卡片；CLI 會回傳完整結果，Agent 可在用戶端自行篩選。

若要讓 Agent 操作結構化資料，最簡單的方式是：先在桌面版／網頁版設定一次標籤、欄位與選項，再讓 Agent 透過 CLI 填入及更新值。

CLI 與 MCP

兩者適用於不同情境，也透過不同途徑存取資料：

MCP（Model Context Protocol）讓相容 AI 助理能在已同步至雲端的 Heptabase 工作區，搜尋、閱讀、建立及更新支援的內容。
CLI 是命令列工具，讓 AI 程式開發 Agent 透過正在執行的桌面版操作 Heptabase。桌面版必須持續執行，CLI 才能連接。

CLI 讀取白板內容時使用正在執行的桌面版已有資料，不會觸發僅在雲端進行的 PDF、網頁或 YouTube 內容處理。已解析頁面或逐字稿請使用 pdf read、audio read 或 video read。CLI 無法取得網頁卡片的完整內文，請使用摘要中提供的來源網址。

CLI 支援詳細白板排版變更，例如移動與縮放物件或編輯心智圖。MCP 可以讀取白板並自動放置支援的既有卡片，但不提供這些詳細排版操作。MCP 也能在相容應用程式中互動顯示卡片；CLI 白板截圖則是示意圖。

疑難排解

Linux AppImage 疑難排解

如果終端機顯示 heptabase: command not found，表示 PATH 有問題。請確認 ~/.local/bin 已加入 PATH，再開啟新終端機。
如果 command -v heptabase 找得到啟動器，但指令回報 Heptabase runtime was not found，表示 PATH 已正常運作。某些 Linux AppImage 安裝環境儲存的註冊資訊，可能仍指向重啟 Heptabase 後已失效的暫時 AppImage 掛載路徑。
此時不要持續修改 PATH。請開啟 Settings → AI Features → CLI，重新註冊 CLI。在問題修正前，可能每次重啟 Heptabase 後都需要重做。

Agent 無法連接

如果 Agent 成功安裝 Skill，卻仍無法註冊或連接 CLI，請檢查 Agent 的沙盒權限。有些 Agent 預設在受限的唯讀沙盒執行，因而無法執行 CLI 或存取工作區外的檔案。

例如，在 Codex 桌面版前往 Settings → Configuration → Sandbox settings，將 Read only 改為 Full access（「Can edit files outside this workspace」）。接著重啟 Heptabase CLI 與 Codex 應用程式，再嘗試連接。

如果做出了有趣的成果或遇到問題，歡迎透過應用程式內客服聯絡我們，我們很樂意聽聽你的經驗。