Current CLI version: 0.6.0

​

Any AI coding agent with access to your terminal can:

Command results and request errors are returned as JSON. Argument-parsing errors, such as invalid option values, may be plain text. See Checking command results below for error formats and partial failures.

​

Install the official Heptabase CLI skills before you use the CLI.

These skills teach compatible AI coding agents how to use the Heptabase CLI safely and reliably. Installing the skill first is a required step for the CLI to work smoothly with agents like Claude Code and Codex CLI. Do this before asking your agent to work with your space.

​

CLI requests require an active Heptabase subscription, with an exception for eligible early adopters using single-device mode without sync. Accounts that do not meet these conditions receive a 403 error even when the CLI is enabled.

macOS

On macOS, the heptabase command is installed automatically — you can start using it right away.

​

Linux AppImage

On Linux AppImage, go to Settings → AI Features → CLI and click Register. The launcher is installed at ~/.local/bin/heptabase. Open a new terminal, then run command -v heptabase and heptabase --version to verify it.

​

Windows

On Windows, you'll see a setup hint like:
​Add C:\Users\<you>\.heptabase\bin to your PATH from System Settings > Environment Variables, then reopen your terminal.

​

The easiest way to handle this is to copy the exact message and paste it into your AI coding agent (e.g., Claude Code) — it can set up the PATH for you.

​

Verify the connection

Open a new terminal and run heptabase start to confirm everything works.

​

Before giving your agent real tasks, we recommend a quick warm-up round: have it walk through the CLI's help commands, try one safe read-only action, and summarize what's possible.

​

Example prompts you can paste into your agent:

​

1. Explore the CLI surface

Run heptabase -h and then the help for each subcommand. Summarize what the Heptabase CLI can do, so we can reference it in follow-up messages.

​

2. Try a read

Use the Heptabase CLI to list my 5 most recently edited cards. Show the titles and last edited times.

​

3. Try a write

Use the Heptabase CLI to append a one-line note to today's journal entry to confirm writes are working. Keep it short and easy to spot, like "Tested the Heptabase CLI".

​

4. Try a whiteboard operation

Use the Heptabase CLI to list my 10 most recently edited whiteboards. Pick one, read its semantic content and exact layout, export a schematic screenshot, and suggest layout improvements without changing anything.

​

5. Try reading and writing tag properties

Use the Heptabase CLI to find a tag I use a lot (for example, book), list its property columns, and then pick one card under that tag and read its property values. After that, set one property on that card — for example, mark its "Read?" checkbox to true.

​

6. Try reading a PDF card (new in v0.4.0)

Use the Heptabase CLI to find one of my PDF cards, check its total page count with pdf metadata, then read the first 5 pages with pdf read and tell me what it's about.

​

Once this context is in the conversation, later requests — "create a journal entry about today's meeting", "summarize the 200-page PDF I added yesterday", "pull the quote about X from this hour-long podcast", "add my latest meeting note to the Q2 planning whiteboard" — will land much more reliably, because the agent already knows the surface area.

​

heptabase card list -q <keyword> searches stored card titles, not body text or semantic meaning. Notes with an empty stored title will not match a keyword even if the text appears in their content. Read the matching cards to retrieve their content, and use pagination when you need the full result set.

​

For a readable view of a supported object, use object read with the object’s type and ID. It returns content with line numbers and supports --offset and --limit for reading long content in parts. For example:

Use the matching object type, such as highlightElement for a highlight or journal with a YYYY-MM-DD date. Use whiteboard read for a whiteboard, and the dedicated PDF or audio/video commands for source content.

​

For structured editing, read the original ProseMirror document:

​

heptabase note read <cardId> returns an outer JSON object. Its content field is a JSON-encoded ProseMirror document string, not a nested object.

For a plain-text view:

The plain-text view is lossy and does not preserve the original ProseMirror structure.

​

note save and journal save replace the entire document with ProseMirror JSON. First read the latest content and its contentMd5, edit the document while preserving its structure, then pass that hash when saving. For a note:

Edit content.json, then save it with the hash from the same read:

If the content has changed since you read it, the save is rejected with a conflict. Read it again and apply your changes to the latest document before retrying. Do not use the lossy plain-text output as the replacement document. If you only want to add text, note append and journal append accept Markdown.

