Command-line interface

Commands

Command	Purpose
`init`	Open or initialize the directory
`put`	Replace one collection/key record
`get`	Write the exact raw value to stdout
`delete`	Delete a record idempotently
`scan`	Return an ordered bounded range as JSON
`batch`	Apply a JSON array atomically
`stats`	Print sequence, record, and storage-budget counters
`flush`	Synchronously checkpoint and compact

Use zeedb <command> -h for flags. Flags follow the command. Use zeedb serve for an authenticated HTTP server. There is no start alias, SQL shell, or sync command.

Database selection

Every command accepts --data, defaulting to ./data:

zeedb put --data ./data --collection users --key 1024 --value Ada
zeedb get --data ./data --collection users --key 1024

The CLI opens the embedded engine directly. It cannot attach to a directory already open by an application or another CLI process.

Scan a range

zeedb scan --data ./data --collection users --start 1000 --end 2000 --limit 20

The start is inclusive and the end exclusive. The default CLI limit is 100, with a configured default maximum of 1000 records. Omitting --end means an unbounded end; explicitly passing an empty end means an empty range.

scan emits JSON with base64-encoded byte fields and commit versions. get emits the raw stored bytes without a newline.

Binary input

zeedb put --data ./data --collection binary --key AP8= --value AAEC --base64

With --base64, the key, value, start, and end flags are decoded as base64. Collection names remain strings.

Atomic JSON batches

Save this as mutations.json:

[
  { "Collection": "users", "Key": "MTAyNA==", "Value": "QWRh" },
  { "Collection": "users", "Key": "MTAyNQ==", "Delete": true }
]

zeedb batch --data ./data --file mutations.json

Byte fields are always base64 in batch JSON. A delete must not include a nonempty value. Unknown JSON fields, extra documents, malformed base64, and files above 4 MiB are rejected. The engine’s encoded batch limit also applies.

Durability and timeouts

Durable mode is the default. --relaxed skips per-commit sync and can lose acknowledged writes after a crash; normal CLI shutdown still syncs the WAL.

--timeout defaults to 30s. A deadline cannot undo a commit after append begins, and cannot interrupt mutex waits or blocked OS I/O.

Errors are written to stderr with exit code 1. Successful writes produce no output; stats, scan, get, and init return their corresponding results.