CROSSBOW(1)              General Commands Manual (urm)             CROSSBOW(1)

NAME
     crossbow ? The minimalist feed aggregator

SYNOPSIS
     crossbow [-cDdqVv] [-i] identifier
     crossbow -h

DESCRIPTION
     crossbow is simple RSS/Atom feed aggregator, designed to be invoked
     periodically via cron(8).

     The feeds to be monitored are specified in the crossbow.conf(5)
     configuration file.  Each feed must declare a URL that is checked for new
     entries upon invocation, and is associated with a handler that determines
     how entries are processed.

     The available handlers are:

     print  Prints a textual representation of each new entry to stdout(3).

            This handler is intended as a way to turn entries into email,
            since the output of a cron(8) job is normally mailed to the owner
            of the crontab(5).

     exec   Handle new entries by means of a subprocess.

            This handler allows to execute a specialized data scraper for each
            processed entry.  The subprocess can be parametrised with various
            entry properties, such as the title and the link to the content.

     pipe   Like exec, but the content is made available to the subprocess by
            means of a pipe(2), so it can be handled regardless of the size.

            This handler allows to process feeds that deliver a copious amount
            of content.

     After each entry has been processed according to the corresponding feed
     handler, the set of their identifiers is persisted on the filesystem, so
     that they are marked as seen for the next invocation.  The entries that
     could not be handled successfully (i.e. the subprocess failed) will be
     processed again on the next round.

OPTIONS
     -c      Catch up, marking new items as seen without processing them.  The
             effect is the same as -D, but feeds configured with the print
             handler are silenced too.

     -D      Do not execute subprocesses for feeds configured with the exec or
             pipe handlers.

     -d      Do not mark processed items as seen.

     -h      Print help text and exit.

     -i identifier
             Only fetch the feed identified by identifier.  The identifier can
             be equivalently supplied as first argument.  This flag is useful
             to escape a feed name that starts with a hyphen.

     -q      Quiet mode.  Set the verbosity level to zero, suppressing
             notifications except for warnings and fatal errors.

     -V      Print version and exit.

     -v      Increase verbosity level.  This option can be supplied multiple
             times for additional verbosity.

FILES
     ~/.crossbow.conf
           The configuration file.  See crossbow.conf(5).

     ${XDG_CONFIG_HOME}/crossbow.conf
           Alternative configuration file, honored if ~/.crossbow.conf is not
           found.

     ~/.config/crossbow.conf
           Alternative configuration file, honored if none of the above is
           found.

     ~/.crossbow
           Path for the persistence directory, that is where crossbow will
           store the set of seen entry identifiers for each feed.  The
           directory is created if it does not exist.  A different path for
           the persistence directory can be specified in the configuration
           file.  See crossbow.conf(5)

EXIT STATUS
     crossbow exits with 0 on success, and with 1 in case of failed feed
     retrieval or failed entry processing.

EXAMPLES
     See crossbow-cookbook(7).

SEE ALSO
     crossbow-format(5), crossbow.conf(5), crossbow-cookbook(7), cron(8)

AUTHORS
     Giovanni Simoni <dacav@fastmail.com>

BUGS
     Depending on the installed version of libcurl, a file descriptor might
     leak to the subprocesses (FD_CLOEXEC bit not set).

                              September 14, 2021