{"id":15283927,"url":"https://github.com/babetoduarte/tootnotify","last_synced_at":"2026-02-05T12:33:16.329Z","repository":{"id":180295400,"uuid":"664819162","full_name":"babetoduarte/TootNotify","owner":"babetoduarte","description":"Python command line tool to send DM notifications to a mastodon user.","archived":false,"fork":false,"pushed_at":"2023-07-17T19:13:12.000Z","size":1105,"stargazers_count":1,"open_issues_count":6,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-09T00:21:27.883Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/babetoduarte.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-10T20:24:31.000Z","updated_at":"2023-07-13T13:09:06.000Z","dependencies_parsed_at":"2024-09-30T14:48:20.158Z","dependency_job_id":"221fe669-4487-406f-9eb5-f3c5b591faaa","html_url":"https://github.com/babetoduarte/TootNotify","commit_stats":null,"previous_names":["babetoduarte/tootnotify"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/babetoduarte/TootNotify","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/babetoduarte%2FTootNotify","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/babetoduarte%2FTootNotify/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/babetoduarte%2FTootNotify/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/babetoduarte%2FTootNotify/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/babetoduarte","download_url":"https://codeload.github.com/babetoduarte/TootNotify/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/babetoduarte%2FTootNotify/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265645446,"owners_count":23804188,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-30T14:48:16.716Z","updated_at":"2026-02-05T12:33:16.283Z","avatar_url":"https://github.com/babetoduarte.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TootNotify  \n\nThis is a python command line utility based on [Mastodon.py](https://github.com/halcy/Mastodon.py) , which is able to send direct messages to a given user on Mastodon:\n\n`foo@bar:~$\u003e tootnotify -r @user@instance -m \"Message from TootNotify!\"`\n\nI built this tool to **notify myself via a secondary (bot) Mastodon account, when long-running processes and tasks finish**. FIY, **you don't need a second account to use TootNotify**, you can use your own account and DM yourself! Also, I'm sure there can be many more uses for this tool.\n\n\n\u003eBecause of the way Mastodon works, direct messages are just regular *Toots* that mention a single user on the content of its body, and are set to have `private` visibility (only the accounts mentioned can see the *Toot*).\n\nThis tool allows to *attach* image, video and audio files to the direct message:\n\n`foo@bar:~$\u003e tootnotify -r @user@instance -m \"Message with media\" -f image1.png image2.jpg`\n    \nDue to mastodon's API specifications, media attached to posts must be of the same type: only images (up to 4 images per *Toot*), only video (a *single* video file __or GIF__), or only audio (a single *audio* file). **The current implementation allows the API to determine the MIME type of each media file by the media's extension**.\n\nNote that these **attachments are done asynchronously** following Mastodon's guidelines, and the *Toot* is not sent until all data is uploaded (confirmed by the API call), which means your notification may take a few seconds to be sent while the attachments are uploaded. __If the upload takes more than the stipulated timeout parameter, the *Toot* is sent without any media__ (better to receive an incomplete notification than no notification at all!).\n\nThere are also command line arguments to flag your post as `sensitive content` (which will blur out the media you upload), as well as labeling the direct message with a `spoiler/content warning`, which will force the recipient to read your warning and click `Show More` to see the body and attachments of the message.\n\n## Mastodon API\n\nTo use this tool you will need to have a Mastodon API application created, with its corresponding API credentials. \n\nThe simplest way to do this, is through the Mastodon web interface: go to Preferences \u003e Development (*i.e.* [mastodon.social/settings/applications](https://mastodon.social/settings/applications))\n\n![Mastodon Preferences - Development Settings](./media/0-mastodon_app_credentials.png \"Mastodon Preferences - Development Settings\")\n\nOnce there, click on the `New Application` button. There, give your application a Name, and click the `Submit` button on the bottom of the page. Having created an App on your account, you should be presented with a `Client key`, a `Client secret`, and `Your Access Token`. You'll need to put these strings into a text configuration file called `.tootnotifyrc` located in your `$HOME` directory, as instructed below.\n\n## Installation\n\nThis section presents the steps needed to install TootNotify, once the API credentials have been obtained.\n\n### Create `~/.tootnotifyrc` file\n\nTootNotify looks for API credentials stored as variables in the `~/.tootnotifyrc` file within the user's `$HOME` folder. By default, **the `.tootnotifyrc` file is not shipped with the project, which means you need to create it**:\n\n`foo@bar:~$\u003e touch ~/.tootnotifyrc`\n\nMake sure that the content of `~/.tootnotify` corresponds to the following (and be sure to assign values to these variables **without any quotes**!):\n\n``` shell\n## FILE: ~/.tootnotifyrc\n[tootnotify]\n# Instance url (e.g. https://mastodon.social)\napi_base_url = YOUR_INSTANCE_URL\n# API Client Key\nclient_id = YOUR CLIENT_ID\n# API Client Secret\nclient_secret = YOUR_CLIENT_SECRET\n# API Access Token\naccess_token = YOU_ACCESS_TOKEN\n# Default recipient for the private toots (e.g. @account@mastodon.social)\nDEFAULT_RECIPIENT = YOUR_DEFAULT_RECIPIENT\n```\n\nAmong the variables, a DEFAULT_RECIPIENT can be configured, so that when using TootNotify systematically to notify the same user, the recipient address doesn't have to be provided every time:\n\n`foo@bar:~$\u003e tootnotify -m \"Message to the default recipient!\"`\n\n### Install from PyPI\n\nOnce the `~/.tootnotifyrc` control file is in place, we can use PIP to install TootNotify from PyPI\n\n``` bash\nfoo@bar:~$\u003e pip install tootnotify\n```\n\n### Install from this repository\n\nOnce the `~/.tootnotifyrc` control file is in place, we can use PIP to install TootNotify (make sure you navigate to the root of the `TootNotify` project folder):\n\n``` bash\nfoo@bar:TootNotify$\u003e pip install .\n```\n\nWe can check whether TootNotify was installed correctly, by invoking it (from anywhere) and passing it the `-h`/`--help` flag:\n\n``` bash\nfoo@bar:~$\u003e tootnotify -h\n```\n\nand if all goes well, we should be presented with the help dialog:\n\n``` bash\nusage: tootnotify [-h] [-r \u003c@user@instan.ce\u003e] [-m \u003cmessage_body\u003e] [-s \u003cspoiler_description\u003e]\n                  [-f \u003cpath_to_media_file\u003e [\u003cpath_to_media_file\u003e ...]] [-x] [-t \u003ctimeout_in_seconds\u003e] [-v] [--version]\n\nSend a Direct Message to someone on Mastodon!\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -r \u003c@user@instan.ce\u003e, --recipient \u003c@user@instan.ce\u003e\n                        User who will receive a direct message.\n  -m \u003cmessage_body\u003e, --message \u003cmessage_body\u003e\n                        Body of the message to be sent.\n  -s \u003cspoiler_description\u003e, --spoiler \u003cspoiler_description\u003e\n                        Description for the spoiler warning which hides the message.\n  -f \u003cpath_to_media_file\u003e [\u003cpath_to_media_file\u003e ...], --files \u003cpath_to_media_file\u003e [\u003cpath_to_media_file\u003e ...]\n                        List of up to 4 media files to attach to the message.\n  -x, --sensitive       Flag post/media as sensitive content (blur media).\n  -t \u003ctimeout_in_seconds\u003e, --timeout \u003ctimeout_in_seconds\u003e\n                        Number of seconds to wait for a single media file to upload.\n  -v, --verbose         Print out verbose messages.\n  --version             show program's version number and exit\n```\n\n## Usage from the command line\n\nThis section presents several examples on how to use TootNotify from the command line once it has been installed.\n\n### Toot to a single user\n\n`foo@bar:~$\u003e tootnotify -r @user@instance -m \"Message!\"`\n\n![Toot - DM to user](./media/1-Toot_Single.png \"Toot - DM to user\")\n\n### Toot with spoiler/content warning\n\n`foo@bar:~$\u003e tootnotify -r @user@instance -s \"Movie spoiler\" -m \"I can't believe Jhon dies at the end of the movie!\"`\n\n![Toot - DM to user with Content Warning and hidden message](./media/2-Toot_CW1.png \"Toot - DM to user with Content Warning and hidden message\")\n\n![Toot - DM to user with CW and message visible](./media/2-Toot_CW2.png \"Toot - DM to user with CW and message visible\")\n\n### Toot and single media file\n\n`foo@bar:~$\u003e tootnotify -r @user@instance -m \"Look at this animation!\" -f animated.gif`\n\n![Toot - DM to user with attached GIF](./media/3-Toot_GIF.png \"Toot - DM to user with attached GIF\")\n\n### Toot and multiple media files\n\n`foo@bar:~$\u003e tootnotify -r @user@instance -m \"Nice image gallery!\" -f image1.png image2.jpg image3.jpeg`\n\n![Toot - DM to user with four images attached](./media/4-Toot_Gallery.png \"Toot - DM to user with four images attached\")\n\n__If more than four media files are passed to `tootnotify -f` only the first four media files will be attached to the direct message.__\n\n### Toot with 'sensitive' media\n\n`foo@bar:~$\u003e tootnotify -r @user@instance -m \"Check out this sensitive content!\" -f sensitive.png -x`\n\n![Toot - DM to user with Sensitive Content hidden](./media/5-Toot_Sensitive1.png \"Toot - DM to user with Sensitive Content hidden\")\n\n![Toot - DM to user with Sensitive Content visible](./media/5-Toot_Sensitive2.png \"Toot - DM to user with Sensitive Content visible\")\n\n### Combining options\n\nAll these arguments can be used in combination with one another, meaning a *Toot* can: have a message body, have up to four images attached, have a spoiler/content warning, and be flagged as 'sensitive'!\n\n`foo@bar:~$\u003e tootnotify -r @usert@instance -m \"Check out this sensitive gallery!\" -f 1.png 2.png 3.png 4.png -s \"Very blue images containing numbers and circles\" -x`\n\n![Toot - DM to user containing multiple images, a content warning, and flagged as sensitive content](./media/6-Toot_All1.png \"Toot - DM to user containing multiple images, a content warning, and flagged as sensitive content\")\n\n![Toot - DM to user containing multiple images, a content warning, and flagged as sensitive content - content visible](./media/6-Toot_All2.png \"Toot - DM to user containing multiple images, a content warning, and flagged as sensitive content - content visible\")\n\n### Toot to multiple users\n\nThis is an unintended use case, and it's sort of _hacky_, but you can add multiple recipients to the *Toot*, by adding multiple Mastodon handles with their respective instances as a `quoted string` passed to the `-r`/`--recipient` argument:\n\n`foo@bar:~$\u003e tootnotify -r \"@user1@instance1 @user2@instance2\" -m \"Group Message!\"`\n\n## License Notice\n\nTootNotify Copyright (C) 2023 Jorge A. Duarte\nThis program comes with ABSOLUTELY NO WARRANTY; for details see [LICENSE](LICENSE). This is free software, and you are welcome to redistribute it under certain conditions; see [LICENSE](LICENSE) for details.  \n![GNU GPLv3](./media/gplv3-with-text-136x68.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbabetoduarte%2Ftootnotify","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbabetoduarte%2Ftootnotify","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbabetoduarte%2Ftootnotify/lists"}