plumes

Simple Twitter CLI for day-to-day social media hygiene
· Report Bug · Request Feature

Contents

• Contents
• Overview
• Inspiration
• Installation
• Usage
  • Getting Started And Creating Your Authentication Config
  • Export Friends
  • Export Followers
  • Export Tweets
  • Audit Users
  • Prune Your Tweets
• Setting Up Authentication
  • Get Your Twitter API Tokens
  • Configuring plumes
• Contributing
• Testing

Overview

Plumes is an open-source Python CLI app for day-to-day social media hygiene. It was designed to provide a simple, clear, and concise interface to quickly explore and clean a personal Twitter account.

Inspiration

Installation

# python >=3.6.1 is required
pip install plumes

Usage

Getting Started And Creating Your Authentication Config

# create your config file
plumes init

# validate your config file
plumes check_config

# print your config file (watch out for sensitive tokens!)
plumes view_config

Export Friends

Extract friends ordered in which they were added:

plumes friends <flags>

# e.g., get the friends of Steve Martin (see data in examples dir)
plumes friends SteveMartinToGo --limit 100

Arguments:

• screen_name Optional[str], optional - Target user's screen name (i.e., Twitter handle). If none is given, authenticated user is used. Defaults to None.
• limit Optional[int], optional - Max number of users to fetch. Defaults to None.
• output Optional[str], optional - Output path for JSON file. Defaults to None.

Export Followers

Extract followers ordered in which they were added:

plumes followers <flags>

# e.g., get the followers of Al Yankovic (see data in examples dir)
plumes followers alyankovic --limit 100

Arguments:

• screen_name Optional[str], optional - Target user's screen name (i.e., Twitter handle). If none is given, authenticated user is used. Defaults to None.
• limit Optional[int], optional - Max number of users to fetch. Defaults to None.
• output Optional[str], optional - Output path for JSON file. Defaults to None.

Export Tweets

Extract (and archive) tweets ordered in by most recent:

plumes tweets <flags>

# e.g., get the tweets of Conan O'Brien (see data in examples dir)
plumes tweets ConanOBrien --limit 100

Arguments:

• screen_name Optional[str], optional - Target user's screen name (i.e., Twitter handle). If none is given, authenticated user is used. Defaults to None.
• limit Optional[int], optional - Max number of users to fetch. Defaults to None.
• output Optional[str], optional - Output path for JSON file. Defaults to None.

Audit Users

Audit and review users given criteria. Use this to mass follow/unfollow many users.

plumes audit_users PATH <flags>

# e.g., follow 100 of Al Yankovic's followers
plumes followers alyankovic --limit 100
plumes audit_users alyankovic-followers.json --befriend

# e.g., prune (i.e., unfollow) current friends who have less than 100 followers AND haven't tweeted in the last 30 days
plumes friends --output "friends.json"
plumes audit_users "friends.json" --prune --min_followers 100 --days 30

Arguments:

• path str - Path to JSON file of users (e.g., output of friends())
• min_followers Optional[int], optional - Min number of followers. Defaults to None.
• max_followers Optional[int], optional - Max number of followers. Defaults to None.
• min_friends Optional[int], optional - Min number of friends. Defaults to None.
• max_friends Optional[int], optional - Max number of friends. Defaults to None.
• days Optional[int], optional - Days since last tweet. Defaults to None.
• min_tweets Optional[int], optional - Min number of tweets. Defaults to None.
• max_tweets Optional[int], optional - Max number of tweets. Defaults to None.
• min_favourites Optional[int], optional - Min number of favourites. Defaults to None.
• max_favourites Optional[int], optional - Max number of favourites. Defaults to None.
• min_ratio Optional[float], optional - Min Twitter follower-friend (TFF) ratio. Defaults to None.
• max_ratio Optional[float], optional - Max Twitter follower-friend (TFF) ratio. Defaults to None.
• prune bool, optional - Unfollow identified users. Defaults to False.
• befriend bool, optional - Follow identified users. Defaults to False.
• bool_or bool, optional - Switch to boolean OR for conditions. Defaults to False.

Prune Your Tweets

Audit and review tweets given criteria. Use this to mass favourite or delete tweets.

plumes audit_tweets PATH <flags>

# e.g., delete your tweets that are older than 60 days AND that you didn't self-favourite
plumes tweets --output "tweets.json"
plumes audit_tweets "tweets.json" --prune --days 60 --self_favorited False

# e.g., export 100 of Conan O'Brien's tweets and favourite those that have a maximum of 10 likes and a minimum of 50 retweets
plumes tweets ConanOBrien --limit 100
plumes audit_tweets ConanOBrien-tweets.json --favorite --max_likes 10 --min_retweets 50

Arguments:

• days Optional[int], optional - Days since tweeted. Defaults to None.
• min_likes Optional[int], optional - Min number of favourites. Defaults to None.
• max_likes Optional[int], optional - Max number of favourites. Defaults to None.
• min_retweets Optional[int], optional - Min number of retweets. Defaults to None.
• max_retweets Optional[int], optional - Max number of retweets. Defaults to None.
• min_ratio Optional[float], optional - Min Twitter like-retweet ratio. Defaults to None.
• max_ratio Optional[float], optional - Max Twitter like-retweet ratio. Defaults to None.
• self_favorited Optional[bool], optional - Check if tweet is self-liked. Defaults to None.
• prune bool, optional - Prune and destroy identified tweets. Defaults to False.
• favorite bool, optional - Like identified tweets. Defaults to False.
• bool_or bool, optional - Switch to boolean OR for conditions. Defaults to False.

Setting Up Authentication

Get Your Twitter API Tokens

• Navigate to the Twitter Dev Portal

• Click Create an app

  

• Fill out the forms

• Navigate to Keys and tokens

  

• Copy the values for API key, API secret key, Access token, and Access token secret

  

Configuring plumes

The API tokens can either be set as environment variables (using the PLUMES_ prefix; e.g., export PLUMES_CONSUMER_KEY=xxxxx) or configuration variables in ~/.plumes.toml:

• CONSUMER_KEY = <API key>
• CONSUMER_SECRET = <API secret key>
• ACCESS_TOKEN = <Access token>
• ACCESS_TOKEN_SECRET = <Access token secret>

Contributing

Please see CONTRIBUTING.md and the Code of Conduct for how to contribute to the project

Testing

• Please review the Makefile for an overview of all available tests
• The most important tests and make commands are highlighted below:

# auto-format code
make format

# perform all static tests
make check