toot - Mastodon CLI client

Toot is a CLI and TUI tool for interacting with Mastodon instances from the command line.

Resources

• Homepage: https://github.com/ihabunek/toot
• Issues: https://github.com/ihabunek/toot/issues
• Documentation: https://toot.readthedocs.io/en/latest/
• Mailing list for discussion, support and patches: https://lists.sr.ht/~ihabunek/toot-discuss
• Informal discussion: #toot IRC channel on libera.chat

Features

• Posting, replying, deleting, favouriting, reblogging & pinning statuses
• Support for media uploads, spoiler text, sensitive content
• Search by account or hash tag
• Following, muting and blocking accounts
• Simple switching between multiple Mastodon accounts

Contents

Installation

toot is packaged for various platforms.

Overview

Packaging overview provided by repology.org.

Debian & Ubuntu

Since Debian 10 (buster) and Ubuntu 19.04 (disco), toot is available in the official package repository.

sudo apt install toot

Debian package is maintained by Jonathan Carter.

Arch Linux

Install from AUR.

yay -S toot

Fedora

Toot is available from the Fedora package repository.

sudo dnf install toot

FreeBSD ports

Install the package:

pkg install py38-toot

Build and install from sources:

cd /usr/ports/net-im/toot
make install

FreeBSD port is maintained by Mateusz Piotrowski

Nixpkgs

This works on NixOS or systems with the Nix package manager installed.

nix-env -iA nixos.toot

OpenBSD ports

Install the package:

pkg_add toot

Build and install from sources:

cd /usr/ports/net/toot
make install

OpenBSD port is maintained by Klemens Nanni

Python Package Index

Install from PyPI using pip, preferably into a virtual environment.

pip install --user toot

Homebrew

This works on Mac OSX with homebrew installed. Tested with on Catalina, Mojave, and High Sierra.

brew update
brew install toot

Source

Finally, you can get the latest source distribution, wheel or debian package from GitHub.

Usage

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
v0.27.0

Authentication:
  toot login           Log into a mastodon instance using your browser (recommended)
  toot login_cli       Log in from the console, does NOT support two factor authentication
  toot activate        Switch between logged in accounts.
  toot logout          Log out, delete stored access keys
  toot auth            Show logged in accounts and instances

TUI:
  toot tui             Launches the toot terminal user interface

Read:
  toot whoami          Display logged in user details
  toot whois           Display account details
  toot notifications   Notifications for logged in user
  toot instance        Display instance details
  toot search          Search for users or hashtags
  toot thread          Show toot thread items
  toot timeline        Show recent items in a timeline (home by default)

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

Status:
  toot delete          Delete a status
  toot favourite       Favourite a status
  toot unfavourite     Unfavourite a status
  toot reblog          Reblog a status
  toot unreblog        Unreblog a status
  toot reblogged_by    Show accounts that reblogged the status
  toot pin             Pin a status
  toot unpin           Unpin a status

Accounts:
  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

https://github.com/ihabunek/toot

Authentication

Before tooting, you need to log into a Mastodon instance.

toot login

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 the configuration file located at ~/.config/toot/config.json.

Using multiple accounts

It’s possible to be logged into multiple accounts at the same time. Just repeat the login process for another instance. You can see all logged in accounts by running toot auth. The currently active account will have an ACTIVE flag next to it.

To switch accounts, use toot activate. Alternatively, most commands accept a --using option which can be used to specify the account you wish to use just that one time.

Finally you can logout from an account by using toot logout. This will remove the stored access tokens for that account.

Post a status

The simplest action is posting a status.

toot post "hello there"

You can also pipe in the status text:

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

If no status text is given, you will be prompted to enter some:

$ toot post
Write or paste your toot. Press Ctrl-D to post it.

Finally, you can launch your favourite editor:

toot post --editor vim

Define your editor preference in the EDITOR environment variable, then you don’t need to specify it explicitly:

export EDITOR=vim
toot post --editor

Attachments

You can attach media to your status. Mastodon supports images, video and audio files. For details on supported formats see Mastodon docs on attachments.

