A CLI php script that can discover and collect Mastodon accounts from the profiles directories and-or local timelines of a defined set of Mastodon instances, and make a «bot» account it may control on each of the other instances follow them.

pezcurrel d470a6253a Updated to script’s help text as it is in commit 45d295b (correct) 2 weeks ago
README.md d470a6253a Updated to script’s help text as it is in commit 45d295b (correct) 2 weeks ago
TODO 2f5c71be15 Marked “make "profile directories" scan optional too” as done, added an entry 2 weeks ago
brigitta 45d295b6d2 Updated help text for “follow option” 2 weeks ago

README.md

INTRODUCTORY NOTE

«Brigitta» is an italian proper noun whose pronunciation in italian
language resembles a bit the english expression «bridge it».

SYNOPSIS

brigitta [options] <project directory>

DESCRIPTION

This is brigitta v0.1, a CLI php script that can discover and collect
Mastodon accounts from the profiles directories and-or local timelines of a
defined set of Mastodon instances, and make a «bot» account it may
control on each of the other instances follow them. Thus, each instance in
the defined set will have its federated timeline populated with more toots
from more accounts of the other instances, increasing the probability for
users of these instances to read and get to know each other.
In order for brigitta to work, an existing «project directory» has to be
passed as an argument to it, with a file named «brigitta.instances.conf»
inside it. This file should contain the instances’ definitions - at least
one, though it won’t make much sense to have only one ;-) -, one
definition for each line (empty lines and lines with an «;» character on
their first column will be ignored).
Each instance definition should follow this syntax:

<instance domain> <token>

«Token» should be the token of an app that has already been created, with
at least «follow» privileges, on an existing account with no particular
privileges on the corresponding instance (this account would better be
marked as «bot»). «Token» should be separated from «instance domain»
by a single « » (space) character. «Token» can also be set to «0»,
and as long as it is set this way the corresponding instance will still be
checked for new accounts, but its (possibly existing) «bot» account will
be ignored: brigitta won’t try to make it follow any new account it may
find on other instances.

--- Example «brigitta.instances.conf» file ---
; This line will be ignored and next line too, since it’s empty.

mastodon.xyz xA9kZe9zB6EgtjsW5EVr4axYWW46c1TPC-RpQhnkAvw
myinstance.social 7fne902mc0954mi2ollWMNfasdf6aposdfADF9MFN12
mstdn.mydomain.org 0
--- End of example ---

If a file named «brigitta.conf» exists inside the «project directory»,
it will be read and options specified in it will be applied. Any option
available on command line, except «help» and «unfollow», can be set in
this file using its long form. Note that any option specified on command
line supersedes the corresponding option that may be specified in this
file.

--- Example «brigitta.conf» file ---
; These lines and empty lines will be ignored.
; Every valid option takes an argument between «yes» and «no» after
; an «=» sign.

directories=no
timelines=yes
verbose=yes
--- End of example ---

OPTIONS

Note: some options need a parameter between «y» (for «yes»)
      and «n» (for «no»).

-h, --help
 Show this help text and exit.
-d, --directories <y|n>
 Defaults to «y»: the script will search for new addresses in the
 «profiles directory» of each instance. Ignored if «unfollow» (see
 below) is used.
-t, --timelines <y|n>
 Defaults to «n». If set to «y» the script will search for new
 addresses in the public local timeline of each instance. Ignored
 if «unfollow» (see below) is used.
-f, --follow <y|n>
 Defaults to «y»: the script will try to make bots follow any new
 account it may have found during current run and any account it
 possibly couldn’t make bots follow during previous runs. Ignored
 if «unfollow» (see below) is used.
-u, --unfollow
 Don’t search for new addresses and don’t make bots follow them, just
 make bots unfollow all previously followed accounts.
-v, --verbose <y|n>
 Defaults to «n». If set to «y», the script will produce a lot of
 informational output about what it’s doing.

EXIT VALUES

0: regular run
1: regular run, but some warnings where emitted
2: brigitta encountered a fatal error
10: brigitta was interrupted by SIGINT, SIGHUP or SIGTERM

NOTES

Brigitta is mainly meant to be run periodically and automatically,
typically from a cron job, but it is advisable to run it manually at least
once before setting it this way, to verify everything is properly set.
Brigitta tries to safely manage possible unavailability or denial of
service from the api endpoints it queries (be it caused by an instance’s
server down, exceeded rate limit, etc.). In particular, if any follow or
unfollow action fails on current run, it will be tried again on next runs,
until it succeeds.
On every run, brigitta writes informations about what it’s doing and
problems it may encounter in a «brigitta.log» file in the specified
project directory.

DISCLAIMER AND LICENSE

This program comes with ABSOLUTELY NO WARRANTY; for details see the source.
This is free software, and you are welcome to redistribute it under certain
conditions; see <http://www.gnu.org/licenses/> for details.