oysttyer User Guide

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

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

• Getting started
  • Getting the code
  • Generating your API key
  • Switching from TTYtter
• Basic usage
  • Commands
• Command Line Options
• Configuration
• Feedback and contributing

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:
   • Name – The globally unique name for your application. We suggest something like “oysttyer (YourCoolTwitterHandle)”
   • Description – Please use “An interactive console text-based command-line Twitter client written in Perl”
   • Website – Please use “http://oysttyer.github.io/”
   • Callback URL – (leave blank)
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
   • Click the Permissions tab
   • Select Read, Write and Access direct messages
   • Click Update application
6. Get your keys
   • Click the Key and Access Tokens tab
   • Note the Consumer Key (API Key) and Consumer Secret (API Secret).

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:

ck=X&cs=X&at=YOUR_ACCESS_TOKEN&ats=YOUR_ACCESS_TOKEN_SECRET

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.

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.

Commands

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:

• oysttyer commands
• tweet commands
• user commands
• list commands

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

Tweet commands

User commands

List commands

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:

Configuration

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

ansi=1
newline=1
vcheck=1

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

Contributing

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