HEAD Queries

A HEAD query returns all active items in a repository — things, assertions, shapes, and collections — at their current version. It’s the fastest way to orient yourself in a repository.

CLI

The CLI names these snapshot reads list for consistency across domains; the command returns the repository HEAD projection.

# All active items
wh thing list

# Filter by shape
wh thing list --shape Location

# Filter by kind (thing, assertion, shape, collection)
wh thing list --kind assertion

# Limit results
wh thing list --limit 50

# Glob filter on wrefs (* = one segment, ** = zero or more)
wh thing list --match "Location/*"

# JSON output
wh thing list --json

Counting

Use --count to get just the number of matching items instead of the full result list:

# Count all active items
wh thing list --count

# Count by shape
wh thing list --shape Location --count

# Count assertions
wh assertion list --count
wh assertion list --shape Belief --count

--count cannot be combined with --limit, --cursor, --all, or --live.

For assertions specifically:

# Equivalent to: wh thing list --kind assertion
wh assertion list

# With shape filter
wh assertion list --shape Belief

MCP

{
  "name": "warmhub_thing_head",
  "arguments": {
    "shape": "Location",
    "kind": "thing",
    "match": "Location/dungeon/*",
    "limit": 100
  }
}

Count via MCP:

{
  "name": "warmhub_thing_head",
  "arguments": {
    "shape": "Location",
    "count": true
  }
}

All parameters are optional. Omit them to get everything.

HTTP API

The HTTP examples below use the public warmhub-data/congress-trading repo so you can copy-paste them directly; the CLI and MCP blocks above use generic Location names that you’d swap for your repo’s own shapes.

GET /api/repos/warmhub-data/congress-trading/head
GET /api/repos/warmhub-data/congress-trading/head?shape=StockTrade&kind=thing&limit=25
GET /api/repos/warmhub-data/congress-trading/head?match=StockTrade%2F2024%2F20025368%2F*&limit=25

Anonymous callers reading public repos are capped at limit=25 per page; authenticated callers can request up to limit=500. See Anonymous Pagination Caps.

The HTTP API does not currently mount a count-only route. Use CLI/MCP count surfaces for count-only reads, or page through /head when using HTTP.

Response

The response contains an items array. Each item includes:

Field	Description
name	Item name
wref	Full wref (Shape/name for things, assertions, and collections; the shape name itself for shape rows)
shapeName	Shape name (omitted for shape rows)
kind	Entity kind (shape, thing, assertion, collection)
version	Current version number
data	Current data payload
aboutWref	About target wref (assertions only)

Reactive Mode

Watch HEAD in real-time:

wh thing list --live

This opens a WebSocket connection and re-renders the display whenever data changes. On TTY terminals, the output refreshes in place. Combine with filters:

wh thing list --live --shape Location --kind thing

When to Use HEAD

HEAD queries are best for:

• Orientation — understanding what’s in a repo before targeted queries
• Monitoring — watching for changes with --live
• Broad snapshots — getting everything of a particular shape or kind

For targeted lookups, prefer filtering queries which accept more specific criteria.