use-cli-heptabase

use-cli-heptabase

Heptabase CLI (heptabase, v0.1.0+). Desktop app must be running with CLI enabled (Settings → AI Features → CLI).

Prerequisite

Run heptabase start first. Electron writes a harmless warning to stderr on every invocation. Suppress with 2>/dev/null when parsing.

Output	Meaning
{"status":"ready",...}	Server up. Proceed
Hangs / non-JSON	Desktop app closed or CLI toggle off

Commands

Run heptabase <sub> -h for argument details (flags vary per subcommand).

Purpose	Command
Server ready check	heptabase start
List / search cards	heptabase card list --limit N --offset M
Trash / restore card	heptabase card trash <id> / heptabase card restore <id>
Create note (markdown)	heptabase note create (first # heading = title)
Read note	heptabase note read <cardId>
Append note (markdown)	heptabase note append <cardId>
Replace note (ProseMirror JSON)	heptabase note save <cardId> (needs contentMd5 from read)
Journal CRUD by date	heptabase journal create | read | append | save <date>
Tag list / create / add / remove	heptabase tag list | create | add | remove
Cards under a tag	heptabase tag cards <tagId>
AI Tutor goals / courses / lessons	heptabase goal | course | lesson ... (read-only)

Content Format

Operation	Format
create / append	Markdown
read	ProseMirror JSON (returns contentMd5)
save	ProseMirror JSON (requires latest contentMd5 from read)

When to Use

use-cli-heptabase	Alternative
Write back to knowledge base (journal append, note create)	Local markdown repo edit
Card library lookup by title / recency	kiku (Slack)
AI Tutor course / lesson / chat read	n/a

Warm-up (first use in session)

1. heptabase start returns {"status":"ready"}
2. heptabase card list --limit 3 for read smoke test
3. Use -h on any subcommand before first write