INFORMANT(1)

📦 version 0.6.0, in arch rolling

👑 INFORMANT(1) — the informant manual, but make it cute 👑

okay so bestie, you know how Arch Linux drops News items and you're supposed to read them before you pacman -Syu and break your whole system? yeah. this is the girl who handles that for you. it's informant, the Arch Linux News reader and pacman hook, and she's literally the main character of your update routine 💅

✨ SYNOPSIS ✨

informant [options] check

informant [options] list [--reverse --unread]

informant [options] read [<item> | --all]

🦋 DESCRIPTION 🦋

informant has three modes of operation, and they're giving very much "three moods, one icon": check, list and read. that's it, that's the vibe.

🎀 COMMANDS 🎀

  • check — checks for unread Arch Linux News items and bails out with an exit status code, and ngl the code is equal to the number of unread items. so zero unread = zero exit = slay. 🙌
  • list — prints out the headlines of the most recent news items (regardless of whether or not they've been read, no judgment). and list has two little options of its own, because she contains multitudes:
    • --reverse — prints the headlines oldest to newest, instead of the default newest to oldest. chronological queen 🕰️
    • --unread — prints the headlines of only the unread items. filtering out the noise, we love to see it.
  • read [<item>|--all] — prints the given news item and marks it as read. <item> can be handed to her as an index (the kind printed by the list command when you don't use the --unread or --reverse options) or as a string matching part of the headline of a news item. and heads up: read will exit with status code 255 if it doesn't have permission to write to the save file. 💀

when you run it with neither <item> nor --all, read goes interactive — it prints all the unread news items from oldest to newest and prompts you about whether you want to keep reading. like a little storytime, but for package news 🧚

  • --all — marks all the most recent news items as read without printing them. efficient. no notes.

🌸 OPTIONS 🌸

these are the global options, and the way they're global is that they can be applied to any of the subcommands. universal icon behavior.

  • -c <cfile>, --config=<cfile> — read configuration from <file>. the configuration and its syntax live down below in CONFIGURATION, keep scrolling bestie 💖
  • -d, --debug — prints the debug messages and, key detail, doesn't make changes to the save file. so you can snoop without consequences 🙈
  • -r, --raw — when printing items, doesn't replace any markup — items get printed exactly as returned by the RSS feed. unfiltered, unbothered, in her raw form ✨
  • -f <file>, --file=<file> — uses <file> as the save location for marking items as read. this is a binary file, fyi.
NOTE: changing the file will not change the file read by the pacman hook, because the pacman hook runs as root. if you want to change that, you gotta do it manually by editing /usr/share/libalpm/hooks/00-informant.hook 👑
  • -p <pager>, --pager=<pager> — uses <pager> to display news items. this option overrides the $INFORMANT_PAGER environment variable. she said my choice, actually 💅
  • --no-cache — doesn't consider the cache (/var/cache/informant/) when fetching feeds (this could likely result in slower feed fetching but more up to date results). using this may be helpful to verify issues running informant due to the cache. slower but fresher, the tradeoff is real 😭
  • --clear-cache — empties the cache directory (/var/cache/informant/) before fetching the feed(s). clean slate energy 🫧
  • --clear-readlist — empties the save file of read news items (/var/lib/informant.dat by default), which means any previously read news items returned in the feed will need to be read again. the news feed only returns a set amount of files, and over time there may end up being items in the save file that are no longer returned when fetching the feed — this option can be used to clean up the save file. basically it's a little reset button 🎀

and like, by clearing the save file and then marking everything as read, you effectively remove all the old items from the save file:

informant --clear-readlist read --all
  • -h, --help — prints the help and exits. your safety net 🫶
  • -V, --version — prints the version information and exits. identity check ⭐

🌈 ENVIRONMENT 🌈

  • INFORMANT_PAGER — if $INFORMANT_PAGER is set, its value will be used as the name of the program used to display news items. she'll respect it, but --pager overrides it (that's a global-option thing up above, iykyk).

💜 CONFIGURATION 💜

so informant can be configured to check multiple feeds instead of just the Arch Linux News feed — whether having it do so is actually useful or not is left up to the user 💀. informant will check for an informantrc.json file in a few places. it checks in this order:

  • CLI provided option (cfile)
  • $HOME/.informantrc.json
  • $XDG_CONFIG_HOME/informantrc.json
  • /etc/informantrc.json
  • for each directory $d in $XDG_CONFIG_DIRS it will look for $d/informantrc.json
NOTE: IF you want the configuration file to be used in the pacman hook, make sure to use a save location that will be accessible to informant when running as root/sudo. 🔥

🧚 Configuration Syntax 🧚

the syntax of informantrc.json is a JSON object containing one key: feeds, which is a list describing the feeds you want informant to check. each feed is represented as a JSON object with the following keys:

  • name (optional) — used to show which feed each news item is from. a little label, a little name tag 🏷️
  • url (required) — the feed URL. no url, no feed, them's the rules.
  • title-key (optional) — defaults to title, the key used to reference the news item title in the feed
  • body-key (optional) — defaults to summary, the key used to reference the news item body in the feed
  • timestamp-key (optional) — defaults to published, the key used to reference the news item date in the feed

for example, the below informantrc.json will configure informant to check the Arch Linux News feed as well as the Arch Linux 32 News Feed:

{
    "feeds": [
        {
            "name": "Arch News",
            "url": "https://archlinux.org/feeds/news",
            "title-key": "title",
            "body-key": "summary",
            "timestamp-key": "published"
        },
        {
            "name": "Arch32 News",
            "url": "https://bbs.archlinux32.org/extern.php?action=feed&fid=12&type=atom",
            "title-key": "title",
            "body-key": "summary",
            "timestamp-key": "updated"
        }
    ]
}

⭐ AUTHOR ⭐

Bradford Smith <https://github.com/bradford-smith94> — the icon who built her 💖

🎀 LICENSE 🎀

MIT. periodt.

💀 BUGS 💀

please report bugs at: <https://github.com/bradford-smith94/informant/issues>. she's not perfect, she's just iconic — help her out 🫶

🌸 SEE ALSO 🌸

alpm-hooks(5) — go read the sister page, she's also important

and that's the whole manual, bestie!! this version is informant-v0.6.0, dated 02 SEPTEMBER 2024, and it ate, no cap 🍓✨ mwah 💋

📦 where this page comes from