Mastodon CLI interface

Craig Maloney 6dd84fc376 Merge tag '' into develop 5 months ago
src 205829bb8e Updating for pep8 7 months ago
.gitignore e51e59e9f4 colored texts using termcolor module 3 years ago 89f9ed50c9 Missed the version bump 5 months ago 8746bfac18 Create 3 years ago ff0688f05c I think I fixed the bad merge 3 years ago c92423ffe4 Adding packaging for tootstream 2 years ago 3957370431 Add a note for the use of the requests library 2 years ago
requirements.txt fc845a5382 Update requirements for the new 1.5.0 release 8 months ago 89f9ed50c9 Missed the version bump 5 months ago


A command line interface for interacting with Mastodon instances written in Python (requires Python 3).

OAuth and 2FA are supported.

Inspired by Rainbowstream.


tootstream displaying the Federated timeline

Install via pip

1: Create a virtual environment

$ virtualenv -p python3 /path/to/tootstream
$ source /path/to/tootstream/bin/activate

2: Install via pip

$ pip install tootstream

3: See the Usage section for how to use Tootstream.

Install for development

1: Clone this repo and enter the project directory through a virtual environment

$ git clone
$ cd tootstream

2: Create a Virtual Environment

# Create a virtual environment
$ virtualenv -p python3 /path/to/tootstream
$ source /path/to/tootstream/bin/activate

3: Install the project

$ python3 install

4: Close the environment with $ deactivate


1: Return to your virtual environment

$ source /path/to/tootstream/bin/activate

2: Run the program

$ tootstream

3: Use the help command to see the available commands

[@myusername (default)]: help

4: Exit the program when finished

[@myusername (default)]: quit

5: Close the environment with $ deactivate

Ubuntu and Unicode

Tootstream relies heavily on Unicode fonts. The best experience can be had by installing the following package:

$ sudo apt-get install ttf-ancient-fonts


By default tootstream uses configparser for configuration. The default configuration is stored in the default location for configparser (on the developer's machine this is under /home/myusername/.config/tootstream/tootstream.conf).

At the moment tootstream only stores login information for each instance in the configuration file. Each instance is under its own section (the default configuration is under the [default] section). Multiple instances can be stored in the tootstream.conf file. (See "Using multiple instances")

Using multiple instances

Tootstream supports using accounts on multiple Mastodon instances.

Use the --instance parameter to pass the server location (in the case of we'd use --instance

Use the --profile parameter to use a different named profile. (in the case of we could call it and name the section using --profile

By default tootstream uses the [default] profile. If this already has an instance associated with it then tootstream will default to using that instance.

If you have already set up a profile you may use the --profile command-line switch to start tootstream with it. The --instance parameter is optional (and redundant).

You may select a different configuration using --config and pass it the full-path to that file.

Notes on networking

Tootstream and use the requests library for communicating with the Mastodon instance. Any proxy settings you may need to communicate with the network will need to be in a format that the requests library understands. See the requests documentation for more details on what those environment variables should be.


Contributions welcome! Please read the contributing guidelines before getting started.

Code of Conduct

This project is intended to be a safe, welcoming space for collaboration. All contributors are expected to adhere to the Contributor Covenant code of conduct. Thank you for being kind to each other!