heptabase-CLI

\[！重要\] 此项目已弃用；截至2026年4月22日，Heptabase发布了官方CLI；阅读更多 更新日志

Heptabase命令行界面

CLI用于您的个人Heptabase知识库。在终端上搜索白板、阅读卡片/日记/PDF和写笔记。

安装

选择一个：

选项1:Homebrew（建议在macOS上使用）

brew tap madeyexz/tap
brew install madeyexz/tap/heptabase-cli
heptabase --help

选项2：独立二进制

安装后，使用 heptabase 对于所有命令。

当前版本的二进制目标：macOS arm64。 如果你在另一个平台上，请使用 bunx 或者从源代码构建。

mkdir -p ~/.local/bin
curl -L https://github.com/madeyexz/heptabase-cli/releases/latest/download/heptabase -o ~/.local/bin/heptabase
chmod +x ~/.local/bin/heptabase
~/.local/bin/heptabase --help

如果 ~/.local/bin 不在你的 PATH，添加它：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

可选的系统范围安装：

curl -L https://github.com/madeyexz/heptabase-cli/releases/latest/download/heptabase -o heptabase
chmod +x heptabase
sudo mv heptabase /usr/local/bin/

选项3： bunx （无需安装，需要 包子)

bunx heptabase-cli --help

代理设置

对于代理，更喜欢安装 heptabase 上 PATH.

如果您使用AI代理（Claude Code、Codex等），请安装Heptabase 代理技能:

npx skills add madeyexz/heptabase-cli

代理命令约定：使用 heptabase ... （不是 bunx heptabase-cli ...).

身份验证（首次运行）

运行任何命令（以下示例）。第一次运行将打开Heptabase OAuth浏览器。

• 令牌缓存在 ~/.mcp-auth/
• 令牌自动刷新
• 使用重置登录 rm -rf ~/.mcp-auth/

用法

以下示例使用已安装的二进制文件 heptabase. 如果使用无安装模式，请更换 heptabase 和 bunx heptabase-cli.

# Search
heptabase search-whiteboards --keywords "project"
heptabase semantic-search-objects --queries "machine learning" --result-object-types card

# Read
heptabase get-object --object-id  --object-type card
heptabase get-journal-range --start-date 2026-01-01 --end-date 2026-02-21

# Write
heptabase save-to-note-card --content "# Title\n\nBody text"
heptabase append-to-journal --content "Some entry"

列出所有命令：

heptabase --help
heptabase  --help

支持的输出格式(--output): text （默认）， json, markdown, raw.

命令

• search-whiteboards
• semantic-search-objects
• get-object
• get-whiteboard-with-objects
• get-journal-range
• save-to-note-card
• append-to-journal
• search-pdf-content
• get-pdf-pages

故障排除

• command not found: heptabase：使用 bunx heptabase-cli ... 或确保 ~/.local/bin （或 /usr/local/bin)在你的 PATH.
• 浏览器未打开OAuth：从终端复制登录URL并手动打开。
• 需要重新验证： rm -rf ~/.mcp-auth/ 并再次运行命令。

开发（高级）

需要 和 包子.

npx mcp-remote@latest https://api.heptabase.com/mcp --transport http-only

npx mcporter@latest generate-cli \
  --command 'npx -y mcp-remote@latest https://api.heptabase.com/mcp --transport http-only' \
  --output ./heptabase-cli.ts \
  --compile ./heptabase \
  --description "Heptabase knowledge base CLI"

更多

• Heptabase MCP文档：https://support.heptabase.com/en/articles/12679581-how-to-use-heptabase-mcp