x-cli Documentation

A command-line power tool for Twitter.

5,590 stars Ruby Ruby 2 files · ~3,735 tokens
RAW Doc

Technical Documentation: sferik/x-cli

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`)

x

A command-line interface for the X API.

Features

  • Full command tree with aliases and options
  • X API client library (x-api) for HTTP, auth, and retry primitives
  • OAuth 1.0a and OAuth 2.0 authentication
  • Automatic retry with backoff for transient API errors
  • V1.1 and V2 API support with automatic fallback
  • Streaming support for filtered and sampled streams
  • Column-aligned output formatting
  • YAML configuration file support
  • Bash completion support

Status

  • Command families: cli, delete, list, search, set, stream
  • Local account/profile commands: accounts, set active, delete account, version, ruler
  • Stream commands use persistent HTTP streaming:
    • stream all and stream matrix use OAuth2 sample stream
    • stream search, stream users, stream list, and stream timeline use v2 filtered stream rules + stream
  • X_STREAM_MAX_EVENTS can be set to limit emitted events (useful for tests/automation)
  • Default profile config is ~/.xrc. If ~/.xrc is missing, ~/.trc is used as a read fallback and migrated on write.

Development

bash
cargo test
cargo run -- version
cargo run -- accounts --profile /path/to/.xrc

Releasing

Tagging a new v* release triggers GitHub Actions to build and publish binaries for:

  • Linux (x86_64-unknown-linux-gnu)
  • Linux ARM64 (aarch64-unknown-linux-gnu)
  • macOS Intel (x86_64-apple-darwin)
  • macOS Apple Silicon (aarch64-apple-darwin)
  • Windows (x86_64-pc-windows-msvc)
  • Windows ARM64 (aarch64-pc-windows-msvc)

Install cargo-release:

bash
cargo install cargo-release --locked

Then tag and push the current Cargo.toml version:

bash
cargo release-tag

Tag messages come from Cargo.toml release metadata (tag-message).

Overview (`legacy/README.md`)

[][icon]

Twitter CLI




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.

Dependencies

First, make sure you have Ruby installed.

On a Mac, open /Applications/Utilities/Terminal.app and type:

text
ruby -v

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

text
ruby 3.4.3 (2025-04-14 revision d0b7e5b6a0) +PRISM [arm64-darwin24]

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

text
ruby: command not found

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

text
sudo apt-get install ruby-dev

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

text
sudo yum install ruby-devel

(if necessary, adapt for your package manager)

On Windows, you can install Ruby with RubyInstaller.

Installation

Once you've verified that Ruby is installed:

text
gem install t

Configuration

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 https://apps.twitter.com/app/new. If you've
previously registered a Twitter application, it should be listed at
https://apps.twitter.com/. 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:

text
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 https://support.twitter.com/forms/platform, selecting the last checkbox. Some users have reported success adding their number using the mobile site, https://mobile.twitter.com/settings, 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:

text
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:

text
t accounts

The output of which will be structured like this:

text
sferik
  UDfNTpOz5ZDG4a6w7dIWj
  uuP7Xbl2mEfGMiDu1uIyFN
gem
  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:

text
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.

text
t help

Update your status

text
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 \:

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

Retrieve detailed information about a Twitter user

text
t whois @sferik

Retrieve stats for multiple users

text
t users -l @sferik @gem

Follow users

text
t follow @sferik @gem

Follow all users from a list

text
t list members -l list | awk '{print $13}' | xargs t follow

Check whether one user follows another

text
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:

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

Create a list for everyone you're following

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

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

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

List all the members of a list, in long format

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

List all your lists, in long format

text
t lists -l

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

text
t friends -l --sort=followers

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

text
t leaders -l --sort=followers

Mute everyone you follow

text
t followings | xargs t mute

Unfollow everyone you follow who doesn't follow you back

text
t leaders | xargs t unfollow

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

text
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)

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

Favorite the last 10 tweets that mention you

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

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

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

Start streaming your timeline (Control-C to stop)

text
t stream timeline

Count the number of official Twitter engineering accounts

text
t list members twitter/engineering | wc -l

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

text
t search all "query"

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

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

Search Tweets you've favorited that match a specified query

text
t search favorites "query"

Search Tweets mentioning you that match a specified query

text
t search mentions "query"

Search Tweets you've retweeted that match a specified query

text
t search retweets "query"

Search Tweets in your home timeline that match a specified query

text
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 user’s timeline

text
t search timeline @sferik "query"

Features

  • 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:

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

Screenshots

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?

History

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 3.2
  • Ruby 3.3
  • Ruby 3.4

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.

Troubleshooting

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.

text
t authorize --display-uri

Copyright (c) 2011-2025 Erik Berlin. See LICENSE for details.
Application icon by @nvk.

--- METRICS ---

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →