Toot CLI

If you find this useful, please consider supporting my work with a donation.

Description

A simple CLI for sending Mastodon toots. This is intended for use in CI systems such as GitHub actions in order to enable to Mastodon notifications of important events.

Usage

You must have Node.js to use this package.

To start, you must have created a Mastodon application. To do so:

Log in to your Mastodon server
Click "Preferences"
Click "Development"
Click "Create application"

Your application will be assigned an access token and you'll need that access token to use this package.

Next, define your environment variables:

MASTODON_ACCESS_TOKEN - your access token
MASTODON_HOST - your Mastodon host (i.e., mastodon.social)

The CLI will not work without these environment variables.

Then, you can run the CLI and pass a message on the command line using npx:

$ npx @humanwhocodes/toot "Hello from the command line!"

If successful, the CLI will output the response from Twitter.

Testing with dotenv

If you'd like to test with dotenv, define an additional environment variable TOOT_DOTENV=1 before executing the CLI. This will cause a local .env file to be read before executing.

Using in a GitHub Workflow

Be sure to set up GitHub secrets for each environment variable. Then, you can configure a job like this:

jobs:
  Toot:
    name: Toot Something
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v3
        with:
          node-version: 12
      - run: 'npx @humanwhocodes/toot "Your Toot text"'
        env:
          MASTODON_ACCESS_TOKEN: ${{ secrets.MASTODON_ACCESS_TOKEN }}
          MASTODON_HOST: ${{ secrets.MASTODON_HOST }}

Developer Setup

Ensure you have Node.js 18+ installed
Fork and clone this repository
Run npm install
Run npm test to run tests

Troubleshooting

Console says "Required environment variable 'MASTODON_ACCESS_TOKEN' is an empty string."

You haven't setup the correct environment variables for Toot CLI. Double check that you don't have any misspellings in your environment variable settings.

GitHub Actions console says "Required environment variable 'MASTODON_ACCESS_TOKEN' is an empty string."

You're probably trying to use the Toot CLI during the pull_request event. This won't work because secrets are not available when a pull request is from a fork. Try using the pull_request_target event instead. (More information)

License and Copyright

This code is licensed under the Apache 2.0 License (see LICENSE for details).