Command line — Ablative docs

Run the store

Run the store in the foreground.

haematite serve --config <file.json> [--create] [--long-wait-interval <duration>]

--config <file.json>: The service configuration: the data directory and, optionally, the socket.
--create: Create the store. Requires a new, empty data directory. Leave it off when restarting.
--long-wait-interval <duration>: How often to print a long-wait warning. Default 30s. A warning, not a deadline.

An explicit socket's parent directory must already exist with mode 0700.
An omitted socket uses the private runtime namespace of the operating system.
No auto-launch is installed.

Talk to it

Send one request to a running service and print the answer.

haematite call (--socket <path> | --config <file.json>) [--timeout-ms N] <method> [<params> | -]

<method>: A method the service names, such as documents.get or collections.list.
<params>: One JSON value. A dash reads it from standard input.
--timeout-ms N: Bounds connecting, writing and reading. Default 30000.

Append one change to a branch.

haematite write (--socket <path> | --config <file.json>) [--timeout-ms N] --branch <name> [--expected <generation>.<sequence>] [--request-id <text>] <kind> <value | ->

--branch <name>: The branch the change is appended to. For branch.fork it is the source.
<kind>: A change kind the service names. See the list of change kinds below.
<value>: One JSON value, sent as given. A dash reads it from standard input.
--expected <g>.<s>: The version you last read. A change made in between is refused rather than overwritten.
--request-id <text>: Makes a retry safe. Without it one is made and printed before sending.

Repeated after the change was applied, the same command answers with the same receipt.
Different content under the same request id is refused.

collection.put: Define a collection, with or without a schema.
document.put: Write one record: collection, document_id and document.
documents.put_many: Write several records in one change.
document.delete: Delete one record and what hangs off it.
vector.declare: Declare a vector field on a collection.
vector.put: Store a vector on a record's field.
relation.put: Declare a relation: its name, the collection it runs from, the collection it runs to, and its cardinality (one_to_one, one_to_many or many_to_many).
relation.delete: Remove a relation's declaration.
edge.put: Link two records under a declared relation, with an object of properties.
edges.put_many: Link several pairs of records in one change, all or none.
edge.delete: Remove one link.
branch.fork: Fork a new branch from a version of --branch.
branch.discard: Discard --branch itself. Its value must repeat that name. main is protected.
document.append_prune: Append under a scope and remove bounded older records in the same change.
documents.delete_many: Delete a bounded batch of existing records atomically.
vectors.put_many: Write a bounded batch of vectors whose field dimensions already exist.
vector.delete: Remove one supplied vector.
index.declare: Declare a versioned equality index on a collection field.

Two change kinds have their own value shapes.

{ "name": "ward-4b-cleanup", "from": { "generation": "3", "sequence": "41" } }

{ "name": "ward-4b-cleanup" }

Run a query at a branch's head and print each row on its own line.

haematite query (--socket <path> | --config <file.json>) [--timeout-ms N] --branch <name> <text | ->

--branch <name>: The branch to read.
<text>: The query as typed: a pipeline, or jq. A dash reads it from standard input.

Every page is read at the moment the first page was read.
On exit 2 or 3 after rows were printed, standard error says how many, and that the answer is not complete.

0: Answered or applied. The receipt or the rows are on standard output.
1: Could not prepare or connect before sending the request. Read the command's diagnostic; this is a client-command exit code, not an offline maintenance result.
2: Refused, for codes this client knows. A refusal it doesn't know exits 3, even when nothing was applied; read its receipt. Read-only calls return 2 for service refusals.
3: The outcome is not known to the client. For write only, standard error names the request id to repeat it with. Query standard error instead reports any incomplete row count.

The write client treats a refusal code outside its known list as outcome unknown, exit 3. The relation examples reproduced this for relation_missing, relation_cardinality and relation_collection. Preserve the same request id while reconciling; the presence of a named message alone does not select exit 2.

Open it to people and agents

Serve the Studio at its origin, with Lys sign-in.

haematite door --config <absolute door.json>

Serve MCP over HTTP at /mcp, with Lys sign-in.

haematite mcp-http --config <absolute service.json>

Serve MCP over standard input and output for one agent.

haematite mcp (--socket <path> | --config <file.json>) [--timeout-ms N] [--pass-file <path> | --lys-agent <issuer origin> <agent id> ((--credential-file | --key-file) <absolute path> | --run-pass-env <variable>)]

