heaper
Docs

Heaper CLI

The heaper-cli npm package connects a terminal, script, or agent directly to a hosted or self-hosted Heaper server. It can also connect to the Electron Local API when you need local-only capabilities.

The package includes normal shell commands and the typed stdio MCP server documented in Agent and MCP Access.

Install

npm install -g heaper-cli
heaper --version

Quick Start With a Server

Log in to a hosted or self-hosted Heaper server:

heaper auth login https://your-heaper.example \
  --agent codex \
  --insecure-save-key

heaper auth status
heaper heaps

The desktop app does not need to be installed or running for this mode. The CLI communicates with the selected server over HTTPS.

After login, normal CLI commands and heaper mcp --stdio reuse the saved server. Select a different saved server explicitly when needed:

heaper --server https://your-heaper.example heaps

Connection Model

The CLI selects a connection in this order:

  1. Explicit --server <url-or-public-key>.
  2. HEAPER_SERVER_URL with remote environment credentials.
  3. Stored credentials created by heaper auth login.
  4. Electron Local API discovery through ~/.heaper/api.json.
ModeUse it forAuthentication
Remote serverHosted or self-hosted access, file uploads, agent access, and normal shell workflowsSaved login or HEAPER_ACCESS_TOKEN and optional HEAPER_REFRESH_TOKEN
Electron Local APIOffline-capable desktop automation, read-only SQL, and saved-view evaluationHEAPER_TOKEN or --token when local auth is enabled

For Local API mode, start Heaper desktop and enable Settings → Local API. The CLI discovers the port automatically. Pass --port only when discovery is unavailable.

Common Workflows

Choose a default heap:

heaper heaps
heaper use <heap-id>

List and search blocks:

heaper blocks --limit 10
heaper blocks --type document
heaper blocks --query project --preview
heaper search "meeting notes"

Read and safely patch a collaborative document:

heaper doc get <block-id> > doc.json
heaper doc patch <block-id> --ops-file patch.json

The patch file contains structured operations and the base_hash returned by doc get. This protects the document from being overwritten after another client changes it.

Upload and download files through a remote server:

heaper file add ./photo.jpg --heap <heap-id>
heaper file upload <block-id> ./attachment.pdf
heaper file download <block-id> --output ./downloaded.bin

File upload is currently remote-only. File download works through remote servers and the Electron Local API.

Run a local read-only query:

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

Raw SQL is intentionally available only through the Electron Local API. Remote agents should use block search, document, property, relation, and file commands instead.

Use the CLI With an Agent

heaper --server https://your-heaper.example mcp --stdio

This starts the typed MCP server over standard input and output. See Agent and MCP Access for client configuration, authentication choices, capability differences, and safe write behavior.

Sessions and Output

heaper use <heap-id> creates a short local session so later commands can omit --heap. Sessions are stored under ~/.heaper/sessions, expire after 24 hours, and are selected automatically in an interactive terminal.

Interactive output uses tables and key/value rows. Non-interactive output and --json use formatted JSON, which makes commands suitable for shell pipelines and agents.

Reference