mastorss/man/mastorss.1.adoc

mastorss(1) Manual Page

NAME

mastorss - Another RSS to Mastodon bot.

SYNOPSIS

mastorss [--help|--version] <profile>

DESCRIPTION

mastorss reads RSS feeds and posts the items via the Mastodon API. Does not support Atom at the moment.

OPTIONS

--dry-run

Do everything like normal, but don’t post anything and don’t update the config file. The initial config file is still created, if the profile doesn’t exist. The interval between posts is set to 1 second.

--help

Show a short help message.

--version

Show version, copyright and license.

USAGE

Put watchwords.json into ${XDG_CONFIG_HOME}/mastorss/. Launch with profile name. The first occurence of every watchword in an RSS item will be turned into a hashtag (unless add_hashtags is set to false). For profile-specific watchwords see the example in watchwords.json. In the first run only the newest entry is posted unless keep_looking is set to true.

The profile is the identifier for a feed and can’t be named "global".

Example 1. Launch mastorss with the profile “example”.

% mastorss example

Configuration

If the profile does not exist yet, a configuration will be created interactively and then saved to ${XDG_CONFIG_HOME}/mastorss/config-<profile>.json.

access_token

The API token needed to communicate with the Mastodon API on the instance you’re using to post.

append

This string will be appended to every post.

feedurl

The URI of the source feed.

fixes

Array of regular expressions that should be deleted from the text. Applies to RSS descriptions (before the HTML is stripped). For information about the syntax see perlre(1).

instance

Hostname of the instance you’re using to post.

keep_looking

If true, keep looking for new items after encountering the first that was already posted. If you set this in the beginning, the whole feed will get posted, since all items are new.

interval

Time to wait between posts.

max_size

Maximum number of characters a post can have.

skip

Array of strings with titles of posts that should be skipped. Matched against the beginning of the title; this means: “Good Day” will match “Good Day in Happytown” but not “A Good Day in Happytown”.

titles_as_cw

If true, the title will be used as the subject (also known as spoiler warning or content warning) of the post.

titles_only

If true, only post titles, no descriptions.

replacements

Object with a list of regular expressions and replacements. Applies to posts (after the HTML is stripped), subjects and links, but not to the string in append. For information about the syntax see perlre(1).

add_hashtags

If true, replace words with hashtags according to watchwords.json.

EXAMPLES

Configuration file

{
    "example" :
    {
        "access_token" : "123abc",
        "append" : "#bot",
        "feedurl" : "https://example.com/feed.rss",
        "fixes" :
        [
            "delete this",
            "<p>[Rr]ead more(\.{3}|…)</p>"
        ],
        "instance" : "newsbots.eu",
        "interval" : 600,
        "keep_looking" : false,
        "max_size" : 500,
        "skip" :
        [
            "If the title starts with this, skip it",
            "Skip me too!"
        ],
        "titles_as_cw" : true,
        "titles_only" : false,
        "replacements" :
        {
            "apple" : "strawberry",
            "(chest|wal)nut" : "hazelnut"
        }
    }
}

PROTOCOL SUPPORT

Currently only HTTP and HTTPS are supported.

PROXY SERVERS

Since mastorss is built on libcurl, it respects the same proxy environment variables. See curl(1), section ENVIRONMENT.

Example 2. Tunnel connections through tor.

% ALL_PROXY="socks4a://[::1]:9050" mastorss example

FILES

Configuration file directory

${XDG_CONFIG_HOME}/mastorss/

${XDG_CONFIG_HOME} is usually ~/.config.

ERROR CODES

Code	Explanation
1	No profile specified.
2	Network error.
3	File error.
4	Mastodon API error.
5	JSON error, most likely the file is wrongly formatted.
6	Feed parse error. Usually the type of feed could not be detected.
9	Unknown error.

DEBUGGING

Define the variable MASTORSS_DEBUG to enable debug output.

Example 3. Debug mastorss while using the profile “example”.

% MASTORSS_DEBUG=1 mastorss example

REPORTING BUGS

Bugtracker: https://schlomp.space/tastytea/mastorss/issues

E-mail: tastytea@tastytea.de

SEE ALSO

perlre(1), curl(1), crontab(1), crontab(5)