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.

Agent Skill Discovery

These commands are bundled with the CLI and require neither a login nor a running server:

heaper skills list
heaper skills list --json
heaper skills show heaper
heaper skills show heaper-search
heaper skills show heaper-documents --json
heaper skills show heaper-organize
heaper doc formatting

list returns names and task descriptions. show returns the full portable SKILL.md; with --json it returns name, description, and markdown. An unknown name exits with an error and points back to skills list. doc formatting returns the same JSON node and patch guide as MCP get_document_formatting.

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 keygen codex
heaper auth login https://your-heaper.example \
  --agent codex \
  --profile-name "Codex helper"

Important options:

Related commands:

heaper auth status
heaper auth servers
heaper auth identities
heaper auth keygen codex
heaper auth keygen codex --use-existing
heaper auth keygen codex --new-name codex-work
heaper auth logout <server-url-or-public-key>

Create a named identity before login. Identity creation never overwrites an existing file: interactive terminals prompt to use the existing identity or choose another name, while scripts must pass --use-existing or --new-name explicitly.

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.