Using ChatGPT, Codex, Claude, or Claude Code? The official Heptabase plugin is the easiest way to start, and it does not need the CLI: see Use Heptabase with ChatGPT and Codex or Use Heptabase with Claude and Claude Code. Use the CLI when your AI coding agent works in a terminal on the computer where the Heptabase desktop app runs.
The Heptabase CLI lets AI coding agents, such as Claude Code and Codex, work with your Heptabase space through the desktop app. The current version is CLI 0.10.0, included in desktop v1.117.0.
What the CLI can do
Create and read note cards and journals, and edit part of them without rewriting the whole note, including images, videos, audio, and attachments
Create PDF, image, audio, video, web, and YouTube cards from files or URLs, and parse PDFs
Read parsed PDFs page by page, the transcripts of audio and video cards, and your journals across a date range
Read card highlights and backlinks
Search by keyword or by meaning, and list cards by type, tag, or whiteboard
Create and edit tag databases, query their cards, set property values, add or remove tags on cards, create tag groups, and move tags
Trash and restore cards
Read and organize your Inbox
Read and set your Space Instructions
Read, create, and edit whiteboards: place, move, arrange, align, resize, recolor, and remove objects; create sections, connections, and mind maps; check layouts and export schematic screenshots
Read your AI Tutor courses, lessons, and chat history
Export original files that are available on your computer, and rename whiteboards, sections, tags, chats, and media cards
Install the required skill
Install the official Heptabase CLI skills before you use the CLI.
The skill tells your AI coding agent when to use the CLI and how to set it up. Since CLI 0.10.0, the detailed guide to working in Heptabase ships with the CLI as a built-in system manual, and the skill points your agent to it (heptabase system-manual read concepts). Updating Heptabase keeps the manual current, so you no longer need to update the skill every time you update Heptabase.
If you installed the skills before CLI 0.10.0, update them now. Earlier versions use commands that CLI 0.10.0 replaced.
Enable the CLI
The CLI requires an active Heptabase subscription. Eligible early adopters using single-device mode without sync are an exception. Other accounts receive a 403 error even when the CLI is turned on.
Open the Heptabase desktop app and update it to the latest version.
Go to Settings → AI Features → CLI and turn it on.
macOS
The heptabase command is installed automatically, so you can use it right away.
Linux AppImage
In Settings → AI Features → CLI, click Register. The command is installed at ~/.local/bin/heptabase. Open a new terminal, then run command -v heptabase and heptabase --version to check it.
Windows
You will see a setup hint like this:
Add C:\Users\<you>\.heptabase\bin to your PATH from System Settings > Environment Variables, then reopen your terminal.
The easiest way is to paste this message into your AI coding agent and let it set up the PATH for you.
Check the connection
Open a new terminal and run heptabase start.
Only use official CLI commands
Make sure your agent uses the heptabase CLI as the only way to access your data. Do not let it read or change Heptabase's local database, app storage, cache files, or internal endpoints. Doing so can corrupt your data.
If your agent finds that the CLI cannot do something you need, do not let it look for a workaround. Contact support first, and we will help you find a safe way.
Try your first tasks
Before giving your agent real work, have it explore the CLI and try a few safe actions. Paste these prompts into your agent:
Explore: "Read the Heptabase CLI system manual with
heptabase system-manual read, starting with the concepts page, and runheptabase -h. Summarize what the Heptabase CLI can do."Read: "Use the Heptabase CLI to list my 5 most recently edited cards, with their titles and last edited times."
Write: "Use the Heptabase CLI to append a short line to today's journal, such as 'Tested the Heptabase CLI'."
Save a PDF: "Use the Heptabase CLI to save this paper as a PDF card, parse it, and summarize the first 5 pages: https://arxiv.org/pdf/1706.03762"
Whiteboard: "Use the Heptabase CLI to list my 10 most recently edited whiteboards. Pick one, read its content and layout, export a schematic screenshot, and suggest layout improvements without changing anything."
Tag database: "Use the Heptabase CLI to find a tag I use often, such as
book, list its properties, and read the property values of one card under it."
Once the agent knows what the CLI can do, later requests, such as "summarize the PDF I added yesterday" or "add my latest meeting note to the Q2 planning whiteboard", work much more reliably.
Command reference
Searching
heptabase search keyword "<query>" finds exact words or short phrases in the titles and content of cards, journals, whiteboards, sections, and tags. PDF, video, and audio cards are matched by title only. heptabase search semantic "<query>" finds content by meaning, even when it uses different words. Both return short excerpts; read a result in full with object read.
heptabase card list -q <keyword> matches card titles only.
Reading content
object read returns an object's content with line numbers, and --offset and --limit read long content in parts:
heptabase object read card <cardId> --offset 0 --limit 100
Use the matching object type, such as highlightElement for a highlight or journal with a YYYY-MM-DD date. Use whiteboard read for whiteboards, and the pdf, audio, and video commands for PDF pages and transcripts. To read your journals across a date range, use journal read-range --start-date <YYYY-MM-DD> --end-date <YYYY-MM-DD>; one call covers up to 185 days.
Editing notes and journals
note create creates a note card from Markdown. note edit and journal edit change part of a note or journal in Markdown without rewriting it: replace exact text, add content at the end, or rewrite the whole content. Put every change to one note in a single call; the changes are saved together, or none are. journal edit also creates the journal if that date has none. Read the current content first with object read card <cardId> or object read journal <YYYY-MM-DD>. In CLI 0.10.0, these commands replace note append, journal create, and journal append.
For changes that Markdown cannot express, note save and journal save replace the whole document with ProseMirror JSON. Read the latest content and its contentMd5 first, edit the document while keeping its structure, then pass that hash when you save:
heptabase note read <cardId> > note.json
jq -r .content note.json > content.json
Edit content.json, then save it:
heptabase note save <cardId> --content-md5 "$(jq -r .contentMd5 note.json)" --content-file content.json
If the note changed after you read it, the save is rejected. Read it again and apply your changes to the latest version.
Adding files and media
Import a file from your computer or a URL, then create a card from it with the command for its kind:
heptabase file import ./paper.pdf
heptabase pdf create --file-uri <fileUri>
The import result says which kind it is: pdf, image, audio, video, or file. Files can be up to 2,000 MB. To save a web page or a YouTube video, use heptabase web create --url <url> or heptabase video create --url <url>. To put an imported image, video, audio file, or attachment inside a note or journal, use its file URI in the content.
Card mentions in Markdown
type="card" refers only to note cards. Use the mention type that matches the target:
Target | Mention type |
Note card |
|
PDF card |
|
Image card |
|
Video card |
|
Audio card |
|
<hepta-mention type="videoCard" id="<VIDEO_CARD_ID>">Video title</hepta-mention>
Using type="card" with a media card's ID creates a broken mention that shows "Invalid card".
note read reads only note cards. For other card types, use object read with the matching type, or the type's own command, such as pdf metadata. A "Card not found" result from note read does not mean the card was deleted.
Highlights
card highlights <cardId> reads the highlights on a note card or PDF card, with their notes. The text of a highlight cannot be edited through the CLI. To keep a revised version, create a separate note card.
Trashing and restoring cards
card trash <cardIds...> moves cards to the trash, and card restore <cardIds...> brings them back. Trashed cards stay on their whiteboards, so a restored card returns where it was. The trash result lists those placements; remove them with whiteboard remove-objects if you do not want them. Journals cannot be trashed.
Before letting your agent trash cards it found itself, ask it to show you the list of cards and wait for your approval.
Whiteboard screenshots
whiteboard screenshot exports a simplified PNG for checking layouts. It does not show card content as the app does, and small titles may be left out. For layout work, combine it with whiteboard read --mode content and whiteboard read-layout.
Inbox
inbox list lists what is in your Inbox: cards and messages you added, mentions, replies, quotes, and invites. inbox add adds cards or journals, optionally with --remind-date. inbox update marks items done, read, or unread, or sets or clears a reminder date. inbox remove removes cards and messages you added, without deleting them; mentions, replies, quotes, and invites can only be marked done.
Marking a card done does not file it. To organize it, have your agent place it on a whiteboard or tag it first.
Space Instructions
Space Instructions are the standing rules you set for how AI works in your space. space-instructions read reads them; the system manual tells your agent to read them at the start of each session and follow them. space-instructions set <cardId> makes an existing note card your Space Instructions. To add a rule, edit that card with note edit.
Exporting original files
To give your agent an original PDF, image, audio, or video file, find its file ID and export it:
heptabase file list --card-id <cardId>
heptabase file export <fileId> --output-dir /absolute/path/to/existing-folder
Choose the file with purpose: "content"; a media card may also have a cover file. The output folder must already exist. Export only works for files in your own space that are already on your computer. If a file is missing, open or sync it in Heptabase first.
Renaming objects
object rename renames a whiteboard, section, tag, chat, or PDF, web, image, video, or audio card:
heptabase object rename whiteboard <whiteboardId> --new-name "Renewable energy research"
To rename a note card, edit its first heading instead.
Checking command results
Results and request errors are JSON. An error has an error string, or an error object with code, message, and retryable. Check the error and its guidance before retrying.
For batch commands, such as whiteboard edits, a successful result can still contain failed items. Have your agent check every item before reporting that the batch is done.
Tag databases
The CLI can create and edit tag databases:
Create a tag database (
tag create), then add properties, select options, and views (tag edit)Read its properties (
tag properties) and find cards with filters and sorts (tag query)Read and set property values on a card (
card properties,card set-property)Create tag groups (
tag create-group) and move tags under another tag or into a group (tag move)Add a tag to a card or remove it (
tag add,tag remove)
New tags are created at the top level. To nest one under another tag, create it, then move it with tag move.
CLI and MCP
Both let AI agents work with your Heptabase space, and they can do most of the same things. MCP connects through Heptabase's servers and works in chat apps such as ChatGPT and Claude; the CLI runs on your computer through the desktop app. For a side-by-side comparison, see Heptabase MCP and CLI: what's the difference?.
Troubleshooting
Linux AppImage
If the terminal says
heptabase: command not found, make sure~/.local/binis in your PATH, then open a new terminal.If
command -v heptabasefinds the command but it reportsHeptabase runtime was not found, your PATH is fine. The saved registration may point to an AppImage path that is gone after restarting Heptabase. Open Settings → AI Features → CLI and register again. You may need to do this after each restart until we fix it.
Agent cannot connect
If your agent installed the skill but cannot connect to the CLI, check its sandbox settings. Some agents run in a read-only sandbox by default, which blocks the CLI.
For example, in the Codex desktop app, go to Settings → Configuration → Sandbox settings and change Read only to Full access. Then restart Heptabase and the Codex app, and try again.
If you build something cool or run into issues, reach out through in-app support. We would love to hear from you.