Invocation
zeedb <serve|init|put|get|delete|scan|batch|stats|flush> [flags]Flags follow the command. Unexpected positional arguments are rejected. Use <command> -h for help; help exits successfully. Errors go to stderr and exit 1.
Flag reference
Direct local commands share these flags, although each operation uses only its relevant inputs. serve has the separate flags listed below. Passing a flag does not imply the chosen operation uses it.
| Flag | Default | Meaning |
|---|---|---|
--data | ./data | Dedicated database directory |
--collection | empty | Collection required by record/scan commands |
--key | empty | Key for put/get/delete |
--value | empty | Value for put; empty is valid |
--start | empty | Inclusive scan start |
--end | omitted | Exclusive scan end; omitted differs from explicitly empty |
--limit | 100 | CLI scan count; engine maximum defaults to 1000 |
--base64 | false | Decode key/value/start/end flags as base64 |
--relaxed | false | Skip per-commit sync; close still syncs |
--file | empty | JSON array input file for batch |
--timeout | 30s | Context duration for context-aware operation work |
The database is opened and recovered before the CLI creates its operation context. --timeout therefore does not impose a deadline on Open, and cannot interrupt blocked OS I/O or lock waits. Stats and Close do not accept contexts at all.
Only durability is exposed as an engine option by the CLI. Custom size budgets require a Go program using Options.
Output contracts
| Command | stdout on success |
|---|---|
init | Initialized followed by the selected path |
put, delete, batch, flush | No result output |
get | Exact raw value bytes; no added newline |
scan | Indented JSON array of records |
stats | Indented JSON object |
Successful output can still be followed by a close failure and nonzero exit. Shell automation should check exit status, not just the presence of stdout.
Scan JSON
[{ "Key": "MTAyNA==", "Value": "QWRh", "Version": 1 }]This represents key 1024, value Ada, and commit version 1. The byte fields are base64 because their Go type is []byte, not because the engine requires JSON/base64 storage internally.
Stats JSON
The field names are sequence, records, data_bytes, memtable_bytes, wal_bytes, and sstable_records. Their values are accounting counters described in observability.
Server flags
zeedb serve opens one directory and listens for authenticated HTTP requests.
| Flag | Default | Meaning |
|---|---|---|
--data | ./data | Database directory; default durable engine options |
--listen | 127.0.0.1:8080 | TCP listen address |
--tls-cert | empty | PEM certificate file; requires --tls-key |
--tls-key | empty | PEM private key file; requires --tls-cert |
Set ZEEDB_TOKEN to a random secret of at least 32 bytes. There is no token CLI
flag, unauthenticated mode, CORS flag, or remote attachment mode for local
commands. See HTTP server for endpoint contracts and
local/hosted examples. Only serve recognizes these transport flags.
Batch input
--file reads a file, not stdin. The input must be one JSON array within 4 MiB and without unknown object fields or trailing JSON documents. The engine’s smaller encoded payload/count limits apply after decoding.
Byte fields always use base64 in this JSON format; --base64 does not toggle batch JSON encoding. A nonempty Value on a delete is invalid.
The current Go decoder also accepts JSON null as a nil mutation slice, producing
an empty no-op batch. Prefer an explicit [] for an intentional empty batch;
neither form creates a commit, checkpoint marker, or synchronization cursor.
Shell quoting
For portable examples across shells, prefer simple values or a batch file. Quoting JSON on a command line depends on the shell’s native argument handling. A file avoids treating JSON quotes as shell syntax.
Windows PowerShell byte-input example using a built binary:
.\zeedb.exe put --data .\data --collection binary --key AP8= --value AAEC --base64
if ($LASTEXITCODE -ne 0) { throw 'write failed' }Do not assume a newline-delimited get result or parse stderr as a structured protocol. Direct CLI commands do not attach to a running server. Use the HTTP API while zeedb serve owns the directory. No stdin pipeline protocol is supplied.