Current CLI version: 0.6.0

What can the Heptabase CLI do?

Any AI coding agent with access to your terminal can:

Create, read, and edit note cards and journals
List and read highlight cards
Search your Card Library
Manage tags
Read, create, and edit whiteboards and their layouts, including placing, moving, arranging, aligning, resizing, recoloring, and removing objects; creating sections and connections; and working with editable mind maps
Read your tag database schema and read or write the property values on each card
Read the parsed text content of your PDF cards, page by page (new in v0.4.0)
Read the transcripts of your audio and video cards (new in v0.4.0)
Read your AI Tutor courses, lessons, and chat history

All commands return JSON, so agents can parse and act on results reliably.

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

heptabase note read <cardId> | jq '.content | fromjson'

For a plain-text view:

heptabase note read <cardId> | jq -r '.content | fromjson | .. | objects | .text? // empty'

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

Mentioning cards from CLI-authored Markdown

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

Target	Mention type
Note card	`card`
PDF card	`pdfCard`
Image card	`imageCard`
Video card	`videoCard`
Audio card	`audioCard`

Example:

<hepta-mention type="videoCard" id="<VIDEO_CARD_ID>">Video title</hepta-mention>

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 its type-specific command, such as video metadata, audio metadata, or pdf metadata, or use 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, have the agent paginate the complete candidate set and show the exact card IDs, count, and createdTime bounds for approval; then soft-trash only the approved IDs one at a time. Stop on any failed or uncertain result, preserve the source PDF and older highlights, and do not empty Trash until the result has been verified. 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.

Before you start: install the official Heptabase CLI skill (required)

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.

How do I enable it?

Open the Heptabase desktop app. (You'll need at least v1.91.0)
Go to Settings → AI Features → CLI and turn it on.
On macOS, the heptabase command is installed automatically — you can start using it right away.
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.
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.
Open a new terminal and run heptabase start to confirm everything works.

Linux AppImage troubleshooting

If the terminal says heptabase: command not found, this is a PATH issue. Make sure ~/.local/bin is in PATH, then open a new terminal.
If command -v heptabase finds the launcher but the command reports Heptabase runtime was not found, PATH is already working. On some Linux AppImage installations, the saved registration can still point to a temporary AppImage mount path that is no longer available after restarting Heptabase.
In that case, do not keep changing PATH. Open Settings → AI Features → CLI and register the CLI again. You may need to repeat this after each Heptabase restart while this issue is being fixed.

Troubleshooting: my agent can't connect to the CLI

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.

Getting started: let your agent explore first

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.

Important: Only access Heptabase data through official CLI commands

When using an AI agent with Heptabase, make sure it uses the heptabase CLI as the only way to access your data.

DO NOT ask or allow agents to directly read, write, or modify Heptabase app data through local database files, app storage, cache files, internal endpoints, or any other non-CLI method. Bypassing the CLI can cause data corruption, inconsistent state, or unexpected behavior.

If there is an operation you want the agent to perform, but the agent finds that the current CLI does not support it, do not rush into any workaround. We recommend contacting customer support first to confirm whether the operation is supported and discuss the safest way to proceed.

What can — and can't — the CLI do with tag databases?

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

Create a new simple tag database (tag create --name)
Read your tag database's property schema (tag properties)
Read the property values on any card under that tag (card properties, tag cards --include-properties)
Set one property value at a time on a card (card set-property)

It cannot:

Create nested parent / child tag relationships or specify parentTagId when creating a tag. Create and organize the nested structure in the desktop app first.
Define, rename, or delete property columns. Create and edit the tag database schema in the desktop app first, then ask your agent to fill in values.
Add, rename, or delete options on Select / Multi-select properties — option lists also have to be set up in the desktop app first. If your agent tries to set a value that doesn't exist as an option (e.g. setting Progress to "Reading" when no such option has been defined yet), the CLI will reject it with a clear error.
Filter or query cards by property value — the CLI returns full results and your agent can filter client-side.

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.

How is the CLI different from the MCP integration?

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

MCP (Model Context Protocol) lets compatible AI assistants search, read, create, and update supported content in your cloud-synced Heptabase space.
CLI is a command-line tool that lets AI coding agents work with Heptabase through the running desktop app. The desktop app must be running for the CLI to connect.

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

How to use Heptabase CLI?