Current CLI version: 0.3.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
Search your Card Library
Manage tags
List your whiteboards and add or remove cards on them
Read your tag database schema and read or write the property values on each card (new in v0.3.0)
Read your AI Tutor courses, lessons, and chat history
All commands return JSON, so agents can parse and act on results reliably.
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 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 startto confirm everything works.
We also provide official Heptabase CLI skills
These skills help compatible AI coding agents understand how to use the Heptabase CLI safely and reliably. They can be used by any skills-compatible agent, including Claude Code and Codex CLI. If your agent supports skills, we recommend installing the official Heptabase CLI skill before asking it to work with your space.
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 and show me what cards are currently on it.
5. Try reading and writing tag properties (new in v0.3.0)
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.
Once this context is in the conversation, later requests — "create a journal entry about today's meeting", "find all notes tagged book-notes and draft a summary", "add my latest meeting note to the Q2 planning whiteboard", "fill in the Author and Price for each book I've added this week" — 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 works with existing tag databases. It can:
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 a new tag database or define / rename / delete property columns — please 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) is a standard protocol that lets AI assistants query external data sources. Heptabase's MCP integration exposes your cloud-synced Heptabase data to any MCP-capable AI assistant, so it can pull in your notes as context when answering questions.
CLI is a command-line tool that lets AI coding agents read and write your local Heptabase database directly. The desktop app must be running, because that's where your local data lives.
What's coming next? How do I share feedback?
This is v0.3.0 — building on v0.2.0, this release adds read access to tag database schemas and read/write access to per-card property values (tag properties, card properties, card set-property, plus --include-properties on tag cards). We'll keep expanding the CLI so AI agents can act on your knowledge at the same depth you can!
If you build something cool or run into issues, reach out through in-app support — we'd love to hear from you.