heptabase-cli

name

heptabase-cli

description

Reads and writes Heptabase through the local `heptabase` CLI: note, journal, and card content as Markdown or ProseMirror JSON under contentMd5 concurrency, typed tag property writes including relations, whiteboard card add/remove, parsed PDF pages, audio and video transcript ranges, local raw file export, and AI Tutor goals, courses, lessons. Use when a task saves, appends, or edits Heptabase content, sets a card property, or pulls a PDF or transcript — "add this to my Heptabase", "update that card's status", "get the transcript".

[HEPTABASE_CLI]

Manage Heptabase knowledge base content through the local CLI; every read and write enters through the heptabase command and returns JSON on stdout for jq parsing or downstream piping.

[01]-[ROUTING]

• [01]-CARD_CONTENT_SCHEMA: mandatory read before any ProseMirror save payload or extension-bearing Markdown.
• [02]-PROPERTY_VALUES: mandatory read before any property write; value formats by type, relation write semantics
• [03]-FILE_READING: file listing and export from PDF and media cards
• [04]-PDF_READING: parsed PDF page metadata and page-range reads
• [05]-TRANSCRIPT_READING: audio and video transcript metadata and time-range reads

[02]-[PREREQUISITES]

• Desktop app installs the CLI: heptabase on macOS/Linux, heptabase.cmd on Windows for cmd/PowerShell beside a heptabase POSIX shim.
• heptabase --version proves the CLI is reachable; a command this skill names but heptabase help does not list halts work rather than being guessed — ask the user to update the desktop app.

[03]-[COMMAND_DISCOVERY]

Run heptabase help for the live top-level command list; each command carries --help for detailed usage:

heptabase help
heptabase note --help
heptabase note create --help

[04]-[TROUBLESHOOTING]

• [DESKTOP_APP_MUST_BE_RUNNING]: Every command reaches a local server in the app, so a closed app fails all; heptabase start launches to readiness.
• [MUTATIONS_ARE_SERIALIZED]: Every mutating command serializes server-side to prevent conflicts; reads run concurrent.
• [REQUEST_BOUNDS]: Oversized request bodies reject, bulk content lands as multiple append passes, never one giant body.

[05]-[BOUNDARIES]

• [CLI_ONLY_ACCESS]: Never reach app data through local database files, app storage, cache files, internal endpoints, or any non-CLI mechanism.
• [UNSUPPORTED_OPERATION]: An operation the CLI omits stops and reports as unsupported.
• [LOCAL_SERVER_SETUP]: This skill never repairs local CLI wiring; ask the user to enable Local CLI Server and CLI install in desktop settings.
• [LOCAL_FILES_ONLY]: heptabase file export reaches only metadata and raw files local to the desktop app, never downloading from cloud storage.
• [BINARY_UPLOAD]: This skill is for JSON/text operations on notes/journals/tags/cards and AI Tutor reads, not file upload or media-processing APIs.
• [WHITEBOARD_MUTATION]: Listing whiteboards and adding, listing, or removing their cards works; creating, renaming, moving, or deleting one does not.
• [PROPERTY_FILTERING]: Reading tag property schemas and values and setting one value on a card works; querying cards by property value does not.