A tool for deleting old toots, written in Python 3.

Prior work

The initial ephemetoot script was based on this tweet-deleting script by @flesueur

ephemetoot relies heavily on the Mastodon.py package by @halcy

Usage

You can use ephemetoot to delete Mastodon toots that are older than a certain number of days. Toots can optionally be saved from deletion if:

• they are pinned;
• they include certain hashtags;
• they have certain visibility; or
• they are individually listed to be kept

Setup

Install Python 3

You need to install Python 3 to use ephemetoot. Python 2 is now end-of-life, however it continued to be installed as the default Python on MacOS until very recently, and may also be installed on your server.

Install ephemetoot

get code with git

If you already have git installed on the machine where you're running ephemetoot, you can download the latest release with:

git clone https://github.com/hughrun/ephemetoot.git

get code by downloading zip file

If you don't have git or don't want to use it, you can download the zip file by clicking the green Clone or download button above and selecting Download ZIP. You will then need to unzip the file into a new directory where you want to run it.

install using pip

From a command line, move into the main ephemetoot directory (i.e. where the README file is) and run:

pip install .

With some Python 3 installations (e.g on MacOS with Homebrew) you may need to use:

pip3 install .

Obtain an access token

Now you've installed ephemetoot, in order to actually use it you will need an application "access token" from each user. Log in to your Mastodon account using a web browser:

1. Click the settings cog
2. Click on Development
3. Click NEW APPLICATION
4. Enter an application name (e.g. 'ephemetoot'), and give the app both 'read' and 'write' Scopes
5. Click SUBMIT
6. Click on the name of the new app, which should be a link
7. Copy the Your access token string

Configuration file

As of version 2, you can use a single ephemetoot installation to delete toots from multiple accounts. Configuration for each user is set up in the config.yaml file. This uses yaml syntax and can be updated at any time without having to reload ephemetoot.

Copy example-config.yaml to a new file called config.yml:

cp example-config.yam config.yaml

You can now enter the configuration details for each user:

setting	description
access_token	The alphanumeric access token string from the app you created in Mastodon
username	Your username without the '@' or server domain. e.g. hugh
base_url	The base url of your Mastodon server, without the 'https://'. e.g. ausglam.space
days_to_keep	Number of days to keep toots e.g. 30
keep_pinned	Either True or False - if True, any pinned toots will be kept regardless of age
toots_to_keep	A list of toot ids indicating toots to be kept regardless of other settings. The ID of a toot is the last part of its individual URL. e.g. for https://ausglam.space/@hugh/101294246770105799 the id is 101294246770105799
hashtags_to_keep	a Set of hashtags, where any toots with any of these hashtags will be kept regardless of age. Do not include the '#' symbol, and remember the rules for hashtags
visibility_to_keep	Any toots with visibility settings in this list will be kept regardless of age. Options are: public, unlisted, private, direct. For example the following would only delete public toots:

- unlisted
- private
- direct

|

If you want to use ephemetoot for multiple accounts, separate the config for each user with a single dash (-), as shown in the example file.

Running the script

It is strongly recommended that you do a test run before using ephemetoot live.

To call the script you can simply enter:

ephemetoot

Depending on how many toots you have and how long you want to keep them, it may take a minute or two before you see any results.

Specifying the config location

By default ephemetoot expects there to be a config file called config.yaml in the directory from where you run the ephemetoot command. If you want to call it from elsewhere (e.g. from cron), you need to specify where your config file is:

ephemetoot --config 'directory/config.yaml'

Running in test mode

To do a test-run without actually deleting anything, run the script with the --test flag:

ephemetoot --test

Other flag options

You can use both flags together:

ephemetoot --config 'directory/config.yaml' --test

Use them in any order:

ephemetoot --test --config 'directory/config.yaml'

Instead of coming back to this page when you forget the flags, you can just use the help option:

ephemetoot --help

Rate limits

As of v2.7.2 the Mastodon API has a rate limit of 30 deletions per 30 minutes. mastodon.py automatically handles this. If you are running ephemetoot for the first time and/or have a lot of toots to delete, it may take a while as the script will pause when it hits a rate limit, until the required time has expired. Note that the rate limit is per access token, so using ephemetoot for multiple accounts on the same server shouldn't be a big problem, however one new user may delay action on subsequent accounts in the config file.

Scheduling

Deleting old toots daily is the best approach to keeping your timeline clean and avoiding problems wiht the API rate limit.

To run automatically every day on a n*x server you could try using crontab:

1. crontab -e
2. @daily ephemetoot

Alternatively on MacOS you could use launchd. Some further work on an example setup for launchd is coming soonish.

ASCII / utf-8 errors

Prior to Python 3.7, running a Python script on some BSD and Linux systems may throw an error. This can be resolved by:

• setting a locale that encodes utf-8, by using the environment setting PYTHONIOENCODING=utf-8 when running the script, or
• upgrading your Python version to 3.7 or higher. See Issue 11 for more information.

Uninstalling

Uninstall using pip;

pip uninstall ephemetoot

Bugs and suggestions

Please check existing issues and if your issue is not already listed, create a new one with as much detail as possible (but don't include your access token!).

Contributing

Contributions are very welcome, but if you want to suggest any changes or improvements, please log an issue or have a chat to me on Mastodon before making a pull request.

License

GPL 3.0+