Hyphae
GitHub

Getting started

This page walks through the first session against a released 3.0.0 binary: install, initialize a directory, and run one command against each engine. Every command and output below is copied verbatim from the project's usage manual, which is itself validated against the released binary.

Install

From crates.io, with an exact pinned version and a locked dependency graph: 

cargo install hyphae-cli --version 3.0.0 --locked
hyphae version --json
{
  "api_version": "v1",
  "disk_format_version": 2,
  "engine_version": "3.0.0",
  "native_directory_format": 1,
  "product": "hyphae",
  "product_api_version": 1
}

The GitHub release also ships signed archives for Linux x64, macOS x64/arm64, and Windows x64, each with SHA-256 checksums, SPDX/CycloneDX SBOMs, SLSA provenance, and Sigstore bundles. Verify the archive before installing — see install and verification for the checksum and Sigstore steps. To embed Hyphae in a Rust application instead of using the CLI, depend on an exact version: hyphae-native-product = "=3.0.0" for new applications, or hyphae-engine = "=3.0.0" for existing format-2 state.

Initialize a data directory

Hyphae never creates a directory implicitly. init fails if the destination already exists, and every other command that operates on live state expects a directory init already created: 

export HYPHAE_DATA_DIR="$PWD/data"
hyphae init --data-dir "$HYPHAE_DATA_DIR"
{ "data_path": ".../data", "native_directory_format": 1, "status": "initialized" }

This documentation follows the manual's convention of exporting HYPHAE_DATA_DIR and writing "$D" for it in command examples; every command also accepts an explicit --data-dir <PATH> flag if you would rather not export it.

Three commands worth knowing from day one:

hyphae capabilities --data-dir "$HYPHAE_DATA_DIR"   # effective limits
hyphae status --data-dir "$HYPHAE_DATA_DIR"         # all-engine state: CSN, WAL, pages
hyphae doctor --data-dir "$HYPHAE_DATA_DIR"          # bounded offline diagnosis

Successful results are formatted JSON on stdout; diagnostics go to stderr; the exit status distinguishes failure classes.

Your first SQL statement

Hyphae SQL is deliberately bounded — see SQL for the full picture — but the everyday shapes are ordinary: 

hyphae sql --data-dir "$D" execute \
  --statement 'CREATE TABLE notes (id BIGINT PRIMARY KEY, body TEXT NOT NULL, stars BIGINT)'

hyphae sql --data-dir "$D" execute \
  --statement 'INSERT INTO notes (id, body, stars) VALUES (?, ?, ?)' \
  --parameter 1 --parameter '"first offline note"' --parameter 5

Parameters are canonical JSON scalars in positional order — note the inner double quotes around the string parameter. Every mutation returns a commit receipt: 

{
  "commit": {
    "commit_csn": 3, "commit_lsn": 328055, "durability": "strict",
    "status": "committed",
    "transaction_id": "93646194250034055130955127479421607581",
    "wal_block_digest": "c160758d66..."
  },
  "result": { "rows_affected": 1, "type": "command" }
}

The receipt's fields are the durability evidence the mental model promises:

  • commit_csn — the single commit sequence number this transaction became visible at, shared across every engine.
  • commit_lsn — the write-ahead log position the commit occupies.
  • durability — which of the three classes (strict, group, memory) acknowledged this write; see Transactions and proofs.
  • transaction_id — a stable identity you can resolve later with transaction status if an acknowledgement is ever lost.
  • wal_block_digest — a content digest over the WAL block this commit wrote, part of the tamper-evidence chain the proof system builds on.

Your first structure write

The native keyspace engine (Keyspace) sits alongside SQL in the same directory. Scalars such as strings and counters auto-create on first use: 

hyphae structure --data-dir "$D" set --key session:active --value note-1 \
  --expires-at-micros 4102444800000000
hyphae structure --data-dir "$D" get --key session:active
hyphae structure --data-dir "$D" ttl --key session:active

Your first search query

Search (Search) needs a catalogued collection before it can ingest anything: 

hyphae catalog --data-dir "$D" create-search-collection \
  --database 10 --schema 11 --collection 13 --analyzer 12 \
  --name main.public.note_search --dimension 2

hyphae search --data-dir "$D" provision --collection 13

hyphae search --data-dir "$D" ingest --collection 13 --idempotency-id 1 \
  --documents-json '[{"id":1001,
    "text":"offline search engine with proofs",
    "doc_values":{"category":"note","price":5},
    "vectors":{"exact":[1.0,0.0],"ann":[1.0,0.0]}}]'

hyphae search --data-dir "$D" query --index 23 --query offline --kind term --limit 5

provision creates the physical lexical index and the exact and ann vector indexes for the collection in one step. Document, vector, and idempotency IDs are stable unsigned integers, and repeating an --idempotency-id with identical content is a safe no-op — useful when a script needs to retry ingest without risking a duplicate.

Diagnose before you worry

hyphae doctor --data-dir "$D" runs a bounded offline diagnosis over format, pages, WAL, manifests, blobs, indexes, and recovery authority. It is the first command to run after anything unexpected — an interrupted process, a restore, an environment change — before assuming corruption. It is not an in-place repair tool; see Operations for what to do with its output.

Next steps

  • Read SQL to learn exactly which statement shapes are admitted.
  • Read Keyspace for the full native-structure command set and the minor-6 additions.
  • Read Search for filters, facets, and hybrid retrieval.
  • Read Transactions and proofs to understand durability classes and verifiable proofs before you rely on either.