heaper
Docs

Heaper CLI

The CLI is a thin developer-focused wrapper around the local client HTTP API. It gives you terminal-friendly output, session shortcuts, and a simpler workflow than calling the local API directly.

this is still very much WIP.

Install

npm install -g heaper-cli

Connection Model

The CLI expects the desktop app to be running with the Local API enabled.

It resolves connection details in this order:

  1. --port and --token
  2. HEAPER_PORT and HEAPER_TOKEN
  3. ~/.heaper/api.json for the port, plus HEAPER_TOKEN or --token for auth

If the app is not running or the Local API is disabled, the CLI fails with a connection error.

Sessions

The use <heap-id> command creates a short session file so later commands can omit --heap.

Session files live in:

~/.heaper/sessions/<id>.json

Current behavior:

  • session IDs are short random hex strings
  • sessions expire after 24 hours
  • TTY mode automatically uses the latest session if you do not pass --heap or --session

Output Modes

TTY behavior:

  • arrays render as tables
  • objects render as key/value output

Non-TTY behavior, or --json:

  • output is pretty-printed JSON

That makes the CLI convenient both for humans and shell pipelines.

Common Workflows

List heaps:

HEAPER_TOKEN=<token> heaper heaps

Choose a default heap:

heaper use <heap-id>

List blocks:

heaper blocks --limit 10
heaper blocks --type document
heaper blocks --query project

Inspect one block:

heaper block <block-id>
heaper block <block-id> --view <view-id-or-name> --limit 25

Run a search:

heaper search "meeting notes"

Run a read-only SQL query:

heaper query "SELECT id, title FROM blocks LIMIT 5"

Relationship to the Local API

Current command mapping:

  • heaper heaps → GET /api/heaps
  • heaper blocks → GET /api/heaps/:id/blocks
  • heaper block → GET /api/blocks/:id
  • heaper search → GET /api/search
  • heaper query → POST /api/query
  • heaper info → GET /api/info

Reference

Use the reference page for the exact options and examples: