Back to Details

heptabase-cli

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Prerequisites

前置条件

  • CLI installed from the desktop app. The command is 
    heptabase
    on macOS/Linux; Windows installs 
    heptabase.cmd
    for cmd/PowerShell and a 
    heptabase
    shim for POSIX shells.
  • Check version compatibility before use with 
    heptabase --version
    . If the installed CLI version is outside this skill's compatibility range (
    0.1.x
    ), you MUST stop and ask the user to update either the Heptabase desktop app or this skill package before continuing.
  • 从桌面应用安装CLI。在macOS/Linux上命令为
    heptabase
    ；Windows系统会为cmd/PowerShell安装
    heptabase.cmd
    ，并为POSIX shell安装
    heptabase
    垫片。
  • 使用前通过
    heptabase --version
    检查版本兼容性。如果已安装的CLI版本不在本技能的兼容范围（
    0.1.x
    ）内，必须停止操作并要求用户更新Heptabase桌面应用或本技能包后再继续。

Command discovery

命令探索

Run 
heptabase help
to see all available top-level commands. This is always up to date. Each command supports 
--help
for detailed usage:
bash
heptabase help
heptabase note --help
heptabase note create --help
运行
heptabase help
查看所有可用的顶级命令，该信息始终是最新的。每个命令都支持
--help
查看详细用法：
bash
heptabase help
heptabase note --help
heptabase note create --help

Common recipes

常用操作示例

Use these as quick recipes for frequent requests. For less common flags or if a command fails, run 
heptabase help
or 
<command> --help
to discover the correct syntax.
  • Recent cards: 
    heptabase card list --sort createdTime --direction descending --limit 20
  • Today's journal: 
    heptabase journal read $(date +%Y-%m-%d)
  • Search cards by keyword: 
    heptabase card list -q "<keyword>" --limit 20
将这些作为常见请求的快速操作指南。对于不常用的参数或命令执行失败时，运行
heptabase help
或
<command> --help
来查看正确的语法。
  • 最近的卡片： 
    heptabase card list --sort createdTime --direction descending --limit 20
  • 今日日志： 
    heptabase journal read $(date +%Y-%m-%d)
  • 按关键词搜索卡片： 
    heptabase card list -q "<keyword>" --limit 20

All output is JSON

所有输出均为JSON格式

Every command prints JSON to stdout. You can parse it with 
jq
or pipe it to other tools.
每个命令都会向标准输出打印JSON内容。你可以使用
jq
解析它，或者将其管道传输到其他工具。

Troubleshooting

故障排除

  • Desktop app must be running. The CLI communicates with a local server inside the app. If the app is closed, all commands fail. Run 
    heptabase start
    to launch and wait for readiness.
  • Mutations are serialized. Write operations (create, save, append, trash, tag add/remove) run one at a time to prevent conflicts. Reads are concurrent.
  • Request body size limit. The server rejects request bodies larger than 1 MB.
  • Request timeout. The server times out requests that take longer than 10 seconds to send their body.
  • 必须运行桌面应用。 CLI与应用内的本地服务器通信。如果应用关闭，所有命令都会执行失败。运行
    heptabase start
    启动应用并等待其就绪。
  • 变更操作已序列化。 写入操作（创建、保存、追加、删除、添加/移除标签）会逐个执行以避免冲突。读取操作支持并发。
  • 请求体大小限制。 服务器会拒绝超过1 MB的请求体。
  • 请求超时。 如果请求体发送时间超过10秒，服务器会超时终止该请求。

Known limitations

已知限制

  • Auto-enabling local server/CLI install not supported. If the local CLI server is disabled or CLI wiring is missing, the skill cannot repair it by itself; ask the user to enable Local CLI Server and CLI install from desktop settings first.
  • Binary/media upload workflows not supported. This skill is for JSON/text operations on notes/journals/tags/cards and AI Tutor reads, not file upload or media-processing APIs.
  • Whiteboard commands not supported yet. You can't CRUD whiteboards or place cards on whiteboards.
  • File reading not supported yet. You can't read files (e.g., image, video) with 
    fileId
    .
  • PDF card reading not supported yet. You can't read pdf card or its parsed content.
  • 不支持自动启用本地服务器/安装CLI。 如果本地CLI服务器已禁用或CLI配置缺失，本技能无法自行修复；请先要求用户从桌面设置中启用Local CLI Server并安装CLI。
  • 不支持二进制/媒体文件上传流程。 本技能仅用于对笔记、日志、标签、卡片进行JSON/文本操作，以及读取AI Tutor内容，不涉及文件上传或媒体处理API。
  • 暂不支持白板命令。 无法对白板进行增删改查（CRUD）操作，也无法在白板上放置卡片。
  • 暂不支持文件读取。 无法通过
    fileId
    读取文件（如图片、视频）。
  • 暂不支持PDF卡片读取。 无法读取PDF卡片或其解析后的内容。

Warnings

注意事项

  • Use the CLI as the only data access path. Never directly read, write, or modify Heptabase app data through local database files, app storage, cache files, internal endpoints, or any other non-CLI mechanism. If the CLI does not support the requested operation, stop and report that it is not supported.
  • 仅通过CLI访问数据。 切勿通过本地数据库文件、应用存储、缓存文件、内部端点或任何其他非CLI机制直接读取、写入或修改Heptabase应用数据。如果CLI不支持请求的操作，请停止操作并告知用户该操作不被支持。