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
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 start to confirm everything works.
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".
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" — will land much more reliably, because the agent already knows the surface area.
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.1.0 — the first step. 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.