heptabase-cli

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.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-ai for human-owned content).
• Create today's journal from markdown: heptabase journal create --content "Body" (marks Created by AI by default; add --no-created-by-ai for 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 use heptabase note read <cardId>, modify the returned ProseMirror JSON, and save with heptabase note save <cardId> --content-md5 <contentMd5> --content-file <path>.
• Work with properties: use heptabase tag cards <tagId> --include-properties to list tagged cards with values, or heptabase card properties <cardIdOrDate> to inspect one card. Before writing, read references/property-values.md, inspect definitions with heptabase tag properties <tagId>, then use heptabase 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 use heptabase pdf metadata <pdfCardId> to discover totalPages, and read a page range with heptabase pdf read <pdfCardId> --start-page N --end-page N.
• Read transcript content: first read references/transcript-reading.md, then use heptabase audio metadata <audioCardId> or heptabase video metadata <videoCardId> to discover transcriptStatus and durationSeconds, and read overlapping transcript entries in a time range with heptabase audio read <audioCardId> --start-seconds 0 --end-seconds 300 or heptabase video read <videoCardId> --start-seconds 0 --end-seconds 300.
• Read an attached file: first read references/file-reading.md. If needed, find its ID with heptabase file list --card-id <cardId>, then run mktemp -d and heptabase file export <fileId> --output-dir <scratchDir>. Read the returned path with your native file-reading tool.
• Inspect a whiteboard: heptabase whiteboard read <whiteboardId> --mode structure, then heptabase whiteboard read-layout <whiteboardId>.
• Read chat messages: Copy a chat ID from whiteboard read output, then use heptabase 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, use heptabase object read chatMessagesElement <elementId> --offset <n> --limit <n>.
• Check or view whiteboard layout: run heptabase whiteboard lint <whiteboardId>. For visual review, first read references/whiteboard.md, then use heptabase whiteboard screenshot <whiteboardId> --output <existingDirectory>/whiteboard.png and inspect the returned local path.
• Change whiteboard layout or a mind map: first read references/whiteboard.md; for mind maps, also read references/mind-maps.md. Commands with nested or batch input use --input <path|-> and canonical JSON.