--pass-file <path>: Read the Lys pass from a file.
--lys-agent <issuer> <agent id>: Ask Lys's agent pass route for a pass, with the grant credential or a request signed by the agent key.
--run-pass-env <variable>: Exchange a seat run pass from the named environment variable for a pass with audience haematite. The value is never printed.

A Lys pass is presented on every call. A new one is asked for whenever none is held or the held one expires within 60 seconds.

Write one bearer header object for an MCP client header helper. The output contains a pass; give it directly to the client.

haematite mcp-pass --lys-agent <issuer origin> <agent id> ((--credential-file | --key-file) <absolute path> | --run-pass-env <variable>) [--timeout-ms N]

--timeout-ms N: Positive milliseconds for the Lys request, default 10000.

Check or register the schema Lys holds for haematite.

haematite lys-schema --issuer <origin> --credential-file <absolute path> (--check | --register | --record <file>)
haematite lys-schema --recorded <file>

Write an install bundle.

haematite install --bundle <new directory> --config <service.json> [--lys-issuer <origin> --lys-agent <id> --key-file <path>] [--lys-issuer <origin> --lys-credential-file <absolute path>]

--bundle <new directory>: Where the bundle is written. Must not exist yet.
--lys-issuer, --lys-credential-file: With this pair, the schema Lys holds is checked first and a drift refuses before anything is written.
--lys-issuer, --lys-agent, --key-file: Preview main accepts all three together and configures the bundled launcher for that agent. The key path is canonicalised and must name a regular file; the key is not copied. These options are absent from the installed documentation binary.

The bundled serve.json is a snapshot. Later socket or data directory changes need a new bundle directory.
A repeat with changed inputs refuses as bundle_conflict.

Host an assistant seat

Run a contained assistant seat from its launch declaration. Preview main only for this documentation run.

haematite assistant run --config <seat.json>

--config <seat.json>: The seat, its paths, proof source and explicit harness with positive resource bounds.

This command is present on preview main at 84b9497a and absent from the installed binary used for these pages. No tagged release carrying it was verified. The installed command returns unknown command "assistant", exit 1. Its seat declaration and limits are described on Connect an agent.

Top-level help matches main’s cli_usage.rs, but does not list every dispatch or command-specific option. The mcp-pass, --run-pass-env, lys-schema --record and --recorded forms are present in the v0.20.1 source. Bundle additions after that tag are identified on the agent and bundle pages.

Maintain a stopped store

Report-only storage inventory. Deletes nothing.

haematite stats <data_dir> [--refs-dir PATH]... [--snapshot-file PATH]... [--json]

--refs-dir PATH: A directory of references outside the store that count as pins. Repeatable.
--snapshot-file PATH: A snapshot file outside the store that counts as a pin. Repeatable.
--json: Machine-readable output.

A live observer report is allowed, but it is a moving view. Stop writers before using the result to plan a backup or sweep.

The sweep. Removes exactly what nothing can reach, or nothing at all.

haematite vacuum <data_dir> (--dry-run | --sweep) [--refs-dir PATH]... [--snapshot-file PATH]... [--attest-metadata-complete] [--json]

--dry-run: Run the full pass and report the deletion set without removing anything.
--sweep: Additionally unlink exactly the unreachable nodes.
--attest-metadata-complete: Your word that the metadata is complete, for the refusal that asks for it. Only pass it when it is true.

Policy blockers refuse before deleting. An I/O failure during unlinking can leave partial progress; preserve the report and investigate.

Rename a branch offline, by forking and then discarding.

haematite branch-rename --config <file.json> --from <name> --to <name> (--check | --apply) [--long-wait-interval <duration>]

--check: Report what would happen.
--apply: Do it, with the service stopped.

Date an undated discarded generation so retention can judge its history by age. This does not set a software release date.

haematite release date --config <file.json> --branch <name> --generation <created> --at <nanoseconds> [--long-wait-interval <duration>]

Migrate or abort a chunking migration.

haematite migrate-chunking <data_dir> (--migrate | --abort) [--json]

Check the history log and show its last entries.

haematite history-check <data_dir> [--json] [--show N]

Read one observed key.

haematite observe-get <data_dir> (--key <text> | --key-hex <hex>) [--hex]