oysttyer User Guide

   ;',. ./#`                                                   
  ({.`,` #/                 
  `& ,` %,~=*'"*=~=-.,      
   \`=_/'.``  -  `'.  *\.                                      
    (%.  -  -      ˋ-. `&   
    `&`  ~     @      . #                                       
     `\`. `    .....ˊ  %'   

  _      _             _     
 /.\ | ||_  |_ |_ | | /_\|'`                                 
 \_/ \_| _|'|_'|_ \_| \_ |                                   
       |            |       

Getting started

Welcome to oysttyer, a console-based Twitter client written in Perl. This guide describes the basic use of oysttyer. If anything is unclear, incorrect, or missing, please let us know.

Getting the code

oysttyer is a single Perl script. You will, of course, need a Perl interpreter and also cURL (included by default on most Linux and Unix distributions). You may also want Term::Readline::TTYtter in order to take advantage of some of the more colorful things oysttyer can do.

There are two options for getting oysttyer: a “stable” release version and the latest development version. In practice, there is not much difference between the two since new releases happen quickly after bugs are fixed or features are added and development changes are (we hope!) not going to break anything.

To get the stable release, go to the GitHub repository and click “Releases” download the most recent release and extract it.

To get the latest development version oysttyer, you can clone the GitHub repository or simply download the raw oysttyer.pl file.

Generating your API key

Before you can get started, you should generate an API key. The key built in to oysttyer is frequently blocked by Twitter, so using your own key is adviseable.

  1. Log in to the Twitter Application Management page with your Twitter user name and password
  2. Click Create New App
  3. Fill out the new app form:
  4. Check the box to agree to the developer agreement and click Create Your Twitter Application
  5. Update your application to be able to send and receive direct messages
  6. Get your keys

Now that you have your keys, you can authorize oysttyer. Your key and secret can be passed on the command line or in your configuration file. An example of using it on the command line is:

perl ./oysttyer.pl -oauthkey=nZdXCxVtQTsFJaybAr9OjApd0 -oauthsecret=ujN4ilao663PyDDgObkk0N6EIbAxxxG7MGoK2Yq7nzLLfOxZjE

Similarly, the configuration file settings are oauthkey and oauthsecret for the Consumer Key and Consumer Secret respectively.

A third option is to generate your token and secret from the Application Management website and write that directly to the .oysttyerkey file:


Switching from TTYTter

If you previously used TTYtter, you should find oysttyer very familiar. A few steps are necessary to make the switch:

  1. You have to re-authorise (you can’t use your .ttytterkey) as we have a new API key
  2. Move/rename your .ttytterc file to .oysttyerrc
  3. If you use the ttytteristas pref it is now called oysttyeristas
  4. Read the Changelog to see what’s new since TTYtter 2.1

Basic usage

To start using oysttyer, run perl ./oysttyer.pl in the directory where you’ve downloaded osytter.pl. Soon tweets start spewing forth. Each tweet is displayed with an menu code (internal to oysttyer) and the username. For example:

h8> <FunnelFiasco> I just really like writing documentation.

Menu codes are typically a letter followed by a single-digit number, except direct messages which prepend a d and search results (including threads, /again, etc) which prepend a z.

The username may also be prepended with special characters that give you more information about a tweet.

Decorator Meaning
@ Tweet is in reply to another tweet
Tweet quotes the tweet below
Tweet was quoted by the tweet above</td
% Tweet was retweeted into your timeline
+ Tweet has location information

Ready to tweet? Just type your tweet and hit enter. But simply broadcasting is no fun (even if it’s your personal #brand). Interaction is what makes twitter enjoyable. The commands section below describes how you can interact.


oysttyer provides many commands, all of which begin with /. For the sake of your followers, anything that starts with / is treated as a command and oysttyer will let you know if it doesn’t recognize it. If you want to start a tweet with /, double it (//). The tables below describe most of the oysttyer commands, in hopefully-helpful sections:

Commands that return multiple responses default to 20, but that can be adjusted by specifying +N after the command name. For example:

/dmagain +5

will only give you your last 5 direct messages, instead of the last 20.

oysttyer commands

Command Description
/! shell command Run shell command in a subprocess
/add key value Add value to key (see the runtime configuration section for more information)
/cls Clear the screen
/del key value Remove value from key (see the runtime configuration section for more information)
/help Display help
/history Display your command history
/pop key Pop the first value off of key (see the runtime configuration section for more information)
/print key Display all settings (or the value of key, if specified)
/push key value Push value onto the stack for key (see the runtime configuration section for more information)
/ruler Print a “ruler” of 140 characters
/set key value Set key to value (see the runtime configuration section for more information)
/unset key Unsets key (see the runtime configuration section for more information)
/vcheck Check to see if you’re running the latest version
/quit Exit oysttyer

Tweet commands

Command Description
/re menu code Reply to tweet menu code
/ra menu code Reply to all users in tweet menu code
/rt menu code message Retweet tweet menu code. If a message is specified, quote tweet menu code
/like menu code Like tweet menu code
/unlike menu code Remove like for tweet menu code
/lrt menu code Like and retweet tweet menu code
/thread menu code Displays the thread for tweet menu code
/again username Displays the recent tweets for username (if none is specified, shows recent tweets in your timeline again)
/deletelast Deletes your last tweet
/delete menu code Deletes tweet menu code
/dump menu code Display all data for tweet menu code
/dm username message Send a direct message to username
/dmsent Display direct messages you have sent
/dmagain Display direct messages sent you you
/dmrefresh Check for new direct messages
/entities menu code Display the expanded t.co links in tweet menu code
/search keyword Search public tweets for keyword
/refresh Check for new tweets
/rtsof menu code List accounts that retweeted tweet menu code
/rtsofme List your tweets that others have retweeted
/track keywords Search for keywords in addition to your normal timeline
/tron keywords Add additional keywords to /track
/troff keywords Stop /tracking keywords
/trends List the current trending topics
/url menu code Display the URLs in tweet menu code and open in the application defined by the urlopen option
/web menu code Display the URL to tweet menu code

User commands

Command Description
/follow username Start following username
/unfollow username Stop following username
/leave username Alias for /unfollow
/block username Block username
/unblock username Un-block username
/mute username Mute username
/unmute username Un-mute username
/whois username Display information for username
/doesfollow username seconduser Check if a user follows another (if a second account is not specified, it checks if the user follows you)
/friends username Get a list of the user’s friends (if an account is not specified, it lists your friends)
/followers username Get a list of the user’s followers (if an account is not specified, it lists your followers)

List commands

/withlist listname create (private|public) text Create your own list listname, and make it either private or public, (text : an optional description of the created list)
/withlist listname add username Add user username to your own list listname
/withlist listname delete username Add user username to your own list listname
/withlist listname list Show who’s on your list listname
/withlis, /withl, /with, /wl Aliases for /withlist
/lists Displays your lists
/lists username Displays lists of the specified user username
/lists username/listname Displays who’s on the specified list of the specified user username
/lfollow listname Start following listname This only marks you as a follower, it does not actually add the list to your timeline
/lleave listname Stop following listname
/liston listname Sets lists that are automatically queried and mixed with your timeline (You do not have to be following a list to add it to your timeline)
/listoff listname Turn off showing tweets from that list in your timeline
/followers listname Displays users who are marked as following the specified list

Command Line Options

Oysttyer inherits many commands from ttytter. The full list of commands supported by ttytter is documented here but some of the more useful ones are:

Command Description Example
-rc Location of config file -rc=oysttyerrc
-keyf Location of Key file -keyf=mykeyfile
-status Tweet directly from the command line -status=“I’m on a boat”
-verbose Give more debugging information -verbose
-location Set your location - Note: you must enable tweet locations on the web interface -location
-lat latitude in decimal -lat=-43.55522919
-long longitude in decimal -long=172.4193726
-script Forces mode designed for being called via a script file, with minimal output -script
-separator string Separate refreshes by string to mark your place -separator=“X—x—X—x—X”
-doublespace Print an extra space after each tweet -doublespace


You can set many options using command line options:

$ perl ./oysttyer -ansi=1 -newline=1 -vcheck

but these can also be set in a configuration file. The standard file is ~/.oysttyerrc, but another one can be chosen using the -f command line option.

The same options above can be written in the configuration file like this


Use # to denote a comment.

For security and portability, it’s recommended that your Twitter credentials be kept in a separate file, ~/.oysttyerkey. This file should be chmod 600 (user read+write).


Development is done via GitHub, the CONTRIBUTING document has details.