slate-kv-cli
A shell for SLATE databases. Read, write, delete and inspect a store from the command line — for debugging a device, scripting a provisioning step, or checking what a running application actually persisted.
A thin wrapper over slate-kv's public API; the semantics it exposes are that crate's, and the on-flash format is specified in ../../docs/specification.md.
Install
Or from a checkout:
Usage
slate-kv-cli <SUBCOMMAND> <DB_DIR> [ARGS...]
get <db_dir> <key> [hex_key] Read the value for a key
put <db_dir> <key> <val> [hex_key] Write a key/value pair and commit
del <db_dir> <key> [hex_key] Delete a key and commit
stats <db_dir> [hex_key] Show database state and session metrics
help Show usage
<db_dir> is the directory holding data.bin and counter.bin — the same path you passed to Db::open. It is created if it does not exist, so a typo in the path yields a new empty database rather than an error.
Every command opens the database with Options::default() — a 4 MiB arena, b_commit 8, automatic batch sizing, the Pi energy profile, and full fsync durability. There is no flag to change any of those; a store created with a different capacity or key count should be opened by a program that passes matching Options.
Both mutating commands go through slate-kv's durable entry points, and dropping the Db at process exit performs one final commit. That final commit is best-effort: its error is discarded, so an I/O failure at drop time still exits 0. In practice a 0 exit means the write reached flash, but if you need that guaranteed rather than typical — an unattended provisioning script, say — verify by reading the key back in a separate invocation rather than trusting the exit status alone.
The hex_key argument
Every subcommand takes an optional trailing 64-character hex string: the 32-byte root key the database was created with.
Omit it and the CLI uses the all-0x42 development key — convenient for local testing, and the reason you should not use that key for anything real.
Two behaviours to be aware of. Anything that is not exactly 64 hex characters is silently ignored and the default key is used instead — a typo'd or truncated key does not produce a complaint, it produces a mount failure. And a wrong key does not report "wrong password": the AEAD tag check fails and you get a tamper or mount error. That is correct for an authenticated store — it genuinely cannot distinguish "wrong key" from "altered data" — but it means a mount failure is always worth double-checking against the key you passed before concluding the data was attacked.
Note also that the key appears in your shell history and in ps output. For anything beyond development, prefer a program that reads the key from a keystore via slate-kv's KeySource::File or KeySource::Env, neither of which this CLI exposes.
Exit codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Usage error, open failure, or operation failure |
| 2 | get only: key not found |
The distinct 2 lets scripts branch on absence without parsing stderr:
if val=; then
elif [; then
fi
get prints the value to stdout and nothing else; all diagnostics go to stderr. Values are printed with lossy UTF-8 conversion, so binary values do not round-trip through the shell — a value containing invalid UTF-8 comes back with replacement characters, silently. Keys and values are taken as raw argument bytes, so there is no escaping mechanism either.
stats
=== Persistent Database State ===
Path: ./slate_db
Epoch: 3
Acked Seq: 1841
Next Seq: 1842
Active Keys: 512
Security Mode: BestEffortRollback
=== Current Session Metrics ===
Commits: 1
Wakes: 1
User Bytes: 0
GC Bytes: 0
Parity Bytes: 0
Ckpt Bytes: 0
Erases: 0
The first block is read from flash and is the real persisted state. The second block is per-process: the CLI opens the database, does one operation, and exits, so the counters describe that one invocation — not the history of the store. They are useful for seeing what a single command costs, not for auditing a deployment. (SLATE keeps no cumulative on-flash counters, so there is nothing the CLI could print instead.)
Security Mode reports what the store can actually guarantee. On an ordinary filesystem it says BestEffortRollback: the log is tamper-evident, but a file-backed counter cannot stop someone restoring an older data.bin + counter.bin pair. Full requires a hardware anchor such as an eFuse or TPM counter.
Scope
Deliberately small: no shell mode, no range scans (the engine has no iteration API), no import/export, no config file, no compact, no seal_epoch, and no way to set any Options field. It exists to inspect and poke a store. For anything richer, use slate-kv directly — this CLI is about 150 lines over that crate's public API, and is a fine template to copy.
License
Dual-licensed under MIT or Apache-2.0, at your option.