Skip to content


Folders and files

Last commit message
Last commit date

Latest commit



93 Commits

Repository files navigation

Facebook CLI

Facebook functionality from the command line.

Download the gem at Join the chat at Take a moment to thank @specious



gem install facebook-cli (might require sudo)

Facebook setup

To interact with the Facebook API you must create and configure a Facebook application for your personal use. Follow these instructions carefully:

  • Go to and create a new app (screenshot)

  • Set up a new "Facebook Login" product

  • Don't bother choosing a platform. Instead click "Settings" under "Facebook Login" in the side bar

  • Under "Valid OAuth redirect URIs", add: https://localhost:3333/ (this is needed to receive auth code during authentication)

  • Click "Save Changes"

  • Go to "App Review" and make your app public

  • Go to "Settings" > "Basic"

  • Under "App Secret" click "Show" to reveal your app secret

  • Open a terminal and save your App ID and App Secret by running: (screenshot)

    facebook-cli config --appid=<app-id> --appsecret=<app-secret>

Logging in

Once the Facebook app is configured, you must authorize it to access the social graph on your behalf:

  • In a terminal, run: facebook-cli login (screenshot)
    • (If authenticating on a remote machine or using a different port to receive the auth code: facebook-cli login --host <hostname-or-ip> --port <port>)
  • Open the given URL in a web browser, and log into your Facebook account if prompted
  • Click "Continue" to approve the permissions (screenshot)
  • Select the scope of your audience for any posts you publish using this application (screenshot) (read more)
  • Click "Ok" to continue
    • If you're using Firefox and you get a SEC_ERROR_REUSED_ISSUER_AND_SERIAL error, just copy the URL and run curl -k <url> in a terminal
  • Close the browser tab (screenshot)


Running facebook-cli or facebook-cli help shows the list of available commands:

    api        - Make a direct Facebook API request
    config     - Save your Facebook API credentials
    feed       - List posts on your timeline
    help       - Shows a list of commands or help for one command
    likes      - List pages you have 'Liked'
    links      - Some useful URLs
    login      - Request Facebook permissions and receive an API access token
    logout     - Deauthorize your access token
    me         - Show your profile information
    photos     - List photos you have uploaded
    photosof   - List photos you are tagged in
    videos     - List videos you have uploaded
    videosof   - List videos you are tagged in

Run facebook-cli help <command> for more details on each command.

Converting output to HTML

Use a Markdown renderer to easily convert the output to an HTML document. For example, using Pandoc:

facebook-cli likes | pandoc -s -f markdown_github > likes.html

See: example

Things created with facebook-cli

  • Facebook Friends - Build a page that lets you click your friends' profile pictures to jump to their timelines

  • Facebook Browser - Build a searchable index of all the Facebook pages you follow

  • Screensaver that prints the titles of all of your 'Liked' Facebook pages, made by using the output of facebook-cli likes | awk 'NR % 3 == 1' | perl -p -e "s/\n/ - /" as the text input to the Phosphor screensaver

Why can't I...?

Facebook has removed a large portion of their Graph API starting with version 2.0. Niraj Shah has done a fantastic job documenting the cutbacks and their implications in these blog posts:

An article published in October, 2012 by Facebook developer Henry Zhang provides insight into the reasoning:

Post to friends wall via the API generate a high levels of negative user feedback, including “Hides” and “Mark as Spam" and so we are removing it from the API. If you want to allow people to post to their friend’s timeline from your app, you can invoke the feed dialog.

More recent changes outlined on Facebook's developer portal cover further massive deprecations enactedin 2018, which have eliminated facebook-cli's ability to access past and upcoming events, publish content and retrieve names of taggable friends, as was still possible with the previous long-standing restriction. facebook-cli's available functions have been pruned to reflect the latest changes.

The functionality removed renders it impossible to build a full-featured interface to Facebook through the Graph API alone.

If you expand the functionality of facebook-cli in any way, please open a pull request.


Clone this repository, then use Bundler to install Ruby dependencies:

gem install bundler
bundle install

You should now be able to run facebook-cli from the bin directory:

bundle exec bin/facebook-cli

facebook-cli depends on the Koala library for interfacing with Facebook's Graph API and GLI for parsing command line arguments.

Using a ruby environment manager such as rbenv or rvm is advisable to avoid environment conflicts between projects.

If you'd like to contribute, please take a brief look at the guide.

Other Facebook client software in the open source community