It is encouraged to add a plain-text description to the attached media for accessibility purposes by adding a --description option.

To attach an image:

toot post "hello media" --media path/to/image.png --description "Cool image"

You can attach upto 4 attachments by giving multiple --media and --description options:

toot post "hello media" \
  --media path/to/image1.png --description "First image" \
  --media path/to/image2.png --description "Second image" \
  --media path/to/image3.png --description "Third image" \
  --media path/to/image4.png --description "Fourth image"

The order of options is not relevant, except that the first given media will be matched to the first given description and so on.

If the media is sensitive, mark it as such and people will need to click to show it. This affects all attachments.

toot post "naughty pics ahoy" --media nsfw.png --sensitive

View timeline

View what’s on your home timeline:

toot timeline

Timeline takes various options:

toot timeline --public          # public timeline
toot timeline --public --local  # public timeline, only this instance
toot timeline --tag photo       # posts tagged with #photo
toot timeline --count 5         # fetch 5 toots (max 20)
toot timeline --once            # don't prompt to fetch more toots

Status actions

The timeline lists the status ID at the bottom of each toot. Using that status you can do various actions to it, e.g.:

toot favourite 123456
toot reblog 123456

If it’s your own status you can also delete pin or delete it:

toot pin 123456
toot delete 123456

Account actions

Find a user by their name or account name:

toot search "name surname"
toot search @someone
toot search someone@someplace.social

Once found, follow them:

toot follow someone@someplace.social

If you get bored of them:

toot mute someone@someplace.social
toot block someone@someplace.social
toot unfollow someone@someplace.social

Using the Curses UI

toot has a curses-based terminal user interface. The command to start it is toot tui.

To navigate the UI use these commands:

• k or up arrow to move up the list of tweets
• j or down arrow to move down the list of tweets
• h to show a help screen
• t to view status thread
• v to view the current toot in a browser
• b to boost or unboost a status
• f to favourite or unfavourite a status
• q to quit the curses interface and return to the command line
• s to show sensitive content. (This is per-toot, and there will be a read bar in the toot to indicate that it is there.)

Note that the curses UI is not available on Windows.

Advanced usage

Disabling HTTPS

You may pass the --disable-https flag to use unencrypted HTTP instead of HTTPS for a given instance. This is inherently insecure and should be used only when connecting to local development instances.

toot login --disable-https --instance localhost:8080

Using proxies

You can configure proxies by setting the HTTPS_PROXY or HTTP_PROXY environment variables. This will cause all http(s) requests to be proxied through the specified server.

For example:

export HTTPS_PROXY="http://1.2.3.4:5678"
toot login --instance mastodon.social

NB: This feature is provided by requests and setting the environment variable will affect other programs using this library.

This environment can be set for a single call to toot by prefixing the command with the environment variable:

HTTPS_PROXY="http://1.2.3.4:5678" toot login --instance mastodon.social

Release procedure

This document is a checklist for creating a toot release.

Currently the process is pretty manual and would benefit from automatization.

Bump & tag version

• Update the version number in setup.py
• Update the version number in toot/__init__.py
• Update changelog.yaml with the release notes & date
• Run make changelog to generate a human readable changelog
• Commit the changes
• Run ./scripts/tag_version <version> to tag a release in git
• Run git push --follow-tags to upload changes and tag to GitHub

Publishing to PyPI

• make dist to create source and wheel distributions
• make publish to push them to PyPI

GitHub release

• Create a release for the newly pushed tag, paste changelog since last tag in the description

• Upload the assets generated in previous two steps to the release:

  • source dist (.zip and .tar.gz)
  • wheel distribution (.whl)

TODO: this can be automated: https://developer.github.com/v3/repos/releases/

Curses UI

toot includes a curses-based terminal user interface (TUI). Run it with toot tui.

Development

The project source code and issue tracker are available on GitHub:

https://github.com/ihabunek/toot

Please report any issues there. Pull requests are welcome.

License

Copyright Ivan Habunek <ivan@habunek.com> and contributors.

Licensed under GPLv3.