# Heptabase CLI > Interact with Heptabase using the CLI to manage knowledge base content, search cards, edit properties, read parsed PDF and media transcript content, export local files, manage whiteboard cards, and browse AI Tutor goals, courses, and lessons. Use when this capability is needed. - Skill: `tomevault-io/heptabase-cli` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/heptabase-cli` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/heptabase-cli/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/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.4.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: ```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 ` --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 "" --limit 20` - **Create a note from markdown:** `heptabase note create --content "# Title\n\nBody"`. - **Append markdown to a note:** `heptabase note append --content "More content"`. - **Edit note content with JSON save:** first read `references/card-content-schema.md`, then use `heptabase note read `, modify the returned ProseMirror JSON, and save with `heptabase note save --content-md5 --content-file `. - **List tag properties:** `heptabase tag properties ` - **List cards with property values:** `heptabase tag cards --include-properties` - **Read card properties:** `heptabase card properties ` - **Set card property:** first read `references/property-values.md`, then use `heptabase card set-property --property-id --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 ` to discover `totalPages`, and read a page range with `heptabase pdf read --start-page N --end-page N`. - **Read transcript content:** first read `references/transcript-reading.md`, then use `heptabase audio metadata ` or `heptabase video metadata ` to discover `transcriptStatus` and `durationSeconds`, and read overlapping transcript entries in a time range with `heptabase audio read --start-seconds 0 --end-seconds 300` or `heptabase video read --start-seconds 0 --end-seconds 300`. - **Read a file from a PDF/media card:** first read `references/file-reading.md`, then use `heptabase file list --card-id ` to find the right file `id`, run `mktemp -d`, and pass the returned directory path to `heptabase file export --output-dir `. Read the returned `path` with your native file-reading tool. - **Read a file by `fileId`:** first read `references/file-reading.md`, then run `mktemp -d` and pass the returned directory path to `heptabase file export --output-dir `. Read the returned `path` with your native file-reading tool. - **List cards on a whiteboard:** `heptabase whiteboard cards ` - **Add a card to a whiteboard:** `heptabase whiteboard add-card --whiteboard-id --card-id ` ## Note and journal card content editing Use `create` / `append` with Markdown for ordinary writing. Before calling `heptabase note save` / `heptabase journal save` with ProseMirror JSON, you MUST read `references/card-content-schema.md`. Also read it before generating Markdown that uses Heptabase-specific extensions such as card mentions, whiteboard mentions, dates, videos, math, or toggle/todo lists. ## Property editing Before setting a property value, you MUST read `references/property-values.md` and inspect the target property with `heptabase card properties ` and/or `heptabase tag properties `. Property formats vary by type, and relation writes replace the full relation value. For relation properties, use `heptabase tag properties ` to get the property definition's `relationTargetTagId`, then list valid related cards before writing. ## File reading Before reading/listing files or exporting a file, you MUST read `references/file-reading.md`. ## PDF reading Before reading parsed PDF content, you MUST read `references/pdf-reading.md`. ## Transcript reading Before reading parsed media transcripts, you MUST read `references/transcript-reading.md`. ## All output is JSON Every command prints JSON to stdout. You can parse it with `jq` or pipe it to other tools. ## 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. - **Codex sandbox may block the local CLI server.** If Heptabase starts but Codex says the CLI server is not ready, read `references/codex-sandbox.md`; retry `heptabase` commands outside the sandbox when Codex supports escalation. - **Mutations are serialized.** Write operations (create, save, append, trash, restore, tag add/remove, card set-property, file export, whiteboard add-card/remove-card) 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. ## 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. - **File export is local-file-only.** `heptabase file export` works only when the file metadata and raw file are already available locally in the desktop app. It does not download missing files from cloud storage. - **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 creation/edit/delete not supported yet.** You can list whiteboards and add, list, or remove cards on them, but you can't create, rename, move, or delete whiteboards. - **Property filtering not supported yet.** You can read tag property schemas, read property values, and set one property value on a card, but you can't query cards by property value. ## 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. --- > Source: [heptameta/heptabase-cli-skills](https://github.com/heptameta/heptabase-cli-skills) — distributed by [TomeVault](https://tomevault.io).