heptabase-cli
Use the local heptabase CLI whenever the user mentions Heptabase or shares an app.heptabase.com URL/deep link. Read and edit notes, journals, tags, and properties; read chats, messages, and files; and work with whiteboard structure and layout through the running desktop app, including sections, connections, mind maps, lint, and schematic screenshots. Also browse AI Tutor goals, courses, and lessons. Do not open Heptabase links in an agent browser unless the user asks.
heptameta · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add heptameta/heptabase-cli-skills --skill heptabase-cli技能说明
name: heptabase-cli description: Use the local heptabase CLI whenever the user mentions Heptabase or shares an app.heptabase.com URL/deep link. Read and edit notes, journals, tags, and properties; read chats, messages, and files; and work with whiteboard structure and layout through the running desktop app, including sections, connections, mind maps, lint, and schematic screenshots. Also browse AI Tutor goals, courses, and lessons. Do not open Heptabase links in an agent browser unless the user asks. allowed-tools: Bash(heptabase *) Bash(jq *) Bash(mktemp *) metadata: heptabase-cli-version-range: "0.6.x"
Prerequisites
- CLI installed from the desktop app. The command is
heptabaseon macOS/Linux; Windows installsheptabase.cmdfor cmd/PowerShell and aheptabaseshim for POSIX shells. - Check version compatibility before use with
heptabase --version. If the installed CLI version is outside this skill's compatibility range (0.6.x), you MUST stop and ask the user to update either the Heptabase desktop app or this skill package before continuing.
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:
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 - Create a note from markdown:
heptabase note create --content "# Title\n\nBody"(marks Created by AI by default; add--no-created-by-aifor human-owned content). - Create today's journal from markdown:
heptabase journal create --content "Body"(marks Created by AI by default; add--no-created-by-aifor human-owned content). - Append markdown to a note:
heptabase note append <cardId> --content "More content". - Edit note content with JSON save: first read
references/card-content-schema.md, then useheptabase note read <cardId>, modify the returned ProseMirror JSON, and save withheptabase note save <cardId> --content-md5 <contentMd5> --content-file <path>. - Work with properties: use
heptabase tag cards <tagId> --include-propertiesto list tagged cards with values, orheptabase card properties <cardIdOrDate>to inspect one card. Before writing, readreferences/property-values.md, inspect definitions withheptabase tag properties <tagId>, then useheptabase card set-property <cardIdOrDate> --property-id <propertyId> --value "Published"for strings/options or--json-value ...for typed JSON values. - Read parsed PDF content: first read
references/pdf-reading.md, then useheptabase pdf metadata <pdfCardId>to discovertotalPages, and read a page range withheptabase pdf read <pdfCardId> --start-page N --end-page N. - Read transcript content: first read
references/transcript-reading.md, then useheptabase audio metadata <audioCardId>orheptabase video metadata <videoCardId>to discovertranscriptStatusanddurationSeconds, and read overlapping transcript entries in a time range withheptabase audio read <audioCardId> --start-seconds 0 --end-seconds 300orheptabase video read <videoCardId> --start-seconds 0 --end-seconds 300. - Read an attached file: first read
references/file-reading.md. If needed, find its ID withheptabase file list --card-id <cardId>, then runmktemp -dandheptabase file export <fileId> --output-dir <scratchDir>. Read the returnedpathwith your native file-reading tool. - Inspect a whiteboard:
heptabase whiteboard read <whiteboardId> --mode structure, thenheptabase whiteboard read-layout <whiteboardId>. - Read chat messages: Copy a chat ID from
whiteboard readoutput, then useheptabase object read chat <chatId> --offset <n> --limit <n>to paginate non-removed messages with their displayed author, timestamp, quoted content, and message content. For a whiteboard chat-messages element, useheptabase object read chatMessagesElement <elementId> --offset <n> --limit <n>. - Check or view whiteboard layout: run
heptabase whiteboard lint <whiteboardId>. For visual review, first readreferences/whiteboard.md, then useheptabase whiteboard screenshot <whiteboardId> --output <existingDirectory>/whiteboard.pngand inspect the returned local path. - Change whiteboard layout or a mind map: first read
references/whiteboard.md; for mind maps, also readreferences/mind-maps.md. Commands with nested or batch input use--input <path|->and canonical JSON.
Heptabase URLs (Deep links)
When the user shares a Heptabase URL (aka. deep link), use the CLI to read it — do NOT open it in a browser if the user does not explicitly ask you to (the app requires authentication and browsers used by agents are typically not logged in).
URL patterns and how to handle them:
- Journal card:
https://app.heptabase.com/<workspaceId>/card/<YYYY-MM-DD>→heptabase journal read <YYYY-MM-DD> - Card by UUID:
https://app.heptabase.com/<workspaceId>/card/<uuid>→ first runheptabase card properties <uuid>to discover the card type, then read its content with the matching command (heptabase note read <uuid>,heptabase pdf metadata <uuid>, etc.). - Whiteboard:
https://app.heptabase.com/<workspaceId>/whiteboard/<uuid>→ runheptabase whiteboard read <uuid> --mode structureandheptabase whiteboard read-layout <uuid>. Readreferences/whiteboard.mdbefore any layout mutation or visual judgment.
The <workspaceId> segment in the URL is not needed by the CLI — extract only the card/whiteboard ID.