CLI Reference

The memkv binary bundles every operator command: drive init, server start, docs site, admin client, offline drive maintenance. This page covers every subcommand and flag.

memkv [GLOBAL OPTIONS] <COMMAND> [ARGS]

Commands:
  setup    Initialize drives and generate config (outputs YAML to stdout)
  start    Start the server
  doc      Serve the bundled MemKV documentation over HTTP
  admin    Query the admin HTTP endpoint of one or more running memkv servers
  drive    Offline drive maintenance (server stopped); see the `drive` section

Global

memkv <command> --help prints the same help that ships with the binary, generated from the same source as this page.

setup

Format the listed NVMe drives in JBOF mode and emit a working config.yaml on stdout. Logs go to stderr so you can pipe stdout straight into a config file.

sudo memkv setup \
  --drives /dev/nvme0n1 /dev/nvme1n1 /dev/nvme2n1 \
  --rdma mlx5_0 \
  | sudo tee /etc/memkv/config.yaml

Behavior

• Logs each drive's model, optimal I/O size, and max_sectors_kb to stderr before formatting.
• Picks the bounce-buffer pool size at 50% of available system memory (minimum 1 GB) and writes that into memory.max_size.
• Without --force, fails fast on any drive that already contains memkv data, naming the first offender.
• The generated YAML always sets storage.mode: direct. Other storage modes (file, memory) are reachable only by hand-editing the YAML — see Configuration.

Exit codes

start

Run the memkv server: license verification, RDMA bring-up, storage recovery, data + admin listeners.

sudo memkv start --config /etc/memkv/config.yaml

Behavior

• Refuses to start on Linux kernels older than 6.8 (io_uring and RDMA features used by memkv are unstable on earlier kernels).
• Validates that the requested bounce-buffer pool fits in either free hugepages or 80% of available system memory, and prints a remediation hint (sysctl -w vm.nr_hugepages=…) if it doesn't.
• Brings up RDMA via the device named in rdma.device. If the device is missing or the QP setup fails, the server logs an error, sets memkv_rdma_active=0, and continues with an in-process memory pool — useful for development, never for production traffic.
• Recovers existing blocks from the configured drives on startup; absence of prior data is logged and not an error.
• Listens for SIGINT and SIGTERM and flushes storage metadata on shutdown.

Exit codes

doc

Serve the documentation site bundled into the binary. The site is the same Fumadocs build that ships at docs.min.io/memkv, packed into the binary as zstd-compressed assets at release time.

memkv doc

The server binds to an ephemeral loopback port; the resolved URL is logged on startup (http://127.0.0.1:<port>/). If the binary was built without docs/website/out/ on disk, this command serves a placeholder explaining how to rebuild.

admin

Query the admin HTTP endpoint of one or more running memkv servers. All routes are versioned under /v1/.

memkv admin [--servers <URLS>] <subcommand> [SUBCOMMAND ARGS]

Server resolution

Targets are resolved in this order, first match wins:

1. --servers <URLS> (short -s) — comma-separated list. Whitespace and empty entries are stripped.
2. $MEMKV_SERVERS environment variable, same comma-separated format.
3. Fallback: http://127.0.0.1:9901.

Bare host:port entries are accepted; http:// is assumed. Use explicit https:// URLs against TLS-enabled servers (network.tls_cert + network.tls_key).

export MEMKV_SERVERS="coe02:9901,coe04:9901"
memkv admin status

Subcommands

admin status flags

admin drives failed flags

admin drives reset flags

Admin HTTP API

memkv admin wraps the same HTTP endpoints exposed by every server at 0.0.0.0:9901 (port + 1 from the data plane). All routes are versioned under /v1/. HTTPS is served when network.tls_cert and network.tls_key are configured; otherwise plain HTTP. Use the curl examples below from any tool that doesn't bundle the memkv binary (Helm hooks, external monitors).

curl http://localhost:9901/v1/drives/failed

[
  {
    "device_id": 2,
    "failure_count": 3,
    "first_failed_at": 1738800000,
    "last_failed_at": 1738810000,
    "blacklisted": false
  }
]

Reset BLKDISCARDs the drive and re-initializes the superblock, journal, and B+ tree. The drive rejoins the active pool after reset. By default the data region is left to BLKDISCARD; pass ?secure=true to additionally zero-fill it, at the cost of write time proportional to drive capacity.

curl -X POST http://localhost:9901/v1/drives/2/reset
curl -X POST 'http://localhost:9901/v1/drives/2/reset?secure=true'

Exit codes

The CLI continues querying remaining servers after an error — it surfaces all failures in one run and only flips the exit code at the end.

drive

Offline drive maintenance — operates on a drive directly, with the server stopped. For online resets against a running server, use memkv admin drives reset <device_id> instead.

memkv drive reset <PATH> [--secure]

Reads the drive's existing superblock to recover its device_id and the JBOF's num_devices, then wipes the superblock, journal, B+ tree, and bitmap regions before re-initialising them. Operators do not need to track the device index — the drive carries it. If the primary superblock is unreadable, the mirror is consulted before failing.

sudo memkv drive reset /dev/nvme2n1
sudo memkv drive reset /dev/nvme2n1 --secure

drive verify

Read-only integrity check of a single drive. Never writes — safe to run any time the server is stopped.

memkv drive verify <PATH> [--quick] [--json]

It validates, in order:

• the superblock and its end-of-device mirror (CRC + cross-check);
• every B+ tree page against its stored CRC, sweeping the region directly rather than following tree pointers, so a corrupt page cannot hide the entries beyond it;
• the journal, replayed on top of the tree when the drive was not cleanly shut down (exactly as the server does on an unclean restart), so a post-crash drive is not reported as corrupt;
• the allocation bitmap against the slots the index actually references — leaked slots (wasted space) and missing bits (an allocator hazard);
• unless --quick, every stored block's CRC32, read back from the data region. This is the only bit-rot detector, since the server's verify_on_read is off by default.

sudo memkv drive verify /dev/nvme2n1
sudo memkv drive verify /dev/nvme2n1 --quick --json

Exit code is 0 when the drive is clean and 1 when any uncorrected error remains (the message points you at drive fsck --repair).

drive fsck

Runs the same checks as verify. Without --repair it is a dry run that only reports what it would fix (like xfs_repair -n). With --repair it rewrites the metadata to restore consistency.

memkv drive fsck <PATH> [--repair] [--quick] [--json]

Repair rebuilds the B+ tree from the surviving entries (so corrupt pages can never be read again), reconciles the bitmap with that rebuilt index, resets the journal, and marks the drive cleanly shut down.

sudo memkv drive fsck /dev/nvme2n1            # dry run — report only
sudo memkv drive fsck /dev/nvme2n1 --repair   # apply repairs

drive health

Offline health snapshot of a drive — model, capacity, fill, clean-shutdown state, and the on-superblock failure registry. Reads only metadata; it does not scan the data region.

memkv drive health <PATH> [--json]

sudo memkv drive health /dev/nvme2n1
sudo memkv drive health /dev/nvme2n1 --json

Environment variables

Default ports

The data port carries the entire TCP wire protocol — control, RDMA bootstrap, and inline-bulk PUT/GET. Admin always lives at address + 1.

On macOS the binary does not expose RDMA — RDMA / JBOF / hugepages aren't compiled in there — but the TCP listener still binds on address, so the client targets the same address it would on Linux.