INFORMANT(1)

NAME
informant - An Arch Linux News reader and pacman hook.

SYNOPSIS
informant [options] check informant [options] list [--reverse --unread] informant [options] read [<item> | --all]

DESCRIPTION
informant has three modes of operation: check, list and read.

COMMANDS

check
    Check for unread Arch Linux News items and exit with status code equal to the number of unread items.

list
    Print out the headlines of the most recent news items (regardless of whether or not they have been read). list also can take two options of its own:

    --reverse
        Print the headlines oldest to newest (instead of newest to oldest).

    --unread
        Print the headlines of only unread items.

read [<item>|--all]
    Print the given news item and mark it as read. <item> can be given as an index (printed by the list command without the --unread or --reverse options) or as a string matching part of the headline of a news item. read will exit with status code 255 if it does not have permission to write to the save file. When run without <item> or --all read will run interactively printing all unread news items from oldest to newest prompting the user if they want to continue reading.

    --all
        Mark all the most recent news items as read without printing them.

OPTIONS
These are the global options which can be applied to any of the subcommands.

-c <cfile>, --config=<cfile>
    Read configuration from <file>. Configuration and syntax can be found below in CONFIGURATION.

-d, --debug
    Print the debug messages and don't make changes to the save file.

-r, --raw
    When printing items do not replace any markup, items will be printed exactly as returned by the RSS feed.

-f <file>, --file=<file>
    Use <file> as the save location for marking items as read. This is a binary file. 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 can do so manually by editing /usr/share/libalpm/hooks/00-informant.hook

-p <pager>, --pager=<pager>
    Use <pager> to display news items. This option overrides the $INFORMANT_PAGER environment variable.

--no-cache
    Do not 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.

--clear-cache
    Empty the cache directory (/var/cache/informant/) before fetching the feed(s).

--clear-readlist
    Empty the save file of read news items (/var/lib/informant.dat by default), this will mean that 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 cleanup the save file. 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
    Print the help and exit.

-V, --version
    Print the version information and exit.

ENVIRONMENT

INFORMANT_PAGER
    If $INFORMANT_PAGER is set it's value will be used as the name of the program used to display news items.

CONFIGURATION
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 will check 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 containig on key: feeds that 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

    url(required)
        the feed URL

    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>

LICENSE
MIT.

BUGS
Please report bugs at: <https://github.com/bradford-smith94/informant/issues>.

SEE ALSO
alpm-hooks(5)