---
title: memhtml head status
description: "Report the corpus version and where it came from: the head server's (`source: server`, with the server's ref, load, advances, and uptime under `server`) when one answers on .memhtml/head.sock, else the version at HEAD built here, with its sha, record count, skipped files, load time, and source: `snapshot` (HEAD's own .arrow file), `snapshot+advance` (an ancestor's snapshot advanced over the changed paths, with `ancestorSha` and `reparsed`), or `git`. `policy` says where the store's write policy comes from: `file` (`memhtml.config.json` present, with its `path`), `defaults` (absent: the library defaults, which refuse no type and require no anchor), or `invalid` (present and unreadable or malformed, with the `reason`: every write that needs the policy refuses with ERR_STORE_CONFIG until it is fixed). The head server reads the file when its status is asked and reports the same under `server.policy`, and `head serve` logs the source in one line at startup."
---

## 1. Synopsis

Report the corpus version and where it came from: the head server's (`source: server`, with the server's ref, load, advances, and uptime under `server`) when one answers on .memhtml/head.sock, else the version at HEAD built here, with its sha, record count, skipped files, load time, and source: `snapshot` (HEAD's own .arrow file), `snapshot+advance` (an ancestor's snapshot advanced over the changed paths, with `ancestorSha` and `reparsed`), or `git`. `policy` says where the store's write policy comes from: `file` (`memhtml.config.json` present, with its `path`), `defaults` (absent: the library defaults, which refuse no type and require no anchor), or `invalid` (present and unreadable or malformed, with the `reason`: every write that needs the policy refuses with ERR_STORE_CONFIG until it is fixed). The head server reads the file when its status is asked and reports the same under `server.policy`, and `head serve` logs the source in one line at startup.

```sh
memhtml head status [options]
```

## 2. Arguments

This command takes no positional arguments.

## 3. Flags

| Flag | Type | Default | Values | Description |
| --- | --- | --- | --- | --- |
| `--server` | flag | `true` | *no fixed set* | Ask the head server on .memhtml/head.sock first (`memhtml head serve`), falling back to loading the head here when no server accepts within 100 ms or answers within 10 s; `--no-server` always loads here. The payload's `source` is `server` when the server answered, and `server` is then the server's own status (null when this process loaded the head). |

Every command also accepts the [global flags](/reference/global-flags/).

## 4. Response

On success the command writes one JSON envelope to stdout, and its `type` is `head.status`.

On failure it writes the failure envelope, whose `code` comes from [error codes](/reference/error-codes/).

[The JSON envelope](/reference/envelope/) gives the fields both shapes carry. [Response types](/reference/response-types/) lists every value `type` takes across the binary.

## 5. Further reading

No guide block names this command. The [guide](/reference/guide/) is the workflow prose the CLI ships beside the command table: which command to reach for, and in what order.

## 6. Provenance

A loader generates this page from `apps/cli/src/commands.ts` while the site builds, so no file in the repository holds it: the `COMMANDS` array there is the one source of argument parsing, of `memhtml manifest`, and of `AGENTS.md`. Change the registry and this page changes with it.