Skip to main content

Interact with Mastodon social networks from the command line.

Project description

Interact with Mastodon social networks from the command line.


Install using pip:

pip install toot


Running toot displays a list of available commands.

Running toot <command> -h shows the documentation for the given command.

$ toot

toot - a Mastodon CLI client

  toot login           Log into a Mastodon instance, does NOT support two factor authentication
  toot login_browser   Log in using your browser, supports regular and two factor authentication
  toot login_2fa       Log in using two factor authentication in the console (hacky, experimental)
  toot logout          Log out, delete stored access keys
  toot auth            Show stored credentials

  toot whoami          Display logged in user details
  toot whois           Display account details
  toot search          Search for users or hashtags
  toot timeline        Show recent items in your public timeline
  toot curses          An experimental timeline app.

  toot post            Post a status text to your timeline
  toot upload          Upload an image or video file

  toot follow          Follow an account
  toot unfollow        Unfollow an account
  toot mute            Mute an account
  toot unmute          Unmute an account
  toot block           Block an account
  toot unblock         Unblock an account

To get help for each command run:
  toot <command> --help

It is possible to pipe status text into toot post, for example:

echo "Text to post" | toot post
cat mypost.txt | toot post


Before tooting, you need to login to a Mastodon instance.

If you don’t use two factor authentication you can log in directly from the command line:

toot login

You will be asked to chose an instance and enter your credentials.

If you do use two factor authentication, you need to log in through your browser:

toot login_browser

You will be redirected to your Mastodon instance to log in and authorize toot to access your account, and will be given an authorization code in return which you need to enter to log in.

The application and user access tokens will be saved in two files in your home directory:

  • ~/.config/toot/instances/<name> - created for each mastodon instance once
  • ~/.config/toot/user.cfg

You can check whether you are currently logged in:

toot auth

And you can logout which will remove the stored access tokens:

toot logout


Copyright © 2017 Ivan Habunek <>

Licensed under the GPLv3:

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
toot-0.13.0-py2.py3-none-any.whl (17.1 kB) Copy SHA256 hash SHA256 Wheel py2.py3
toot-0.13.0.tar.gz (12.2 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page