# slate-kv-cli
[](https://crates.io/crates/slate-kv-cli)
[](#license)
**A shell for [SLATE](https://github.com/ja7ad/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`](https://crates.io/crates/slate-kv)'s public API; the semantics it exposes are that crate's, and the on-flash format is specified in [`../../docs/specification.md`](../../docs/specification.md).
## Install
```sh
cargo install slate-kv-cli
```
Or from a checkout:
```sh
cargo run -p slate-kv-cli -- stats ./slate_db
```
## Usage
```text
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.
```sh
slate-kv-cli put ./slate_db sensor_1 "23.5 C"
slate-kv-cli get ./slate_db sensor_1
slate-kv-cli del ./slate_db sensor_1
slate-kv-cli stats ./slate_db
```
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.
```sh
slate-kv-cli get ./slate_db sensor_1 \
4242424242424242424242424242424242424242424242424242424242424242
```
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`](https://crates.io/crates/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:
```sh
if val=$(slate-kv-cli get ./slate_db sensor_1 2>/dev/null); then
echo "value: $val"
elif [ $? -eq 2 ]; then
echo "not set yet"
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`
```text
=== 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`](https://crates.io/crates/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](https://github.com/ja7ad/slate/blob/main/LICENSE-MIT) or [Apache-2.0](https://github.com/ja7ad/slate/blob/main/LICENSE-APACHE), at your option.