Simple Twitter CLI for day-to-day social media hygiene
·
Report Bug
·
Request Feature
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.
# python >=3.6.1 is required
pip install plumes
# 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
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.
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.
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 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.
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.
-
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
, andAccess token secret
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>
Please see CONTRIBUTING.md
and the Code of Conduct for how to contribute to the project
- 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