Are you happy with your logging solution? Would you help us out by taking a 30-second survey? Click here


A command-line power tool for Twitter.

Subscribe to updates I use t

Statistics on t

Number of watchers on Github 4492
Number of open issues 151
Average time to close an issue about 1 month
Main language Ruby
Average time to merge a PR 16 days
Open pull requests 40+
Closed pull requests 17+
Last commit almost 2 years ago
Repo Created almost 8 years ago
Repo Last Updated over 1 year ago
Size 3.44 MB
Homepage http://sferik.git...
Organization / Authorsferik
Page Updated
Do you use t? Leave a review!
View open issues (151)
View t activity
View on github
Fresh, new opensource launches 🚀🚀🚀
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating t for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)

Application icon

Twitter CLI

Gem Version Build Status Dependency Status Coverage Status tip for next commit

A command-line power tool for Twitter.

The CLI takes syntactic cues from the Twitter SMS commands, but it offers vastly more commands and capabilities than are available via SMS.


First, make sure you have Ruby installed.

On a Mac, open /Applications/Utilities/ and type:

ruby -v

If the output looks something like this, you're in good shape:

ruby 2.3.1p112 (2016-04-26 revision 54768) [x86_64-darwin15]

If the output looks more like this, you need to install Ruby:

ruby: command not found

On Linux, for Debian-based systems, open a terminal and type:

sudo apt-get install ruby-dev

or for Red Hat-based distros like Fedora and CentOS, type:

sudo yum install ruby-devel

(if necessary, adapt for your package manager)

On Windows, you can install Ruby with RubyInstaller.


Once you've verified that Ruby is installed:

gem install t


Twitter API v1.1 requires OAuth for all of its functionality, so you'll need a registered Twitter application. If you've never registered a Twitter application before, it's easy! Just sign-in using your Twitter account and then fill out the short form at If you've previously registered a Twitter application, it should be listed at Once you've registered an application, make sure to set your application's Access Level to Read, Write and Access direct messages, otherwise you'll receive an error that looks like this:

Error processing your OAuth request: Read-only application cannot POST

A mobile phone number must be associated with your account in order to obtain write privileges. If your carrier is not supported by Twitter and you are unable to add a number, contact Twitter using, selecting the last checkbox. Some users have reported success adding their number using the mobile site,, which seems to bypass the carrier check at the moment.

Now, you're ready to authorize a Twitter account with your application. To proceed, type the following command at the prompt and follow the instructions:

t authorize

This command will direct you to a URL where you can sign-in to Twitter, authorize the application, and then enter the returned PIN back into the terminal. If you type the PIN correctly, you should now be authorized to use t as that user. To authorize multiple accounts, simply repeat the last step, signing into Twitter as a different user.

NOTE: If you have problems authorizing multiple accounts, open a new window in your browser in incognito/private-browsing mode and repeat the t authorize steps. This is apparently due to a bug in twitter's cookie handling.

You can see a list of all the accounts you've authorized by typing the command:

t accounts

The output of which will be structured like this:

  thG9EfWoADtIr6NjbL9ON (active)

Note: One of your authorized accounts (specifically, the last one authorized) will be set as active. To change the active account, use the set subcommand, passing either just a username, if it's unambiguous, or a username and consumer key pair, like this:

t set active sferik UDfNTpOz5ZDG4a6w7dIWj

Account information is stored in a YAML-formatted file located at ~/.trc.

Note: Anyone with access to this file can impersonate you on Twitter, so it's important to keep it secure, just as you would treat your SSH private key. For this reason, the file is hidden and has the permission bits set to 0600.

Usage Examples

Typing t help will list all the available commands. You can type t help TASK to get help for a specific command.

t help

Update your status

t update "I'm tweeting from the command line. Isn't that special?"

Note: If your tweet includes special characters (e.g. !), make sure to wrap it in single quotes instead of double quotes, so those characters are not interpreted by your shell. If you use single quotes, your Tweet obviously can't contain any apostrophes unless you prefix them with a backslash \:

t update 'I\'m tweeting from the command line. Isn\'t that special?'

Retrieve detailed information about a Twitter user

t whois @sferik

Retrieve stats for multiple users

t users -l @sferik @gem

Follow users

t follow @sferik @gem

Check whether one user follows another

t does_follow @ev @sferik

Note: If the first user does not follow the second, t will exit with a non-zero exit code. This allows you to execute commands conditionally. For example, here's how to send a user a direct message only if they already follow you:

t does_follow @ev && t dm @ev "What's up, bro?"

Create a list for everyone you're following

t list create following-`date "+%Y-%m-%d"`

Add everyone you're following to that list (up to 500 users)

t followings | xargs t list add following-`date "+%Y-%m-%d"`

List all the members of a list, in long format

t list members -l following-`date "+%Y-%m-%d"`

List all your lists, in long format

t lists -l

List all your friends, in long format, ordered by number of followers

t friends -l --sort=followers

