KAPLA(1)

📦 version 0.4.0, in nixpkgs unstable

KAPLA(1) 💅✨

okay so welcome to the Kapla Manual bestie, this is the whole vibe 🫶

🎀 NAME 🎀

kapla — ERIS block store and transport. that's it, that's the whole name, slay.

✨ SYNOPSIS ✨

kapla [COMMAND] …

so like, Kapla is a tool for making content more robustly available over computer networks. it can be used for sharing files. no cap.

it provides a store for blocks, mechanisms for connecting to remote peers, and an interface for encoding and decoding content. it's giving infrastructure icon 👑

💖 COMMANDS 💖

  • decode [--output=OUTPUT] [--socket=ERIS_UNIX_SOCKET] [OPTION]… READ_CAPABILITY — decode content. that's the whole job, she just decodes.
  • encode [OPTION]… [INPUT] — Encode content using ERIS. the main character command fr.
  • fcgi [--port=PORT] [--socket=ERIS_UNIX_SOCKET] [OPTION]… — Serve ERIS blocks and content over HTTP by starting a FastCGI responder. she serves, literally.
  • info [--socket=ERIS_UNIX_SOCKET] [OPTION]… READ_CAPABILITY — Get information from read capability (block size and length of encoded content). the little gossip session 🗣️
  • ls [--socket=ERIS_UNIX_SOCKET] [OPTION]… READ_CAPABILITY — List entries in an encoded ERIS-FS index. window shopping but make it filesystem.
  • peer [COMMAND] … — Manage Kapla peers. your friends, your network, your circle 🫂
  • serve [--data=DATA_DIR] [--socket=ERIS_UNIX_SOCKET] [--state=STATE_DIR] [OPTION]… — Start the Kapla server and make blocks available over TCP/IP and Unix sockets. the moment she steps on stage 🌟
  • sqlite [COMMAND] … — Read blocks from an SQLite database. yes bestie, sqlite, we love a crossover episode.
  • volume [COMMAND] … — Manage Kapla store volumes. the storage organization era 📦

🦋 COMMON OPTIONS 🦋

these apply all over the place, memorize them, they're iconic:

  • --color=WHEN (absent=auto) — Colorize the output. WHEN must be one of auto, always or never. aesthetics are serious business 💅
  • --help[=FMT] (default=auto) — Show this help in format FMT. The value 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. she reads the room.
  • -q, --quiet — Be quiet. Takes over -v and --verbosity. shhh 🤫
  • -v, --verbose — Increase verbosity. Repeatable, but more than twice does not bring more. ok so like diminishing returns bestie, two is the limit that matters.
  • --verbosity=LEVEL (absent=warning or KAPLA_LOG_LEVEL env) — Be more or less verbose. LEVEL must be one of quiet, error, warning, info or debug. Takes over -v. she's got opinions on volume.
  • --version — Show version information. the "who are you" moment 💁‍♀️

🌸 USAGE 🌸

Start a Kapla server that makes blocks available over a Unix socket:

kapla serve

Encode some content:

echo "Hello ERIS!" | kapla encode -
urn:eris:B4AFSFHHUHVPUYLL3V7GEPXI6HE55LY5BJONMMJUNHIQ3ELG5AESVFSC2U4SFHBCM2BIUJXKTEVPEL4TIC5OZ3GKOKSW7XM4RN34R35Q5U

Decode the content:

kapla decode urn:eris:B4AFSFHHUHVPUYLL3V7GEPXI6HE55LY5BJONMMJUNHIQ3ELG5AESVFSC2U4SFHBCM2BIUJXKTEVPEL4TIC5OZ3GKOKSW7XM4RN34R35Q5U
Hello ERIS!

Encode a file.txt:

kapla encode file
urn:eris:B4APR75ZVQDPWSN5H5X5IGWQRYSHENJ5NMSGDSXLP3YBE2A2RRWB2ZC4PGQNWPTJB64SPBHLZXMP6ZYGH24NMF7ZIQH5CXEJRBJXW6XOCU

look at her go 😭 she's literally doing it

🌈 EXIT STATUS 🌈

kapla exits with:

  • 0 — on success. we love a win 🎉
  • 123 — on indiscriminate errors reported on standard error. messy but valid.
  • 124 — on command line parsing errors. you typed it wrong bestie, it happens.
  • 125 — on unexpected internal errors (bugs). not her fault, i promise 💀

🍓 ENVIRONMENT 🍓

These environment variables affect the execution of kapla:

  • KAPLA_LOG_LEVEL — Set the log level. she's listening to her environment, as she should.

🧚 EXAMPLES 🧚

You can connect to a remote ERIS block store via SSH port forwarding. Assuming that a Kapla server is running on the remote host remote:

ssh -L ~/.state/local/eris.sock:~/.state/local/eris.sock user@remote

This will forward connections to the local eris.sock to the remote eris.sock. The kapla encode or decode commands will use the remote store.

ngl that's kind of a flex. tunnel era 🚇✨

👑 STORE 👑

The Kapla store persists blocks of encoded content in multiple CBOR sequences called volumes. Volumes can be removed allowing the store to only keep recently used blocks and operate with bound storage. so like, she forgets on purpose, and that's a feature 💜

See the help on the volume subcommand (kapla volume --help) for more information.

⭐ SEE ALSO ⭐

kapla-decode(1), kapla-encode(1), kapla-peer(1), kapla-serve(1), kapla-volume(1)

the whole friend group fr 🫶

💀 FILES 💀

  • eris.sock — Unix socket used to connect with block store.
  • kapla.sock — Unix socket used to control the Kapla server.

two sockets, two moods, both essential 🔥

🎀 STANDARDS 🎀

Kapla uses the Encoding for Robust Immutable Storage (ERIS) — a scheme for encoding content into uniformly sized and encrypted blocks as well as a short identifier called the read capability. Content can be decoded from the blocks and the read capability.

For more information on ERIS see also:

The Constrained Application Protocol (CoAP) is used for communication between server and frontend as well as to remote peers. See also:

Blocks are stored in CBOR sequences. See also:

the RFC deep dive is real and honestly? obsessed 📚💅

💜 LICENSE 💜

Kapla is Free Software and is available under the terms of the AGPL-3.0-or-later.

free software, free her 🦋

ok that's the whole page bestie, go forth and encode 💖

Kapla 0.4.0 — that's the version, and this was the KAPLA(1) manual, mwah, bye 🎀✨

📦 where this page comes from