KAPLA-VOLUME(1)

📦 version 0.4.0, in nixpkgs unstable

💅 kapla-volume — the one where we manage Kapla store volumes

okay so hi bestie 🫶 welcome to KAPLA-VOLUME(1), straight out of the Kapla Manual. this is your little group chat for wrangling Kapla store volumes and honestly? it's giving infrastructure ✨

🌸 SYNOPSIS

kapla volume [COMMAND] …

so the Kapla store persists blocks of encoded content (yes, that's its whole thing 💅). and the commands below? they let you inspect and manage that store. iconic behavior only.

🎀 COMMANDS

  • create [--control=CONTROL_SOCKET] [--maximum-size=MAXIMUM_SIZE] [OPTION]… — make a brand new volume, slay 💖
  • list [--control=CONTROL_SOCKET] [OPTION]… — show me the volumes, all of them, no cap
  • retire [--control=CONTROL_SOCKET] [OPTION]… UUID — retire a volume (it's not gone, it's just… retiring 💅)
  • unlink [--control=CONTROL_SOCKET] [OPTION]… UUID — unlink a volume, bye bestie 👋

🦋 STORE

a kapla store is literally made of:

  • volumes — multiple CBOR sequences of blocks, each identified by UUIDs
  • index — a listing of volumes plus the position of blocks within the volumes, which is what makes block retrieval efficient (main character energy tbh)
psst — the store location gets handed to the serve command with the --data option 🌈

⭐ VOLUMES

volumes are CBOR sequences holding blocks of encoded content. a Kapla store can have a bunch of volumes, and each one is in one of these states:

  • WRITE — blocks get appended here. at any given time there's exactly one volume in this state. one. single. volume. 💀
  • READ_ONLY — this one's for reading blocks, no further blocks get written to it
  • RETIRED — blocks accessed here (both storage and retrieval) get re-appended to the current WRITE volume

volumes have a maximum size (and yes, that max size lives in the index 🎀). if the WRITE volume grows up to the maximum size, it transitions to READ_ONLY and a fresh WRITE volume is created. growth. periodt.

you can move volumes from READ_ONLY to RETIRED using the retire command 🫶

🧚 INDEX

the index keeps a list of blocks and where those blocks sit inside the volumes.

the index is an SQLite3 database, so you can peek at it with the sqlite utility. but — and this is important — when you're manually inspecting or manipulating the index, remember to activate the foreign key pragma so the database constraints actually get enforced, bestie 😭 otherwise you're out here raw-dogging your own data.

like this:

PRAGMA foreign_keys = ON;
SELECT * FROM kapla_volume;

✨ OPTIONS ✨

  • -c CONTROL_SOCKET, --control=CONTROL_SOCKET — the Kapla control socket. when it's absent it resolves as $XDG_STATE_HOME/kapla/kapla.sock, then $HOME/.local/state/kapla/kapla.sock, then /var/lib/kapla/kapla.sock 🦋

💜 COMMON OPTIONS 💜

  • --color=WHEN (absent=auto) — colorize the output. WHEN has to be one of auto, always or never 🌈
  • --help[=FMT] (default=auto) — show this help in the format FMT. FMT must be one of auto, pager, groff or plain. with auto, the format is pager or plain whenever the TERM env var is dumb or undefined 🙈
  • -q, --quiet — be quiet. this takes over -v and --verbosity 🤫
  • -v, --verbose — increase verbosity. repeatable, but more than twice doesn't bring more 💀
  • --verbosity=LEVEL (absent=warning or the KAPLA_LOG_LEVEL env) — be more or less verbose. LEVEL must be one of quiet, error, warning, info or debug. takes over -v 👑
  • --version — show version information ⭐

📚 STANDARDS

🔥 EXIT STATUS

kapla volume exits with:

  1. 0 — on success 🎉
  2. 123 — on indiscriminate errors reported on standard error 😭
  3. 124 — on command line parsing errors 🫠
  4. 125 — on unexpected internal errors (bugs) 💀

🌱 ENVIRONMENT

these environment variables affect how kapla volume runs:

  • KAPLA_LOG_LEVEL — set the log level 💅

👀 SEE ALSO

okay that's the whole page bestie, go be great with it 🫶💖

Kapla 0.4.0 — mwah, that's the version and source, signed off with love from your favorite manual page ✨🎀🦋

📦 where this page comes from