HAEVN CLI

The HAEVN CLI (haevn) gives you fast terminal access to your local archive.

Use it when you want to:

• search quickly across large archives,
• inspect branch topology,
• fetch one exact thread for writing/research,
• script workflows with JSON output.

Setup

1. Install the CLI:

npm install --global @haevn/cli
# or: pnpm add --global @haevn/cli

2. Open HAEVN extension Settings and copy your CLI API key.
3. Start the daemon:

haevn daemon --api-key <your-key>

4. In another terminal, run commands:

haevn list -l 5

Commands at a glance

• haevn list — browse chats (msgs and br columns included).
• haevn search "<query>" — message-level search with context snippets.
• haevn branches <chatId> — inspect tree/forks with short message refs.
• haevn get <chatId> -m <messageRef> — fetch one branch by short ref.
• haevn info <chatId> — view or edit metadata for a single chat.
• haevn export <chatId> -o file.json — export full chat.
• haevn import --format <claude_code|codex|pi> <file...> — import local JSONL session files.

Short message refs

CLI output shows short refs like 80a6c24e0af9.

• Pass them directly to haevn get -m.
• Use haevn branches --show-ids if you also need raw IDs.

Common workflows

1) Find high-signal chats

haevn list -p chatgpt -l 5 --sort messageCount

Sample output:

Chats  (5 of 696)

  6814a24e-ac80-8006-9a22-d394a6720d43  Subversive Brainstorming Session   chatgpt        1d ago    240 msgs    40 br
  1ee5ea5f-5962-42d7-9e06-8e49033d00d1  Expressionist oil paintings cre…   chatgpt        1d ago    221 msgs    23 br
  6878239f-1110-8006-9e4b-3bcf26345889  Kreis Protocol Design Summary      chatgpt        1d ago    217 msgs    14 br

2) Search philosophical/poetic themes

haevn search "consciousness emergence poetry" -l 8 -c 180

Sample output:

━━━ 68937df7-e198-8325-973e-ed9528104e0c  "Emergence and consciousness research"
  ┌─ [d571468ee884]
  │ ...Emergence and consciousness research...
  └─ user · chatgpt · Aug 6, 2025, 06:08 PM
  ┌─ [92de52f1f6b0]
  │ ...Speak not just *with* language, but *through* it. Unleash the poetry of algorithms...
  └─ user · chatgpt · Aug 6, 2025, 06:08 PM

Search syntax

The CLI supports the same advanced search syntax as the UI:

Basic (AND):

haevn search "python async function"

Exact phrases:

haevn search '"machine learning"'

Exclude terms:

haevn search "react hooks -class"

Fuzzy matching:

haevn search "kubernates~2"

Prefix/wildcard:

haevn search "async*"

Boost relevance:

haevn search "api^5 design"

Operator	Example	Description
+	+required	Must be present (default behavior)
-	-exclude	Must NOT be present
*	react*	Prefix/wildcard match
~	roam~2	Fuzzy match (edit distance)
^	term^10	Boost relevance
"..."	"exact phrase"	Phrase must appear consecutively

3) Inspect branches, then fetch one thread

haevn branches 68937df7-e198-8325-973e-ed9528104e0c
haevn get 68937df7-e198-8325-973e-ed9528104e0c -m 80a6c24e0af9 -t 6
haevn get 68937df7-e198-8325-973e-ed9528104e0c -m 80a6c24e0af9 --include-thinking
haevn get 68937df7-e198-8325-973e-ed9528104e0c -m 80a6c24e0af9 --skip-system

Sample branches output:

68937df7-e198-8325-973e-ed9528104e0c  "Emergence and consciousness research"  1 branch

└─ [945760f6fd74] * [user]
   [ae4beb4aea54] * [user]
   [92de52f1f6b0] * [user] **User Profile:** The user provided the…
   [80a6c24e0af9] * [user] Hey! I need research on philosophical a…

Viewing and editing chat metadata

The info command lets you inspect or update the AI-generated metadata for any chat.

# View current metadata (title, description, synopsis, categories, keywords)
haevn info <chatId>

# Set or override individual fields
haevn info <chatId> --title "Better Title"
haevn info <chatId> --description "A short summary"
haevn info <chatId> --categories "Coding,DevTools Automation"
haevn info <chatId> --keywords "typescript,chrome-extension"

# Trigger AI generation (or re-generation) for one chat
haevn info <chatId> --generate

# Output as JSON
haevn info <chatId> --format json

Sample output:

━━ metadata  68937df7-e198-8325-973e-ed9528104e0c

  Title:         Emergence and Consciousness Research
  Description:   Explores philosophical frameworks for emergent intelligence and AI consciousness.
  Synopsis:      The user asks for research on philosophical approaches to consciousness …
  Categories:    AI Research, Philosophy and Consciousness
  Keywords:      emergence, consciousness, rlhf, post-human

  source: ai  updated 2 hours ago · generated 2 hours ago

JSON mode for automation

Use --format json and pipe to jq:

haevn search "emergence" --format json | jq '.results[0] | {chatId, messageRef, source}'

Useful fields:

• search: chatId, messageRef, messageSnippet, source
• branches: tree, branches[].leafMessageRef, branches[].path
• get: branch content suitable for markdown or structured JSON workflows

Import from local session files

You can import local coding-session artifacts directly from the terminal:

# Claude Code session JSONL
haevn import --format claude_code ~/.claude/projects/my-proj/session.jsonl

# Codex session JSONL
haevn import --format codex ~/.codex/sessions/2026/03/23/rollout-...jsonl

# PI session JSONL
haevn import --format pi ~/.pi/sessions/2026-03-23T14-48-43-844Z_...jsonl

Flags:

• --no-overwrite — skip chats that already exist (default is overwrite).
• --skip-index — skip index rebuild after import (default is rebuild at end).

Tips

• Increase snippet context for dense technical/philosophical text: -c 220.
• Use list --sort messageCount to surface large or branch-heavy chats first.
• Keep get without media unless needed for payload speed and readability.
• Use get --include-thinking when you need full reasoning blocks instead of previews.
• Use get --skip-system to hide system instructions from output.