​

type="card" refers specifically to a note card. Use the matching mention type for the target object:

​

Example:

Using type="card" with a media-card ID creates a note-card mention and may display “Invalid card.” Changing blockId does not change the target type.

​

heptabase note read <cardId> only reads note cards. For another card type, use object read with the matching type, its type-specific command (such as video metadata, audio metadata, or pdf metadata), or card properties. A “Card not found” response from note read does not by itself mean that the card was deleted.

​

Highlight card body text is read-only in the CLI. The CLI can list and read highlights, but it cannot edit the captured body text of a PDF or Readwise highlight. If you need revised text in an automated workflow, create or update a separate note card. This creates a copy and does not modify the original highlight. Use the Heptabase app to modify the original highlight.

​

Source mapping for PDF highlights is also not currently exposed. When the CLI reads a PDF highlight, it does not return the source PDF ID, page number, highlighted region coordinates, or an equivalent precise deep link. There is no whiteboard-scoped export for these anchors; a full-account export is currently required if you need them.

​

Generic card-level commands can move a highlight card to Trash or restore it when given its exact ID: heptabase card trash <cardId> and heptabase card restore <cardId>. These commands do not edit the highlight body.

​

The in-product AI Agent does not expose a trash/delete tool. These commands are for external AI coding agents using the official Heptabase CLI.

​

Before cleanup

The CLI has no PDF/source-ID filter or atomic bulk-trash operation.

​

Whiteboard screenshots are schematic. whiteboard screenshot exports a simplified PNG for visual review. It does not fully render card body content like the desktop app, and object titles may be omitted when rendered too small. For AI-assisted layout, combine it with whiteboard read --mode content and whiteboard read-layout.

​

Inbox is not currently supported by the CLI. The CLI cannot list Inbox items, check whether an existing card is in Inbox, or add or remove Inbox membership. Use the Heptabase app for these operations.

​

To let your agent work with an original PDF, image, audio, or video file, first find its file ID, then export it through the CLI:

Choose the file with purpose: "content" for the original file; a media card may also have a cover file. The export returns an absolute path that your agent can read. The output directory must already exist.

​

Export works only for files in your own workspace that are already available locally. It does not download missing files from the cloud or export files from a shared workspace. If the file is not cached, open or sync it in Heptabase first, then retry. Unsupported card types return an empty file list.

​

Use object rename to rename a whiteboard, section, tag, chat, or PDF, web, image, video, or audio card. For example:

Use the matching object type, such as pdfCard for a PDF. This command does not rename note cards or edit database property columns.

​

Request errors may contain an error string, or an error object with code, message, and retryable fields. Check the returned error and recovery guidance before retrying.

​

For whiteboard operations, an HTTP response alone does not mean the change succeeded. A top-level status: "failed" produces exit code 1, but a successful top-level result can still contain failed individual items and exit with code 0. Have your agent inspect every item result before reporting that a batch is complete.

​

The CLI can create simple tag databases and work with existing ones. It can:

It cannot:

If you want your agent to work with structured data, the easiest pattern is: set up the tag and its columns / options once in the desktop/web app, then let the agent populate and update values via the CLI.

​

They serve different use cases and reach your data through different paths:

CLI whiteboard content reads use data available in the running desktop app; they do not trigger cloud-only PDF, web, or YouTube content processing. Use pdf read, audio read, or video read for parsed pages or transcripts. Full web card body content is not available through the CLI; use the source URL provided in its summary.

​

The CLI supports detailed whiteboard layout changes, such as moving and resizing objects or editing mind maps. MCP can read whiteboards and automatically place supported existing cards, but does not expose those detailed layout operations. MCP also offers interactive card display in compatible apps; CLI whiteboard screenshots are schematic.

​

​

If your agent installs the skill successfully but still can't register or connect to the CLI, check the agent's sandbox permissions. Some agents run in a restricted, read-only sandbox by default, which stops them from running the CLI or accessing files outside their workspace.

​

For example, in the Codex desktop app, go to Settings → Configuration → Sandbox settings and change it from Read only to Full access ("Can edit files outside this workspace"). Then restart both the Heptabase CLI and the Codex app and try connecting again.

If you build something cool or run into issues, reach out through in-app support — we'd love to hear from you.