CLI Reference
The CLI is a wrapper over the local client HTTP API, not the remote server API.
Global Options
| Flag | Description |
|---|---|
--json | Force JSON output instead of table or key/value output. |
--token <token> | Local API token. Falls back to HEAPER_TOKEN. |
--port <port> | Local API port. Falls back to HEAPER_PORT or ~/.heaper/api.json. |
--session <id> | Resume a saved heap session created by heaper use. |
--heap <id> | Override the heap for the current command. |
--limit <n> | Pagination limit for commands that support paging. |
--offset <n> | Pagination offset for commands that support paging. |
Commands
heaper heaps
- Purpose: List all heaps available through the local API.
- Local API call: GET /api/heaps
Examples:
heaper heaps
HEAPER_TOKEN=<token> heaper heaps --json
heaper use <heap-id>
- Purpose: Create a short-lived local session and make that heap the default for later commands.
- Local API call: GET /api/heaps/:id
Notes:
- The command first verifies that the heap exists.
- Sessions are stored in
~/.heaper/sessions/*.jsonand expire after 24 hours.
Examples:
heaper use <heap-id>
heaper blocks
- Purpose: List blocks in a heap, optionally filtered or searched.
- Local API call: GET /api/heaps/:id/blocks
Options:
- --type
: filter by block type. - -q, --query
: full-text search term scoped to the heap.
Examples:
heaper blocks
heaper blocks --type document
heaper blocks --query project --limit 20
heaper block <block-id>
- Purpose: Fetch a single block with relations, files, and related local data.
- Local API call: GET /api/blocks/:id
Options:
--view <view-id-or-name>: resolve one saved app view on the block and return a paginated result set for that filtered view.--limit <n>: page size for relations, backlinks, and--viewresults.--offset <n>: page offset for relations, backlinks, and--viewresults.
Examples:
heaper block <block-id>
heaper block <block-id> --view "<view-id-or-name>" --limit 25 --offset 0
heaper search <query>
- Purpose: Run full-text search across local blocks, optionally within the current heap session.
- Local API call: GET /api/search
Examples:
heaper search "meeting notes"
heaper search roadmap --limit 10
heaper query <sql> [params...]
- Purpose: Execute a read-only SQL query against the local data store.
- Local API call: POST /api/query
Notes:
- CLI parameters after the SQL string are parsed as JSON when possible before they are sent as SQL params.
Examples:
heaper query "SELECT id, title FROM blocks LIMIT 5"
heaper query "SELECT id, title FROM blocks WHERE workspace_id = ?" '"<heap-id>"'
heaper info
- Purpose: Show local API status plus the latest active heap session.
- Local API call: GET /api/info
Examples:
heaper info