List all your leaders (people you follow who don't follow you back)

t leaders -l --sort=followers

Mute everyone you follow

t followings | xargs t mute

Unfollow everyone you follow who doesn't follow you back

t leaders | xargs t unfollow

Unfollow 10 people who haven't tweeted in the longest time

t followings -l --sort=tweeted | head -10 | awk '{print $1}' | xargs t unfollow -i

Twitter roulette: randomly follow someone who follows you (who you don't already follow)

t groupies | shuf | head -1 | xargs t follow

Favorite the last 10 tweets that mention you

t mentions -n 10 -l | awk '{print $1}' | xargs t favorite

Output the last 200 tweets in your timeline to a CSV file

t timeline -n 200 --csv > timeline.csv

Start streaming your timeline (Control-C to stop)

t stream timeline

Count the number of official Twitter engineering accounts

t list members twitter/engineering | wc -l

Search Twitter for the 20 most recent Tweets that match a specified query

t search all "query"

Download the latest Linux kernel via BitTorrent (possibly NSFW, depending on where you work)

t search all "lang:en filter:links linux torrent" -n 1 | grep -o "[0-9A-Za-z]*" | xargs open

Search Tweets you've favorited that match a specified query

t search favorites "query"

Search Tweets mentioning you that match a specified query

t search mentions "query"

Search Tweets you've retweeted that match a specified query

t search retweets "query"

Search Tweets in your home timeline that match a specified query

t search timeline "query"

Note: In Twitter API parlance, your home timeline is your Newsfeed whereas your user timeline are the tweets tweeted (and retweeted) by you.

Search Tweets in a specified users timeline

t search timeline @sferik "query"


  • Deep search: Instead of using the Twitter Search API, which only goes back 6-9 days, t search fetches up to 3,200 tweets via the REST API and then checks each one against a regular expression.
  • Multi-threaded: Whenever possible, Twitter API requests are made in parallel, resulting in faster performance for bulk operations.
  • Designed for Unix: Output is designed to be piped to other Unix utilities, like grep, comm, cut, awk, bc, wc, and xargs for advanced text processing.
  • Generate spreadsheets: Convert the output of any command to CSV format simply by adding the --csv flag.
  • 95% C0 Code Coverage: Well tested, with a 2.5:1 test-to-code ratio.

Using T for Backup

@jphpsf wrote a blog post explaining how to use t to backup your Twitter account.

t was also mentioned on an episode of the Ruby 5 podcast.

t was also discussed on an episode of the Ruby Rogues podcast.

If you discuss t in a blog post or podcast, let me know and I'll link it here.

Relationship Terminology

There is some ambiguity in the terminology used to describe relationships on Twitter. For example, some people use the term friends to mean everyone you follow. In t, friends refers to just the subset of people who follow you back (i.e., friendship is bidirectional). Here is the full table of terminology used by t:

                          |                         |                         |
                          |     YOU FOLLOW THEM     |  YOU DON'T FOLLOW THEM  |
|                         |                         |                         |                         |
|     THEY FOLLOW YOU     |         friends         |        groupies         |        followers        |
|                         |                         |
|  THEY DON'T FOLLOW YOU  |         leaders         |
                          |                         |
                          |       followings        |


Timeline List

Shell completion

If you're running Zsh or Bash, you can source one of the bundled completion files to get shell completion for t commands, subcommands, and flags.

Don't run Zsh or Bash? Why not contribute completion support for your favorite shell?


The twitter gem previously contained a command-line interface, up until version 0.5.0, when it was removed. This project is offered as a successor to that effort, however it is a clean room implementation that contains none of the original code.


Supported Ruby Versions

This library aims to support and is tested against the following Ruby implementations:

  • Ruby 2.0.0
  • Ruby 2.1
  • Ruby 2.2
  • Ruby 2.3

If something doesn't work on one of these Ruby versions, it's a bug.

This library may inadvertently work (or seem to work) on other Ruby implementations, however support will only be provided for the versions listed above.

If you would like this library to support another Ruby version, you may volunteer to be a maintainer. Being a maintainer entails making sure all tests run and pass on that implementation. When something breaks on your implementation, you will be responsible for providing patches in a timely fashion. If critical issues for a particular implementation exist at the time of a major release, support for that Ruby version may be dropped.


If you are running t on a remote computer you can use the flag --display-uri during authorize process to display the url instead of opening the web browser.

t authorize --display-uri


Copyright (c) 2011-2016 Erik Michaels-Ober. See LICENSE for details. Application icon by @nvk.

t open issues Ask a question     (View All Issues)
  • almost 3 years `t list add` skips accounts
  • almost 3 years Request unmute feature
  • almost 3 years "t stream timeline" crashes after a few moments
  • about 3 years [feature] List Favourites
  • about 3 years t matrix just prints out non-stop japanese unicode characters
  • about 3 years Specify pry-byebug for Ruby v2.x
  • over 3 years POST et. all timeout ceilings need to be quadrupled
  • over 3 years can't end tweet with exclamation mark (dup #259)
  • over 3 years Missing set function
  • over 3 years `t delete favorite -f` not working
  • over 3 years Cancel pending requests
  • over 3 years Search for tweets that haven't been favorited
  • over 3 years Direct messages 140-character limit.
  • over 3 years Can not run `t authorize`, undefined method error from oauth.
  • over 3 years T stopped working after latest updates on Ubuntu/AWS
  • over 3 years Cryptic error message
  • over 3 years pipe stream
  • over 3 years t does nothing
  • over 3 years search trends (hashtag)
  • over 3 years Growl notification on new event (tweet)?
  • over 3 years Building t on OSX
  • over 3 years Search: Internal error
  • over 3 years SSL certificate issues
  • almost 4 years One thing to be perfect
  • almost 4 years How do I limit timeline or mentions to < 20?
  • almost 4 years [feature] Reply to a tweet without having the handle
  • almost 4 years Sample command isn't working
  • almost 4 years Feature Req: Non-interactive with "-f force" or "-y yes"
  • almost 4 years thor error
  • almost 4 years How to tweet with line breaks (new lines)?
t open pull requests (View All Pulls)
  • Allow multiple options for exclude.
  • Replace new lines in print_csv_tweet.
  • Stream your timeline in medium format.
  • Add ability to show conversation (in reply to) for a tweet
  • Prevent crash on empty list of followers
  • Added 'blocks' command.
  • Render images with netpbm
  • replies
  • Don't try to sort_by unnamed users
  • Remove trailing whitespace
  • Added instructions to README on using an application from a different account
  • Clarify deep search
  • Added docs for recommended way to install completions in ZSH (fixes #9)
  • Fix spacing consistency issues in
  • for cli.rb#timeline: --max_results option and silent-error-handling
  • Optionally display Twitter Name next to the @screenName in stream
  • more proper "following" list creation
  • Add support for looking up Place by ID. Add support for querying Places ...
  • Added time since tweet after username when viewing timeline and direct m...
  • Add completions for fish shell
  • Add filename completions for --file args
  • Added Missing set function
  • Updated help text for trends to match actual amount returned.
  • update user timeline definition
  • Specify pry-byebug for Ruby v2.x.
  • Update README with delete status usage example
  • fix double quotation error in bin/t
  • [Issue No #352] Fix --csv option doesn't escape newlines
  • Fix order dependent tests by resetting `host_os` after changing
  • Fix Rubocop (and therefore CI)
  • Fix Markdown links
  • s/2016/2017/
  • added functionality
  • Update license date
  • Update ruler length to 280 characters
  • changed 140 to 280 in the help text
  • Fix version dependencies and fix tests
  • Update README
  • update license date
  • Adds --full-text option to direct-messages command. Fixes #371
t questions on Stackoverflow (View All Questions)
  • Play Json: defining a Reads[T] that parses a JSON array and ignores certain elements
  • List<T> thread safety
  • std::move or std::forward with parameter std::unique_ptr<T>&&
  • t-sql user defined function to replace text with a lookup from a table
  • Kotlin: How can I extend a generic class (of "<T>")?
  • My switch statement won´t let me use a particular variable as an expression
  • When do Java generics require <? extends T> instead of <T> and is there any downside of switching?
  • How to get IntPtr of the array within List<T>?
  • Windows Phone emulator not starting (couldn`t setup the UDP port)
  • Can´t use Tomcat v8.0 server
  • Combine command line and T-SQL - SQL Server
  • How to add Create and Edit View to Model with IEnuernation<T> properties?
  • Can`t deploy Java restful WS using Maven, TomEE and Jersey
  • How can i convert Func<T,object> to PropertyInfo
  • How to write a function in T-SQL, which accepts a table as input and returns result back as a table?
  • Awaiting a TaskCompletionSource<T> that never returns a Task
  • Using AutoMapper to map Wrapper<T> to T' by convention
  • Why IList<T> does not contain a Length property?
  • How to solve this recursion equation T (n) = √2T(n/2) + log n using master theorem?
  • T-SQL: 'where' query - multiple columns to match on
  • T-SQL Multiple Pivot Column Issue
  • What is the big O notation complexity of an algorithm with T(N) = 16N+8N^2+N^2log(n)+6NK+5N^2K-5NK^2
  • Expected invocation on the mock once, but was 0 times, with Func(T, TResult)
  • T-SQL XOR Operator
  • lisfragment and intent doesn`t work correctly
  • T must be a non-abstract type with a public parameterless constructor in order to use it as parameter 'TModel' in the generic type or method
  • Wia code won`t work with kodak scanmate i1120 scanner
  • final = P * (((1 + (r/n)) ** (n*t))) TypeError: unsupported operand type(s) for /: 'str' and 'int'
  • Is ConcurrentQueue<T> Class really thread safe?
  • Swift: how to make my custom struct Node<T> conform to Hashable?
t list of languages used
Other projects in Ruby