CLI Reference

The Heaper CLI supports two connection modes:

• A hosted or self-hosted server over HTTPS.
• The Electron Local API over localhost HTTP.

Run heaper <command> --help for the complete option list installed with your version.

Global Options

Global options must appear before the command:

Example:

heaper --server https://your-heaper.example --json blocks --limit 20

Remote Authentication

heaper auth login <server-url>

Sign in with a Heaper agent key challenge:

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

Important options:

Related commands:

heaper auth status
heaper auth servers
heaper auth identities
heaper auth keygen codex
heaper auth logout <server-url-or-public-key>

Heaps and Blocks

heaper heaps

List the heaps available through the active connection:

heaper heaps

heaper use <heap-id>

Verify a heap and save it as the default for later commands:

heaper use <heap-id>

heaper blocks

List, filter, or search blocks in the active heap:

heaper blocks
heaper blocks --type document
heaper blocks --query project --preview --limit 20

heaper block <block-id>

Fetch bounded block metadata, relations, backlinks, and files:

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

Saved-view evaluation with --view is currently available only through the Electron Local API.

heaper search <query>

Run full-text search:

heaper search "meeting notes"
heaper search --all roadmap --limit 10

heaper history [block-id]

Read provenance history for a heap or one block:

heaper history
heaper history <block-id> --source cli_server --node-authorship

History can be filtered with --source, --actor, --event-type, --since, and --cursor.

Documents and Writes

heaper create

Create a document block:

heaper create \
  --heap <heap-id> \
  --title "Project note" \
  --content "First paragraph" \
  --tag <tag-block-id>

Use --content-file <path> instead of --content to read the initial content from a file. Repeat --tag to add more initial tags.

heaper doc get <block-id>

Get a structured document snapshot for safe agent editing:

heaper doc get <block-id> > doc.json

The result includes stable node identifiers and a document hash.

heaper doc patch <block-id>

Apply structured operations with conflict checking:

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

Example patch.json:

{
  "base_hash": "copy-from-heaper-doc-get",
  "ops": [
    {
      "op": "replace_text",
      "node_id": "n:0",
      "find": "old",
      "replace": "new"
    },
    {
      "op": "append_block",
      "node": {
        "type": "paragraph",
        "text": "New paragraph"
      }
    }
  ]
}

Use --ops <json> for inline operations or --base-hash <hash> when the hash is not included in the JSON payload.

heaper edit <block-id>

Use compatibility helpers for common text edits:

heaper edit <block-id> --title "Updated title"
heaper edit <block-id> --replace-first-line "Updated first line"
heaper edit <block-id> --append-line "Another paragraph"

--replace-file <path> rebuilds the collaborative document tree and therefore also requires --force-rebuild.

Relations and Properties

heaper tag <block-id> <tag-id>
heaper untag <block-id> <tag-id>
heaper property set <block-id> <property-id> <value>
heaper property set <block-id> <date-property-id> 2026-06-29 --kind date
heaper property unset <block-id> <property-id>

Property kinds include string, number, boolean, date, datetime, block, list, object, json, url, and location.

Files

Create a File Block

heaper file add ./photo.jpg \
  --heap <heap-id> \
  --title "Reference photo"

This creates a block and uploads the file. File creation and upload currently require a remote server connection.

List and Upload

heaper file list <block-id>
heaper file upload <block-id> ./attachment.pdf

Remote uploads check for an existing matching hash and size before transferring data. Files larger than 32 MiB use resumable chunks.

Download

heaper file download <block-id> --output ./downloaded.bin
heaper file download <block-id> --hash <file-hash> --output ./downloaded.bin

Downloads work through remote servers and the Electron Local API. Existing files are not overwritten unless --force is supplied.

Thumbnails

heaper file thumbnails <block-id> --json
heaper file thumbnail <block-id> \
  --hash <file-hash> \
  --type image \
  --size small \
  --output ./thumb.webp

Use the thumbnail list to discover valid file hashes, types, and sizes.

Invites

Accept a workspace invite through the selected remote server:

heaper --server https://your-heaper.example invite accept <invite-code>

Local SQL

Run one read-only SQL statement against the Electron Local API:

heaper query "SELECT id, title FROM blocks WHERE workspace_id = ? LIMIT 5" '"<heap-id>"'

Raw SQL is not exposed by the remote server. Parameters after the SQL string are parsed as JSON when possible.

Status

Show information about the active API connection:

heaper info

For remote authentication details and stored server selection, use:

heaper auth status

MCP Server

Start the typed MCP server over standard input and output:

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

If a saved remote server is already selected, this is sufficient:

heaper mcp --stdio

See Agent and MCP Access for MCP client configuration, capability differences, and guarded writes.

Environment Variables

Command-line options take precedence over environment variables and saved connection state.