Ruby gem CLI tool that downloads the most recent images from Twitter based on the search terms provided
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Gem Version Circle CI Code Climate Test Coverage

This is a CLI tool for downloading the most recent images off of Twitter based on the search terms you provide.


I've recently started a major overhaul of the gem's structure. However, it's still a work in progress, and there is a lot I want to add and change.

For the list of possible future changes see the Trello board.


Execute this in the terminal:

$ gem install twitter_images


alt tag

After installing the gem you need to run the following command to authorize the app with Twitter:

twitter_images -a

After that, your credentials will be saved in your home directory, inside a twitter_imagesrc file. No need to set up any environment variables anymore. If you remove the configuration file, you can simply run the command again to re-authorize the app.

The CLI format is as follows: twitter_images [path] [search terms] [amount]

For example:

twitter_images ./test_pics "#cats" 50

will download 50 pictures into your ./test_pics directory.

You can search for hashtags and multiple words if you enclose your search terms in quotes. You can also search for non-hashtags words like so:

twitter_images ./test_pics friends 150

Please note that the Twitter API rate limit is 180 calls every 15 minutes.


If you want to build a runnable version yourself, follow these simple steps

  • Create your own Twitter Application

  • Get your Twitter application's API key and secret

  • Put those in the lib/twitter_images/consumer.rb:

def consumer_key

def consumer_secret
  • Install locally with bundle exec rake install


  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request