LITTERBOX(1)

📦 version 1.9, in nixos 26.05, nixpkgs unstable

💖 LITTERBOX(1) — like, the IRC logger manual, bestie 💖

okay so this is litterbox, from the General Commands Manual section, and she's literally the moment. sit down, grab a strawberry 🍓, and let's get into it.

✨ NAME ✨

litterbox — an IRC logger. that's it, that's the vibe. she logs. 💅

🌸 SYNOPSIS 🌸

litterbox [-Qqv] [-N network] [-U url] [-c cert] [-d path] [-h host]
          [-j join] [-k priv] [-l limit] [-n nick] [-p port] [-t trust]
          [-u user] [-w pass] [config ...]
litterbox -i | -m [-d path]
litterbox -b path [-d path]

🦋 DESCRIPTION 🦋

the litterbox daemon logs your IRC (over TLS, we're not messy) activity into a database, and then you can query that database with scoop(1). it's giving archive icon. 🔥

what gets recorded, you ask? messages, notices, joins, parts, quits, kicks, nick changes, topic changes, bans and unbans — all of it, in the database. and the contents of messages are indexed for full-text search, so you can actually find things later. obsessed.

you can hook the litterbox daemon up to the pounce(1) IRC bouncer right alongside your regular clients, and that gives you central logging plus a simple search query interface with -q. chef's kiss. 👑

okay important: the database must be initialized with -i. no -i, no database, no vibes.

if the database format has changed, it gets migrated automatically when litterbox starts — or you can migrate it explicitly with -m. live backups of the database can be made with -b. and yes, instances of litterbox connected to different IRC networks will share the same database. one database, many networks, main character energy. ✨

options can be loaded from files listed on the command line. files are searched for in $XDG_CONFIG_DIRS/litterbox unless the path starts with ‘/’, ‘./’ or ‘../’. each option goes on its own line, and lines beginning with ‘#’ are ignored (comments, we respect them). the options are listed below following their corresponding flags, iykyk.

the arguments are as follows:

💅 the arguments, in order, no skipping 💅

  • -N name | network = name — sets the network name to be used if the server doesn't send RPL_ISUPPORT NETWORK. the default is the server hostname.
  • -Q | public-query — enables the public search query interface. this lets anyone perform searches in private messages to litterbox. search results are limited to channels on the current network.

searches use the full-text search index. the searchable columns are channel, nick, user, target, message.

  • -U url | scooper-url = url — sets the base URL of a scooper(1) instance used to construct links to full search results in response to the search query interface enabled by -Q or -q.
  • -b path — performs a live database backup to path and exits. ⚠️ this operation requires SQLite version 3.27.0 or newer, so check your version bestie.
  • -c path | cert = path — loads the TLS client certificate from path and authenticates with SASL EXTERNAL, also known as CertFP. the path is searched for in the same manner as configuration files. if the private key is in a separate file, it's loaded with -k.
  • -d path | database = path — sets the path to the database file. see “FILES” for the default paths.
  • -h host | host = host — connects to host.
  • -i — initializes the database and exits. the required first step, periodt.
  • -j chan | join = chan — joins the comma-separated list of channels chan.
  • -k path | priv = path — loads the TLS client private key from path. the path is searched for in the same manner as configuration files.
  • -l limit | limit = limit — limits the number of results in the search query interface enabled by -Q or -q. the default limit is 10.
  • -m — migrates the database to the latest format and exits.
  • -n nick | nick = nick — sets the nickname to nick. the default nickname is “litterbox”. iconic name, no notes.
  • -p port | port = port — connects to port. the default port is 6697.
  • -q | private-query — enables the private search query interface. when connected to pounce(1), this lets the user private message their own nickname with search queries. search results are limited to the current network.

searches use the full-text search index. the searchable columns are channel, query, nick, user, target, message.

  • -t path | trust = path — trusts the self-signed certificate loaded from path and disables server name verification. ⚠️ that's the whole point of it, so like, know what you're doing. the path is searched for in the same manner as configuration files.
  • -u user | user = user — sets the username to user. the default username is the same as the nickname.
  • -v | verbose — writes sent and received IRC messages as well as SQL INSERT statements to standard error. very "let me see everything" of her. 🙈
  • -w pass | pass = pass — logs in with the server password pass.

🎀 FILES 🎀

$XDG_CONFIG_DIRS/litterbox

configuration files are searched for first in $XDG_CONFIG_HOME, usually ~/.config, followed by the colon-separated list of paths $XDG_CONFIG_DIRS.

$XDG_DATA_DIRS/litterbox/litterbox.sqlite

the database file is searched for first in $XDG_DATA_HOME, usually ~/.local/share, followed by the colon-separated list of paths $XDG_DATA_DIRS.

~/.local/share/litterbox/litterbox.sqlite

the most likely default path of the database file. like, if you had to guess, it's this one. 🫶

🌈 EXAMPLES 🌈

configuration on the command line, live and direct:

litterbox -Q -h irc.example.org -j '#example'

configuration in a file, cozy and organized:

host = irc.example.org
join = #example
public-query

🧚 SEE ALSO 🧚

full-text Query Syntax: https://www.sqlite.org/fts5.html#full_text_query_syntax

go read them, they're literally right there. ✨

👑 STANDARDS 👑

⭐ Extensions ⭐

the litterbox daemon implements the causal.agency/consumer and causal.agency/passive vendor-specific IRCv3 capabilities offered by pounce(1). fancy. 💅

💜 AUTHORS 💜

June McEnroe <june@causal.agency> — the legend herself.

💀 BUGS 💀

send mail to ⟨list+litterbox@causal.agency⟩ or join #ascii.town on irc.tilde.chat. we don't bite, fr fr. 🫶

and that's the whole page, bestie — brought to you by the Debian squad, dated April 3, 2021. go log some IRC and slay. 🦋💖✨

📦 where this page comes from