Using Mastodon from the command line

Command Line – Mastodon CLI Client

© Lead Image © Author,

© Lead Image © Author,

Article from Issue 269/2023

If you are looking for a Twitter alternative, toot lets you interact with Mastodon from the command line.

An open source, decentralized version of Twitter, Mastodon has been in development since 2016. With Elon Musk's erratic decisions since purchasing Twitter in late 2022, many users predicting Twitter's doom have been searching desperately for alternatives. The result has been a new surge in interest in Mastodon – even if many newcomers remain puzzled by its open source organization. The interest is so great that Mastodon's founder Eugen Rochko reports that he has received offers of "hundreds of thousands of dollars" from five investors – offers he refused so as not to endanger Mastodon's nonprofit status [1]. As I write, the exodus from Twitter appears to have slowed, but along with the renewed interest in Mastodon has come a renewed interest among Linux users in toot [2], an open source command-line client for Mastodon.

Toot takes its name from Mastodon's equivalent of Twitter's tweets, the microblog messages posted by users. Officially, the term is obsolete, with Mastodon's latest release replacing toot with a simple Publish button [3], but the term remains widely used. Toot compares favorably with Twitter clients for Linux such as Twidge, Oyster, and Rainbow Stream, many of which are not up-to-date, and have an alarming tendency to come and go without warning. By contrast, although current users must still use the web interface to create a Mastodon account for everyday use, toot is a complete replacement for the web version of Mastodon (Figure 1), providing functionality that is both thoroughly documented and up-to-date with Mastodon through a series of commands and options that keeps users' hands firmly on the keyboard.

Figure 1: The Mastodon web application.

Getting Started

You will find toot in the package repositories of many distributions and you can also install toot using Homebrew, although some sources are more current than others. However you choose to install, to use toot, you must create an account in a Mastodon instance from a web browser before logging in with the command toot login_cli (Figure 2). Upon launching, toot creates a configuration file in your home directory at .config/toot/config.json. You must then specify a Mastodon instance to log in to – but note that its name must be entered in lowercase characters with periods rather than spaces between the words, regardless of how the instance name is presented in the web interface. After toot locates the instance, enter your email and password to log in. For later access, toot stores your email and a temporary access token in the configuration file so that your password is never stored unencrypted. Once you are connected to an instance, you can enter user whoami to display user details and toot whois to display account details. To switch accounts, use toot activate. To see a list of active accounts, enter toot auth.

Figure 2: Logging in to toot.

Posting Toots

You can post a toot in several ways. The simplest (as shown in Figure 3) is:

toot post 'MESSAGE'
Figure 3: One of several ways to post a toot.

Alternatively, you can compose a toot in a text editor of your choice (Figure 4) – Vim in this example – with the following command:

toot post --editor vim
Figure 4: You can compose a toot in the text editor of your choice.

Save and exit the toot as you normally would in the editor, and the toot is also posted. If you prefer to always use a text editor, define your preferred editor as an environmental variable (for instance, export EDITOR=vim), and then you can simply use the following command:

toot post --editor

With all these variations of the command, you can add up to four attachments. For the first attachment, use the option

-media path/to/image1.png --description "TEXT" \

and then change the image number for the subsequent attachments. If necessary, you can flag attachments with:

--media nsfw.png --sensitive

Once a toot is posted, you can see any replies using toot notifications.

Viewing the Timeline

When viewing toots in your timeline, the basic command toot timeline displays the most recent toot. It then gives you the option of either displaying the last dozen toots or else exiting the client altogether. You can also use the options listed in Table 1 to modify which toots are displayed.

Table 1

Viewing Options

toot timeline --public --local

Public timeline, only this Mastodon instance

toot timeline --tag photo

Posts tagged with #photo

toot timeline --count NUMBER

Fetch up to 20 toots

toot timeline --once

Don't prompt to fetch more toots

At the bottom of each toot, you will find its ID and whether it has been reblogged. You can pin one of your own toots to the top of your timeline with toot pin ID or delete it with toot delete ID (Figure 5).

Figure 5: The toot timeline.

You can locate other people on Mastodon with

toot search "NAME"

or by their Mastodon instance address with

toot search NAME@INSTANCE

With an instance address, you can also use the self-explanatory commands follow, mute, block, or unfollow. To like a toot, used the command

toot favourite ID

(note the UK English spelling). To reblog toot use toot reblog ID.

Should you decide to undo any of these actions, you can run the same commands prefaced by un. For example, if you decide on second thought not to favor a toot, use the command:

toot unfavourite ID

The rest you can probably figure out for yourself. If necessary, though, for detailed summaries, run

toot COMMAND --help

You can perform all these basic functions from the command line or start the curses user interface with toot tui (Figure 6). The curses interface is navigated by the keyboard commands shown in Table 2.

Table 2

Curses Interface Navigation

k or up arrow

Move up the list of toots

j or down arrow

Move down the list of toots


Show a help screen


View status thread


View the current toot in a browser


Boost or unboost a status


Favorite or unfavorite a status


Quit the curses interface and return to the command line


Show sensitive content

Figure 6: Toot includes an alternative curses-based interface for working with the timeline.

Buy this article as PDF

Express-Checkout as PDF
Price $2.95
(incl. VAT)

Buy Linux Magazine

Get it on Google Play

US / Canada

Get it on Google Play

UK / Australia

Related content

  • Mastodon Clients Post Line

    The open and simple Mastodon API makes it easy to create applications to interact with this federated microblogging platform. Here are some of the clients that the community has come up with and how you can use them.

  • Social Skills

    Creating a custom application that toots text to Mastodon (the Fediverse's version of Twitter) is simple and straightforward. But we can mix it up by adding images and video, scheduling posts, and changing privacy settings.

  • Tutorial – Fediverse

    If you're looking for social media options where the user has more control, you'll find a range of options to explore in the Fediverse, including the popular Mastodon.

  • Mastodon

    Get started with free microblogging, interact with others who share you interests, and even help expand the Fediverse with your own Mastodon instance.

  • Status Quo

    Creating your own clients to interact with your friends in the Fediverse is easy. A bit of Python and an off-the-shelf module will do the trick.

comments powered by Disqus
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters

Support Our Work

Linux Magazine content is made possible with support from readers like you. Please consider contributing when you’ve found an article to be beneficial.

Learn More