[Back to the Floodgap main page] Return to Floodgap Software

TTYtter for Perl (Legacy 0.9.12)

Hey, you should probably read this. Yeah, you.

This is version 0.9.12 (14 February 2010), the final version of the long-lived 0.9 branch. There will be no further bug-fixes to this branch and is provided for those who can't or prefer not to use the current version, or have an application depending on the old TTYtter API.

If you need an even older version, you can also get 0.8.6, or browse all pre-1.0 versions. These versions are equally unsupported, and may not even work in the future.

If you came here by mistake and want the current version, go back to the main page. Otherwise, we assume you know why you're here and just want to download 0.9.12.

Noooo, not another Twitter client! Yes, another Twitter client. The difference here is that you're dealing with a multi-functional, fully 100% text, Perl command line client.

TTYtter requires Perl 5.005 or better (5.6 and up are recommended), and either cURL or Lynx (chosen on purpose since more people are likely to have one or both of those instead of LWP, and also to allow people to carry over their proxy settings and whatnot). Nothing else is necessary; it does not use Net::Twitter and does not require it, and in fact will run happily with just a bare Perl and cURL/Lynx with no libraries at all like on my OLPC XO-1. It will work fine over any dummy terminal, serial connection or telnet/ssh login. TTYtter is offered as freeware under the Floodgap Free Software License.

Basic use: TTYtter as a basic interactive client

To use ttytter as a basic regular interactive client, chmod +x and run from the command line. If your Perl is not in /usr/bin, change the first line (/usr/bin/env on some systems does not support passing arguments in shebang lines, so for maximum compatibility it is not used here). You will need to specify your username and password with the -user option, like so:

% ./ttytter -user=screwtape:wormwood

(NB: If you have a password like pa$$word that has shell metacharacters in it, you may need to single quote it like ./ttytter '-user=screwtape:pa$$word'. In 0.9.5 and earlier you needed to backslash them also, but not as of 0.9.6.) Yes, you can put the password in an external file; more about that when we get to .ttytterrc.

If you don't want to type your password on the command line, then just use a username like -user=screwtape, and TTYtter will ask for the password. (You should still backslash metacharacters in those same older versions.)

If ttytter complains that it cannot enable UTF-8 support, re-run it with the -seven option for now. You might want to look at the TTYtter and UTF-8 section later.

ttytter will next try to detect which client you have (it prefers cURL but you can force Lynx with -lynx; Lynx 2.8.6 or higher is strongly advised), and then starts up if it can run a test query successfully. It then starts a background process that will automatically get new tweets and, at less frequent intervals, direct messages. When it comes up, it looks something like this:

trying to find cURL ... /usr/bin/curl
-- no version check performed (use -vcheck to check on startup)
test-login SUCCEEDED!

######################################################        +oo=========oo+ 
        TTYtter 0.9.12 (c)2010 cameron kaiser                 @             @
                 all rights reserved.                         +oo=   =====oo+
       http://www.floodgap.com/software/ttytter/            a==:  ooo
                                                            .++o++. ..o**O
  freeware under the floodgap free software license.        +++   :O:::::
        http://www.floodgap.com/software/ffsl/              +**O++ #   :ooa
         tweet me: http://twitter.com/ttytter                      #;;ooo;;
            tell me: ckaiser@floodgap.com                          #+a;+++;O
######################################################           ,$B.*o*** O$,
#                                                                a=o$*O*O*$o=a
# when ready, hit RETURN/ENTER for a prompt.                        @$$$$$@
# type /help for commands or /quit to quit.                         @o@o@o@
# starting background monitoring process.                           @=@ @=@
TTYtter> a0> <barely> Looks like I am going to Baltimore next week
a1> <pamela> Redesign for bookstore website is almost done! RFP for custom publishing projects in the works due to start in Sept. Keeping busy.
-- checking for most recent direct messages:
[DM da0][cbqueue/Fri Sep 28 02:01:33 +0000 2007] test test
[DM da1][ttytter/Fri Sep 28 03:01:51 +0000 2007] don't forget to update the website
-- notification: API rate limit is currently 100 req/hr
-- no version check performed (use -vcheck to check on startup)

At this point, the client is ready to go and you can start tweeting, and we'll talk about that below. If you're not seeing ANSI colours and you know your terminal supports it, either use the -ansi option on the command line or type /set ansi 1 now. Your terminal must understand ANSI colour escape sequences or things will look rather weird. There are other things we can also enable (all in good time):

Like with the ANSI example above, once you find a set of options you like, you can put them into the .ttytterrc file in your home directory along with your username and password if you prefer. See Command-line options: the .ttytterrc file for how to do this. You can even select from multiple .ttytterrc* files using the -rc option; see the same link.

Basic use: TTYtter as a command-line posting agent

If you specify any arguments on the command line (like ttytter foo), then foo is seen as a filename to read tweets and commands from instead of standard input (a "script"). A fatal error will occur if foo doesn't exist. You can pipe data to TTYtter as well; it will terminate when it runs out of stdin to read.

You can also use the -status=... option to post a single tweet, which is more efficient (and can be made bulletproof using the -hold option):

% ./ttytter -user=screwtape:wormwood -status="Writing a letter to my nephew."

For some scripts, that's all you'll need to get started. We'll talk about scripting TTYtter in a moment, but first let's get to the

Table of contents (it's not that complex, I swear!)

User's guide:
Basic tweeting | Built-in commands
Direct messaging | Replying to tweets/DMs, threading ("in reply to"), favourites
Following and leaving users (and other Twitter-handled commands) | Tracking keywords and hashtags/Twitter Search API | Command history and substitution

Special features:
TTYtter and UTF-8 support | TTYtter and SSL | TTYtter and notification support, Growl, libnotify
TTYtter and Laconi.ca/Identi.ca
TTYtter and your special terminal environment | TTYtter and readline support
Scripting TTYtter | Extending TTYtter with custom behaviour

Basic tweeting

By and large, most people use TTYtter as an interactive client. In this mode, it acts much like a command line IRC or micq. Like such clients, unless you specify otherwise, updates occur automatically and without any intervention from you, although you can request an update early (see Built-in commands).

To send a tweet, just type it. It will be submitted and appear on the next update. Keep in mind that posting tweets and executing most commands are asynchronous operations, so don't expect instant feedback.

If an update occurs and your tweet is overwritten on screen, don't worry: just hit CTRL-R, and the line you're currently working on will be redisplayed. (If you have -readline, SPACE/BACKSPACE will usually do it; see TTYtter and readline.)

If you want to cancel what you're typing and start over, press CTRL-U.

If your tweet is over 140 bytes, it will be automatically trimmed (hopefully intelligently to a word or punctuation boundary) and you will be offered a chance to accept or edit the trimmed version. This affects the command history. If you use the -autosplit option, you can let TTYtter break up long lines for you into multiple tweets (see Command-line options). (NB: bytes != characters. See TTYtter and UTF-8 support for why this matters.)

If your terminal supports ANSI colour sequences (or you force it on with -ansi), then replies to you appear in red, and your own tweets appear in yellow, by default.

If tweets are too wide for your screen, you can wordwrap them with the -wrap option. This defaults to 79 characters, sufficient for most terminals and terminal programs.

If you keep fat-fingering your tweets, or are prone to cutting and pasting in the wrong window, or just want a second chance to approve stuff before it goes out to the Interwebs, you can force TTYtter to verify every tweet you (unintentionally or otherwise) type with the -verify option. A gentler option might even be -slowpost.

If TTYtter can't download any tweets or messages, or if the Obvious folks have put up an announcement or service outage page, ttytter will report the error and retry automatically when it can. If your terminal supports ANSI colour sequences (or you force it on with -ansi), then server messages appear in magenta by default.

Built-in commands

Speaking of commands, there are also some ttytter internal commands you can use. All internal commands start with /. Starting with 0.6, if you enter a bogus command, ttytter will complain at you instead of tweeting it, which should cut down on mildly useless but enormously entertaining tweets like /quot and /refrehs. If you really want to send a tweet that starts with a slash, just double slash it (e.g., //the ants are my friends/they're blowing in the wind/) and the double slash will be made a single slash and passed on.

Starting with 0.6, most commands have a quick abbreviation, which is given in parentheses. Most commands are asynchronous, meaning that you can do stuff in the foreground while the background process does the work, but some are synchronous and will hold your console temporarily for technical reasons.

Not all commands work or are fully supported in earlier versions.

/help (/?)
Displays mad-k001 ASCII art. Oh, and a quick list of commands, secondarily speaking.
/refresh (/r)
Thumps the background process to do another update for new tweets right away instead of waiting for the next one scheduled. Remember, Twitter only gives us the last twenty tweets, so you will therefore only get the last twenty too (important if you're watching the public timeline, or have a lot of friends). If nothing new is available, the background process will politely tell you so. (/thump is a synonym since I keep typing it.)
/again (/a)
Displays the last twenty tweets from your timeline, even old ones, along with refreshing the most recent results from keywords and hashtags you may be tracking (if any).
/again [username] (/a [username])
Displays the last twenty tweets for user username (sans braces, of course). If the user doesn't exist, or is protected/otherwise not available to you, you will get an error message instead. This command is synchronous and the foreground process will pause until the tweets are received or timed out.
/whois [username] (/w [username])
Displays the Twitter "vital statistics" for the specified user, including number of people they follow and are followed by (f:), number of updates (u:), real name, location, description, URL and image/picture, along with (if you are not anonymous) if you already follow this user and if this user follows you. Their URL, if they have one, is loaded into the variable %URL% so you can substitute it in a tweet (see command history and substitution below), /shorten it, or open it with /url.

If you specify a filter with -avatar, then the URL for the user's picture is passed to the specified shell command to operate upon it, including saving it, opening it in a window somewhere else, or even converting it to ASCII art. See Command-line options for more. This command is synchronous and the foreground process will pause until the data is received or timed out.

/wagain [username] (/wa [username])
Combines /again followed by /whois (yes, the name is out of order, but it sounded better than /againw).
/dmrefresh (/dm)
Thumps the background process to do another check for direct messages right away instead of waiting for the next one scheduled. Again, this is limited to the last twenty, if you are a particularly popular person to whisper to. See the section on direct messaging below.
/dmagain (/dma)
/replies (/re)
Displays your last twenty @ replies. This may be affected by your Twitter account notifications settings. This command is synchronous and the foreground process will pause until the replies are received or timed out.
/reply [menu code] [tweet] (/re), /vreply [menu code] [tweet] (/vre), /thread [menu code] (/th)
This set of commands respectively replies directly to a tweet or direct message using threading if possible (the first using conventional replies; the second using a publicly visible reply a la "r @al3x Twitter API roxx"), and the last displays the thread a tweet is part of (if any). See the sections on tweet selection and DM selection below.
/delete [menu code] (/del)
Deletes a tweet (only your own tweet -- nice try) or a direct message. See the sections on tweet and DM selection below.
/favourite [menu code] (/fave, /f), /unfavourite [menu code] (/unfave, /unf)
Favourites or unfavourites a tweet, respectively. See the section on tweet selection below.
/favourites (/faves, /fl)
Displays your most recent favourite tweets. This command is synchronous and the foreground process will pause until the data is received or timed out.
/favourites [username] (/faves [username], /fl [username])
Displays someone else's most recent favourite tweets. This command is synchronous and the foreground process will pause until the data is received or timed out.
/retweet [menu code] (/rt), /eretweet [menu code] (/ert), /fretweet [menu code] (/frt)
Retweets a tweet (direct messages, wisely, not allowed). /eretweet loads the tweet into the special substitution variable %RT% which you can use at the beginning or end of your next tweet; regular /retweet just sticks on RT @username: and sends it right away. If you really like the tweet, then /fretweet will favourite it for you at the same time as you retweet it. See the sections on tweet selection and command history/substitution below.
/search [query] (/se)
Queries the Twitter Search API, as if you had typed it into the box on search.twitter.com, and displays the most recent results. See the section on Search API integration below. This command is synchronous and the foreground process will pause until the data is received or timed out.
/track [keywords] and /tron [keywords], /troff [keywords], /#[hashtag], /notrack
Keyword and hashtag tracking (respectively: set your keywords, add a keyword, remove a keyword, shortcut for adding a hashtag, and cancel all tracking keywords). See the section on Search API integration below.
/trends (/tre)
Asks the Twitter Search API for the most current trending topics. Displays them as /search and /tron commands (qq.v.) you can simply cut and paste to execute. See the section on Search API integration below. This command is synchronous and the foreground process will pause until the data is received or timed out.
/versioncheck (/vcheck)
Pings the floodgap.com server (this one!) to see if you are using the most current version.
/short (/sh)
Shortens a supplied URL (by default using the is.gd service, but may be compatible with others). The new shortened URL is displayed and you can substitute it at the beginning or end of subsequent tweets using %URL% (see command history and substitution). If you don't specify a URL, then the current value of %URL% is substituted.
/url [menu code]
Opens the URL(s) specified in the tweet or direct message indicated by the selected menu code, according to the current -urlopen option. See the sections on tweet and DM selection below. If you don't specify a menu code, then the current value of %URL% is substituted (you can also use an arbitrary URL if you like). (Nota bene: While /url will accept UTF-8 characters as valid parts of a URL (damn you tinyarro.ws), that doesn't mean your underlying browser will.)
/dump [menu code] (/du)
Dumps out the internal structure for the tweet referenced by the specified menu code (which, if only stored in TTYtter's backing store, may omit fields irrelevant to TTYtter). This is mostly for debugging, but useful for people who want to grab URLs to individual tweets, as the URL for this particular tweet is placed into %URL% for additional use.
Allows you to enter a shell command from within TTYtter. This is run with whatever Perl thinks your shell is (inside system()); for example, /!ls displays the contents of the current working directory. Remember that this opens up subshells (on purpose), so you can't change, say, an environment variable this way and expect the Perl running TTYtter to see it.
/history (/h)
Displays the last set of commands entered (see Command history and substitution below).
/set [key] [value] (/s) and /print [key] (/p)
Allow setting and printing of command line options at runtime. Not all command line options can be changed. For more about this, see Command-line options.

If you type /print by itself with no key, the (visible) settable values are displayed.

For the IRC freaks. Simply echoed as a tweet, /me included.
/ruler (/ru)
Prints a "ruler," 140 characters wide plus the size of the prompt, as a convenient visual aid.
/quit (/q)
Leaves ttytter. Pressing CTRL-D or CTRL-C will also do this. It's preferable to use this command (or those keysequences) to exit ttytter because if you kill the console process outside of ttytter, the background process may not get cleaned up and will have to be killed separately. /exit and /bye are synonyms by popular request.

/quit immediately stops anything running in the background, including pending requests for new tweets or DMs. If you want to wait for these to complete, use /end (/e).

Direct messaging

Direct messages are handled like any other tweet, except they appear with special formatting to set them apart. Because most people receive more tweets than DMs, DM checks are handled less frequently than regular tweets (the default is to check every fourth time interval). Any new DMs are then displayed as part of the tweet stream. (Also see the -dmpause option under Command-line options.)

If your terminal supports ANSI colour sequences (or you force it on with -ansi), then DMs that you receive appear in green by default.

Since ttytter does not save state (on purpose), it doesn't know where you left off in your DM inbox. When you start ttytter, it will display the two most recent DMs and their time stamps. If both are new to you, a quick /dmagain will show you the full last twenty to see if there are any others.

To send a direct message, use the Twitter D command, e.g., D zaphod trillian is gonna kill you when you get home you two-faced jerk. This command is handled by Twitter, not TTYtter.

You can also use the /reply command to reply to a DM menu code, which we will talk about now.

Replying to tweets and direct messages, threading ("in reply to"), favourites and DM/tweet selection (or, "what are those funny little codes for?")

After a bit of time using TTYtter, you will have noticed the a letter-number code on the left of every tweet. This is the tweet's menu code. The letter ranges from a-z, the number from 0-9, with tweets u0-z9 reserved for temporary menus the foreground process constructs (with z0-z9 always reserved for thread requests) and a0-t9 reserved for the background process.

That sounded a little dizzying, so I think an example will be the best way to show how to use this effectively. As your timeline moves along, say there is a tweet you want to reply to. You could simply use @username, but this does not thread your reply (there is no 'reply to'). Instead, the /reply command can take a menu code and you can then tell TTYtter the exact tweet you are referencing. For example,

h2> <ev> I am so awesome. You all want me. #eviswanted
h3> <ttytter> Version 16.0.9 will enable world domination.
TTYtter> /re h3 I would like very much to dominate the planet.
(expanded to "@ttytter I would like very much to dominate the planet.")
TTYtter> h4> <@doctorlinguist> @ttytter I would like very much to dominate the planet.

Notice that your reply appeared with its own menu code (so you can reference your own tweets), that the reply had the correctly referenced screen name added for you (you don't need to retype that), and that your tweet appeared with a @ before your screen name. The @ means that your tweet is now part of a thread (i.e., it has "reply to" information attached to it). If you asked TTYtter for the thread it belongs to using the /thread command, you would get

TTYtter> /th h4
z0> <ttytter> Version 16.0.9 will enable world domination.
z1> <@doctorlinguist> @ttytter I would like very much to dominate the planet.

(up to 10 tweets in a thread can be retrieved, if it's that long), ending with the tweet you asked to have threaded.

Notice that the menu codes are different. Any collection of tweets requested by your command has a special temporary menu constructed just for those tweets. For example, if you asked for your mentions-replies, you might see

h5> <@ttytter> @doctorlinguist I like your world domination code.
TTYtter> /re
u0> <@ttytter> @doctorlinguist I like your world domination code.
u1> <cbqueue> Waiting for @doctorlinguist to hack into my wireless.
u2> <@floodgap> @doctorlinguist We have fired you for being too awesome. Please see HR.

Then you can see the threads that any of those belong to:

TTYtter> /th u0
z0> <ttytter> Version 16.0.9 will enable world domination.
z1> <@doctorlinguist> @ttytter I would like very much to dominate the planet.
z2> <@ttytter> @doctorlinguist I like your world domination code.
TTYtter> /th u2
z0> <doctorlinguist> I have converted lead, puppy poop and rubber bands into gold. I am awesome.
z1> <@floodgap> @doctorlinguist We have fired you for being too awesome. Please see HR.

Temporary menu codes last until you execute a new command that clears the menu. Replies (with /replies), asking for a user's tweets (/again username) and searches all create their own temporary menus which last until you ask for another one of those commands, and they are always u0-y9. Threads occupy their own special temporary menu from z0-z9 so that you don't have to keep grabbing, say, your replies when you want to look at a whole bunch of threads. In fact, that is exactly what we did above.

If you try to access a tweet that has gone out of scope, you simply get an error message. For example, we made a new temporary thread menu when we asked for the second thread. To prove this,

TTYtter> /re z2 I will E-mail my world domination code update to you.
-- no such tweet (yet?): z2

Because you are always receiving new tweets, however, the background menu codes are always valid and continuously "roll forward." When the background process runs out of menu codes, it simply wraps around, viz., after tweet t9 comes a0 again. This means that the background has a "memory" of 200 tweets, after which the tweet is removed from the backlog. Don't worry: if you should miss the chance to reference a tweet, you can still get a temporary menu code by calling up that user's tweets (or your replies) and referencing that tweet that way. Remember that the temporary menu codes are good until you issue a command that makes a new temporary menu.

If you don't know if a tweet still exists, don't fret. Whatever is the most recently displayed background tweet with that code is always the tweet it will reference.

Deletion (/delete), retweets (/retweet, /eretweet and /fretweet), marking and unmarking favourites in 0.9.7+ (/fave, /unfave and /fretweet), and opening URLs (/url) also all take menu codes. The /url command opens all URLs in a tweet according to the current -urlopen setting; for example, try /set urlopen lynx -dump %U | more and then run /url on a tweet with URLs in it. Mac OS X users, try /set urlopen open %U

Note that as of 0.9.7+ /url will permit UTF-8 characters in URLs thanks to the proliferation of faddish shortners like tinyarro.ws, but some browsers don't understand them on the command line (in fact, Mac OS X's open will see these characters and think its argument is a filename, so caveat scriptor).

If you want to make a visible reply everyone can see regardless of whether they follow the user you replied to, or regardless of their settings, you can use /vreply. This generates a tweet like r @username your reply, and threads it. Use sparingly to avoid annoying people. It is available in 0.9.7+.

/delete deletes your own tweets, after you confirm which tweet you have flagged for destruction. You cannot use it to erase another user's. Deletion is not guaranteed: even if TTYtter reports it received successful confirmation, it may be queued for later by Twitter internally, or it may not happen at all if Twitter is having database problems. If you're really prone to fatfingering your tweets, you might want to use the -verify or -slowpost options so you have a chance to catch mistaken tweets before they are sent.

/retweet simply retweets the selected tweet, with RT @userwhosaidit: followed by the tweet. If you want to add your own commentary, you can use /eretweet, which loads the tweet into the substitution variable %RT% which can then be used at the beginning or end of a subsequent tweet. Here is an example of both in action:

s5> <doctorlinguist> I am awesome
TTYtter> /rt s5
(expanded to "RT @doctorlinguist: I am awesome")
TTYtter> s6> <@ttytter> RT @doctorlinguist: I am awesome
/ert s5
-- ok, %RT% is now "RT @doctorlinguist: I am awesome"
TTYtter> yes, you are %RT%
(expanded to "yes, you are RT @doctorlinguist: I am awesome")
TTYtter> s7> <@ttytter> yes, you are RT @doctorlinguist: I am awesome

If even this is not expressive enough for you, you can also edit %% with the usual substitution sequences (see Command history and substitution below), which as of 0.9.7+ is also populated by /eretweet. If you really enjoyed the post, then /fretweet will retweet and favourite the tweet for you all at the same time in 0.9.7+.

Direct messages also have their own menu codes in 0.9.6+. These are three-character codes to distinguish them from tweet menu codes, and every DM menu code starts with the letter D. They are completely separate from each other (e.g., tweet code a5 is unrelated to DM code da5). For example, when you start up you might see

-- checking for most recent direct messages:
[DM da0][cbqueue/Fri Sep 28 02:01:33 +0000 2007] test test
[DM da1][ttytter/Fri Sep 28 03:01:51 +0000 2007] don't forget to update the website

These codes can also be used to /reply (sending them a direct message reply), to /delete (deleting it from your direct message inbox), or for /url to extract URLs from, just like a tweet menu code would be. Instead of using the two-character tweet menu code, however, use the three-character DM menu code and "the right thing" (tm) will be done automagically:

TTYtter> /re da0 test test back atcha
(expanded to "D cbqueue test test back atcha")

Currently Twitter does not support threading for direct messages, so /thread cannot be used for DMs at present (and /reply to a direct message thus cannot thread it; in this version it acts merely as a convenient shortcut). Also, there is no /retweet for DMs. If you want to be like that, cut and paste yourself.

Like regular tweet menu codes, DM menu codes wrap around. There are no temporary menus for DMs, however; if you use /dmagain to redisplay your inbox, the codes simply keep advancing. Whatever is the last DM on screen with a particular DM menu code will always be referenceable by that code. Because there are no temporary menus, the range of DM codes is da0 through dz9, meaning a "memory" of 260 direct messages. You can always get them back with /dmagain.

If your /reply or /(e)retweet of a tweet (or, where allowed, a DM) ends up expanding over length, the usual automatic trimming or autosplitting applies with one important change: if you use %-substitution on the most recent tweet that is or originally was a reply or retweet, then the substituted tweet is also linked (see Command history and substitution). This allows things like autosplit or %-based line editing to work correctly and connect to the same thread. As soon as you type a new tweet or reference a new one, however, TTYtter may automatically purge it if it thinks you are no longer working with the selected tweet.

Following and leaving users (and other Twitter-handled commands)

As you might expect, since Twitter accepts the D command to send direct messages, it will also accept the other specific commands supported for phones and IM (see the official list), including FOLLOW username and LEAVE username. Remember, these commands are handled by Twitter -- TTYtter simply passes them along.

The only commands that presently are not supported are ones that "talk back" to you, such as FOLLOWERS, STATS, etc., because TTYtter currently doesn't do anything with the server response after a tweet except to check that it's there (thus considered "successful").

Tracking keywords and hashtags, and integration with Twitter Search API

Starting in 0.9.4, TTYtter can talk to the Twitter Search API. You can use this to search for keywords and topics as if you were searching Twitter from your browser, or you can even tell TTYtter to watch for #hashtags and keywords you specify, and add them to your stream of tweets automatically with regular refreshes.

Let's start with a typical workflow. What are people looking at? The /trends command tells you what the current topics du jour are:

TTYtter> /trends
/search #sxsw OR SXSW
/tron #sxsw SXSW
/search Twilight
/tron Twilight
/search Ireland
/tron Ireland

This displays a string of topics, formatted into /search and /tron commands you can cut and paste from and into your terminal. If you see a search you want to run, the /search command runs it as if you had typed it into the Twitter Search page, and displays the most current tweets that match. You can use any search term and operator the web page would normally let you. Obviously you are not limited to the trends list; those are just suggestions.

But say you want to actually follow that topic or hashtag. The /tron command adds that topic or hashtag to your list to follow, and automatically executes that search on your behalf, mixed into your regular updates from your timeline and updated whenever your timeline would normally update. If your terminal supports ANSI colour sequences (or you force it on with -ansi), then keywords and hashtags you are tracking are highlighted, and results that came only from a search (i.e., weren't part of your normal timeline) and aren't replies or your own tweets are marked in cyan by default so they stand out. (If you only want to see tracked results, then either use the -notimeline command line option or say /set notimeline 1 and your timeline will be turned off -- only direct messages and tracked results will appear.) For example, you can say /tron #twitter, or use a keyword: /tron ttytter or even a quoted string: /tron "Jack Dorsey". You can follow multiple at once; you don't need to say AND or OR (they are treated as OR).

Following certain topics can literally flood your terminal out with a massive stream of tweets. If you want to completely replace your tracking list with a new list, use /track (such as /track "Cameron Kaiser" #gopher); however, if you want to just withdraw one single term, use /troff (such as /troff #twitter) to remove that search term or hashtag from your tracking list.

If you've totally had enough, you can turn off tracking entirely with /notrack, which cancels all your keywords, or you can reversibly disable tracking with the -notrack commandline option in 0.9.5+ (or /set notrack 1 to turn it off, and /set notrack 0 to turn it back on).

To see what you are tracking now, type /print track. When you quit TTYtter, your tracking list is shown and you can either pass it on the command line next time or put it in your .ttytterrc with the -track option.

Because hashtags are so popular, you can use the /# shortcut to follow a particular hashtag, such as /#twitter. To turn it off, use /troff like usual (/troff #twitter).

Automatic keyword/hashtag tracking does not support using Search API operators or logicals. Occasionally you want an automatic search that is more prolix, and the semi-secret command /set tquery allows you to specify a single complex query that the Search API will support. This overrides your keywords. For technical reasons, tquery requests still highlight your old keywords, if you specified any before. To cancel a custom query and return to regular tracking (if any), say /set tquery 0; your old keywords will be reinstalled.

Command history and substitution

Command-line history and editing is significantly changed, and sometimes even improved, if readline support is enabled. See TTYtter and readline support for what changes when you use -readline.

A simple one-command history (I used to call this the "re-tweet," which was a term I used long before the johnny-come-lately "RTs"! sigh) allows you to recall the last command. Instead of using !!, which can sometimes start (or be) a tweet, the last command is recalled with %%, and can be further modified. If the last tweet was too long, the truncated version is added to the history, allowing you to approve or append to it (and you are reminded of the new length in 0.8.2+). For example,

TTYtter> this is an attempt at a really long tweet which will almost certainly be greater than one hundred and forty characters even without UTF-8 overhead.
*** sorry, tweet too long by 7 characters; truncated to "this is an attempt at a really long tweet which will almost certainly be greater than one hundred and forty characters even without UTF-8" (137 chars)
*** use %% for truncated version, or append to %%.
TTYtter> now is the time
TTYtter> %% for all good men to eat pizza
(expanded to "now is the time for all good men to eat pizza")
TTYtter> q3> <doctorlinguist> now is the time
q4> <doctorlinguist> now is the time for all good men to eat pizza
[DM dn4][cbqueue/Mon Oct 01 07:31:54 +0000 2007] stop doing that

If you have -autosplit on (0.9.3 and up), then the split tweets get placed into %%. See Command-line options for how this works.

Starting with 0.6, a full command history is available, by default the last twenty in a session. Just as %% replaces !! for the immediately preceding command, so does, say, %-3 replace !-3 to retrieve (in our example) the command you entered three lines ago. If you add a :p (e.g., %-3:p) it will print it for you, or you can type /history to see all the commands in the buffer. :p and /history don't get added to the history themselves, but all other commands and tweets are. %% also still works just like before.

In 0.9.7+, you may either append to a substitution, such as %% jumps the shark, or prepend to it, such as American Idol jumps the %%. To avoid ambiguity, intercalation is not supported (e.g., American Idol %% the shark is not subject to substitution). Prior to 0.9.7, you could only append after a history substitution, not prepend before it (although /%% is always allowed to let you escape tweets that look like commands); thus, something like you can get the third command with %-3 is tweeted out without substitution, but %-3 and Phyllis did get substituted.

Starting with 0.8, there is now primitive tweet editing. Since one common thing is to try to take words off the end, you can now do this by adding -x to the end of a history command (or -- for one word only). For example, %%-- takes the last word off the last command and resends that, or for a more complex example, %-2-4 takes the command two lines ago, and takes four words off that. You can then append to this construct, e.g., %-3-2 with Phyllis I mean, or prepend to it in 0.9.7+, e.g., this is cool >> %-3-2. Note that this does not work with :p.

Starting with 0.9, the most recently-shortened URL is available as %URL% (e.g., if you shorten http://www.example.com/, then %URL% is http://is.gd/7bP). Again, to eliminate ambiguity in potentially compressed 140-character missives, it is only interpreted at the beginning or end of a line. Starting with 0.9.7, %URL% is also set by /whois and /wagain from the user's URL (if any), along with the last URL you looked at with /url, and the URL for the tweet dumped by /dump. If you say /short or /url with no arguments, then %URL% is used as the default, so you can open someone's home page with /whois user followed by /url.

Starting with 0.9.5, the /eretweet command loads a selected tweet menu code into %RT%, allowing you to frame a tweet with your own commentary before you send it. Once again, to eliminate ambiguity in potentially compressed 140-character missives, it is only interpreted at the beginning or end of a line. If even this is not flexible enough for you, it also populates %% as of 0.9.7+ so that you can use the other command line substitution sequences to edit it.

Also starting with 0.9.5, if you use %-substitution on the most recent tweet and it was connected to another tweet (such as making a /reply to specify a tweet you are replying to, or a /(e)retweet), then any immediate substitutions made on that tweet are linked to that tweet also. Note that these kinds of tweets, such as /reply, appear in your history in their original unexpanded form, i.e., literally as you typed them (e.g., "/re f9 bletch foo bar"), except if they are auto-split. This is, in fact, how /eretweet works by design. If you reference another tweet or type another tweet, however, this context is automatically purged if TTYtter believes you have stopped working with this one.

Remember to read TTYtter and readline support if you intend to use readline support.

Command-line options

There are many useful options you can pass on the command line. Not all options are supported in prior versions. Here is the complete list of command-line options.

TTYtter and UTF-8 support

TTYtter does support receiving and making tweets using UTF-8 encoding for Unicode code points larger than 8 bits. However, there are a number of gotchas that need to be considered.

For minimal support of UTF-8, including receiving and decoding UTF-8 tweets, your Perl must have support for Unicode (thus 5.005 won't work) and the internal utf8 pragma (which usually means you must have utf8.pm), and your terminal program must be configured to understand a UTF-8 locale or at least not interfere with bytes with the high bit set. For example, even many modern xterms will not properly display UTF-8 unless the LC_CTYPE environment variable is correctly set prior to launching the xterm (this is particularly relevant to Mac OS X), such as en-US.UTF-8. You may also need to set other LC_* environment variables, or the LANG environment variable. Users of terminal programs in other environments should enable UTF-8 encoding in their settings, and if you are using Telnet or rlogin, make sure your connection is 8-bit safe. Your font must also include the needed glyphs for display.

If you do not meet these minimum requirements, or ttytter complains your Perl does not support enough features to enable UTF-8 support, then you must disable UTF-8 with the -seven option. This is the only supported way for 5.005 or for impoverished installations.

To send UTF-8 encoded tweets, there are several more gotchas. First, you will need to make sure that your terminal environment gives you the ability to enter the desired character; TTYtter does not support any specific input methods internally and relies on your terminal. As a corollary, if your terminal program or input method does not properly support wide characters such that a backspace or delete does not delete both byte halves of a wide "2 byte" character, backspacing over a wide character only once will leave an incomplete UTF-8 sequence even if it looks like the glyph was deleted. This is entirely under the control of your terminal environment; TTYtter only reads from standard input. If you don't know, press CTRL-R to redisplay the current line. Don't worry, however: if you enter a tweet with demonstrably invalid UTF-8 encoding, ttytter will refuse to post it.

The current version of the Twitter API only reliably allows you to make tweets of 140 bytes, not 140 characters. Although some other clients may let you do this, Twitter still (as of this writing) does not reliably accept them in my testing, and the backing stores are not fully UTF-8 safe. To prevent an unexpected situation, right now TTYtter rigidly enforces 140 byte tweets. You might consider using -autosplit=char to make this easier on yourself by automatically splitting your tweets up into correctly-sized fragments; see Command-line options. When Twitter fixes this (see this developer thread), I will back the guard code out of a future version of TTYtter.

Certain -readline drivers may not allow you to enter UTF-8 (although virtually all I have tested will let you receive it). If you get Malformed UTF-8 errors while you try to type or edit a line, your readline driver is not UTF-8 safe. For more on readline, see TTYtter and readline support.

UTF-8 support is not possible for every combination of font, terminal, locale and Perl version, and while I'm trying to make sure it works in most places, I can't make it work every place. If you'd rather just junk UTF-8 or 8-bit characters in general altogether, use -seven. In this mode, all 8-bit characters are rendered as printable dots and UTF-8 entry is not allowed. This is the lowest common denominator for compatibility.

TTYtter and SSL

For modern versions of either Lynx or cURL, OpenSSL is mandatory for the following section.

TTYtter supports encryption as long as your Lynx or cURL does, since obviously the network lifting is done by Lynx or cURL, not TTYtter. For this reason, since not everyone has a crypto-enabled client, SSL is not enabled by default. Note that this means passwords are encoded only using HTTP Basic Authentication and updates are sent and received in the clear, which may be a problem if you require high security for your application or are on an insecure link such as open wireless.

If your client does support SSL, then you can easily change TTYtter to use it (do note that this may scale less well due to the additional overhead) by simply using the -ssl option. This assumes you are using 0.9.0+ and that you are using the regular Twitter API URLs. All of the applicable URLs will be changed for you. (This does not apply to -shorturl for the URL shortening service, which is not a Twitter service, and it does not apply to the Search API URLs which do not offer SSL access. You should make sure your URL shortening service allows SSL access first, and if so, specify -shorturl=... yourself. See Command-line options.)

If you are using 0.8.x or earlier, or are not using the Twitter default URLs, you can use the various URL command-line options to manually specify https:// URLs, or you can cut and paste this into your .ttytterrc file (see Command-line options for other things you can put in this file):


By default, cURL's certificate bundle is old and may not support Twitter's current CA. cURL offers an updater script in Perl which will rebuild a new certificate bundle suitable for installation, which requires LWP, along with the standard Getopt and MIME modules. (A more current version may have already come with your cURL install.) If you need a version of this updater script for systems without LWP (like Mac OS X) and don't want to install LWP to run it, I offer a modified version using cURL itself.

For Lynx users, if you get certificate errors, read how to manage certificates in Lynx. The MirOS root certificates package is known to work with Lynx 2.8.6 (yours truly uses it); simply expand the sh-archive into your OpenSSL certificates folder, by default /usr/local/ssl/certs, and Lynx should automatically start using them.

TTYtter and notification support (Growl, libnotify, ...) (0.9.7+)

Starting with 0.9.7, TTYtter can pass selected tweets and direct messages on to a notification system. Thus, not only will they appear on your regular terminal window, but you can also be alerted to them in another customizable way. For example, with Growl support (built in to TTYtter), you can then configure Growl to send selected tweets and DMs to your iPhone via Prowl. Or, when I'm working out and not sitting at the computer, I have Growl configured to display very large alerts on the screen, driven by TTYtter, so I can see tweets I might need to respond to from across the room without having to watch the window all the time.

To enable notifications, specify the notifications driver you want to use with the -notifytype=... option, and the class(es) of messages you want to send through the driver using the -notifies=... option. For example, this command line enables Growl support and passes notifications for (and only for) direct messages and replies that you receive:

% ./ttytter -notifytype=growl -notifies=dm,reply

TTYtter supports Growl and libnotify drivers (more about that below) and dm, me, reply, search and default message classes, corresponding to, respectively in order of precedence, direct messages, tweets you wrote, replies and mentions, tweets that appear in search, and other unclassified tweets from your timeline. The highest level class is selected, so a tweet selected from search that mentions you is promoted to a reply; if you retweet yourself (you shameless publicity whore), it is promoted to a self-written tweet. If you want to be notified about everything that you get in your timeline, you might say

% ./ttytter -notifytype=growl -notifies=dm,me,reply,search,default

Each notification is tagged as a TTYtter alert, along with the class of the notification, and the contents of the DM or tweet.

Growl support is built-in and well-tested, and uses the growl driver (i.e., -notifytype=growl). Growl is available for Mac OS X (although there are endpoints supported on other systems such as iPhone OS via Prowl). You must also install growlnotify, which comes separately with the standard distribution of Growl in the installation disk image. Run the growlnotify install script; it places growlnotify in /usr/local/bin by default. When you start TTYtter for the first time with Growl, it registers itself as an application so that you can make application-specific settings such as alert type, sticky alerts and timeouts specific to TTYtter within the Growl preference pane. Changes to settings are stored by Growl, become active immediately, and are remembered for future TTYtter sessions.

libnotify support is also built-in but experimental as of 0.9.7, and uses the libnotify driver (i.e., -notifytype=libnotify). Although it uses the standard notify-send utility, currently it requires that notify-send be recompiled with standard input support as shown in Galago Project trac ticket #147 in order to protect the command line from malicious data. Replace notify-send with the new binary and start TTYtter. If notifications appear successfully, your configuration is correct. On purpose no special settings or categories are currently used. Please report any bugs you find to ckaiser@floodgap.com, as this support is currently not well tested.

I would invite any other suggestions for notification frameworks, although I am intentionally restricting built-in notification support to the most common applications and systems. You can, however, build a handler for your own preferred notification system using the API.

TTYtter and Laconi.ca/Identi.ca (and other Twitter-alike APIs) (0.9.5+)

TTYtter will speak with other Twitter-alike APIs, although less functionally depending on how much of the Twitter API is implemented.

The special command line option -apibase rewrites the default Twitter URLs (and only the Twitter URLs, not, say, Search API URLs or URL-shortening-service API URLs) to point to a different server. For example, Identica offers a Twitter-alike API with URLs starting with http://identi.ca/api, so

ttytter -apibase=http://identi.ca/api

, plus your usual login options and such, will suddenly enable you to authenticate and twitter on that server.

Or at least in theory, because when you do that ... ttytter immediately crashes with a not-implemented error and an ugly dump of HTML (as of this writing). Because not all Twitter-alike APIs support all the services that TTYtter expects, you might need to clue TTYtter into what it shouldn't be trying to fetch. For example, since the Laconi.ca/Identi.ca servers do not (currently) support rate limiting or direct messages, you should specify a fixed interval, tell TTYtter to not even try to get the rate limit even for your information, and don't bother with direct messages either. (For that matter, since there is also no search facility, might as well not waste Twitter's CPU cycles with search, so we'll also disable that.) So, if we change our example above to

ttytter -apibase=http://identi.ca/api -noratelimit -notrack -pause=90 -dmpause=0

and run that, then we're rolling. You can also make this automatic by putting


into your .ttytterrc file. To find out what all these command line options do, see Command-line options. Depending on the service you use, you may need to only include some of these options, but this is the minimum lowest common denominator of functionality supported in TTYtter.

TTYtter and your special terminal environment

It is possible, and quite often entirely functional, to run ttytter within a custom terminal environment. For example, your humble author runs ttytter routinely in GNU screen. This works as-is and requires no special options.

For environments that try to provide a custom editing environment, such as running ttytter under ssfe (a simple full screen environment that is part of the sirc package) or similar, often TTYtter needs to signal the environment that it is running, and TTYtter's normal prompt handling usually must be suppressed. In 0.9.0+, this is accomplished with two options: -noprompt, which as its name implies means no prompt is displayed and TTYtter simply waits on standard input; and -leader=..., which prints a lead line even before TTYtter has started up in order to flag the environment. Depending on your real terminal or terminal program, you may also need -ansi or -noansi to handle escape sequences correctly. Details on all these options are on the Command-line options page.

For example, this command line will start TTYtter under ssfe:

% ssfe ttytter -leader='`#ssfe#sTTYtter' -noprompt

(Naturally include your login and any other relevant options; also, my particular environment does in fact require -noansi, but I have omitted those options for clarity. This patch may be useful for passing ANSI sequences through.)

It is possible to use versions 0.8.x and earlier under such conditions but this usually requires writing a library or modifying ttytter directly, and thus is not supported. Some patches to do so against 0.8 for ssfe are here.

If you are trying to get TTYtter to run under rlwrap or other kinds of readline-specific wrappers, this usually will work, but a better idea is to use TTYtter's own built-in readline support instead.

It is not possible for me to support every possible environment in TTYtter, and some just won't work. Also, I do not like to add special trivial cases to the code if I can help it. However, if there is a general way I can extend support to your favourite runtime environment, or if you have written a library/plugin to accomplish this, please let me know at ckaiser@floodgap.com. Please, no attachments unless I request them. Thank you :)

TTYtter and readline support (0.9.0+)

Starting in 0.9.0, TTYtter now supports readline for interactive command line history, TAB completion and editing. You must have Perl 5.6 or higher for readline support to properly function (it will work in 5.0050x, but the display may be messed up), along with the Term::ReadLine stub module (part of the standard Perl distribution), and a functional Term::ReadLine::* driver. Most systems will do well with Term::ReadLine::Perl, which is a pure Perl readline emulator (although it is slower than native code, it is very compatible and runs on nearly anything), but TTYtter should support any module that follows the API laid out in Term/ReadLine.pm.

Please note that readline support is considered experimental and bugs should be expected. You should make sure that your Perl's Term::ReadLine::* is up-to-date with CPAN, as this greatly improves several apparent bugs.

To start TTYtter in readline mode, pass the -readline=... option, along with a (n optional) string of words to preload the TAB completer with. This string is space delimited, so you may need to quote it, or you can just type -readline by itself with no string and use the defaults. With readline enabled, assuming your driver supports it, your cursor keys will become enabled allowing you to go back and forth through your history, and you will be able to use them to edit the current command plus any additional editing keys enabled by your driver's features and/or keybindings.

Tweets will still print on screen and may overwrite what you're typing. How you redisplay your current line varies on the keybindings of your driver, but a routine that works for most is to press SPACE, and then BACKSPACE. (This might not work for certain input methods, however, particularly ones like Kotoeri where nothing is transmitted until a completed word is sent. There is nothing TTYtter or Term::ReadLine can do about that.)

TAB is also active in readline mode for standard TAB completion. The TAB completer starts out with the standard TTYtter command set (completed only at the beginning of a line, natch), plus any additional keywords you give it with the -readline=... option. These can be regular words, or they can be Twitter users (if so, they should be prefaced with @, e.g., -readline="@doctorlinguist @ttytter"). Like any sane TAB completion routine, if you press TAB and multiple options match, you will be given a list.

During the course of your session, people you @-reply to, people you DM and people you query with /again, /whois and etc. will be added to the completer's vocabulary. The completer is smart -- it will add the name in context whether the @ is needed (replies) or where it isn't (commands), but commands will accept @user arguments as well so that improved orthogonality is achieved. (Your list is not populated out of tweets you receive: this would scale very badly, and edge cases would find themselves running out of memory!) When you quit TTYtter, the words you preloaded plus the added usernames (ranked with highest usage to the top) will be displayed in command line form, up to 15. You can pass this directly to ttytter or cut it up to put in your .ttytterrc. Note that of course you can have active, and specify on the command line, more than 15 terms; I just picked that number to make it easier for people to parse and cut and paste. If you want to know what the optimized readline string is now, type /print tabcomp; if you just want to see what got added to your TAB completer (and all of it), use /print ntabcomp.

TAB completion can also shorten URLs for you. Type any http:// URL and at the end before you hit SPACE, press TAB. After a brief pause the URL will be replaced with a shortened one as if you had used the /short command. This does not always work for characters that the driver eats before handing the string to the TAB completer -- it is best used for URLs that do not query forms or use excessively complex parameters. If you're having trouble with the TAB URL shortener, use /short.

There is little need to use %-based command line history in readline as it's much easier to just cursor back and re-use or edit the line yourself interactively with the cursor keys. Nevertheless, %-sequences are still active and can still be used (and for things like oversize tweets, autosplit, etc., still have to be). Because of the way the history is generated, %-substitutions appear in your cursor up/down history in their unsubstituted original form. Also, the -maxhist option (q.v.) only affects TTYtter's internal history, not readline's. If you intend to mix and match TTYtter's internal history and readline's (not recommended!), check the /history command to make sure that you and TTYtter agree on what particular portion of the history is being operated upon.

Remember that readline does not necessarily work like standard input. For example, characters you type between prompts may not be seen.

If you intend to work in an UTF-8 locale, some readline drivers may not handle UTF-8 character entry correctly (the current version of Term::ReadLine::Perl is the most notorious). If you receive Malformed UTF-8 errors while attempting to edit a string with UTF-8 encoded characters, your driver is not UTF-8 safe. Note that you may still be able to receive and see UTF-8 encoded tweets, so if you don't need to send them, you can still use that driver. However, neither TTYtter nor Perl nor Term/ReadLine.pm can magically make a driver accept input methods it does not understand. For more about UTF-8 support in TTYtter, see TTYtter and UTF-8.

Scripting TTYtter

TTYtter can be easily scripted by passing it console commands on standard input (and tweets, although if you are doing a single tweet -status=... works much better and can be made 'bulletproof' with -hold to boot). For many custom applications where you just need, say, a cron job to fetch your last 20 DMs, this can be all you need.

In 0.8, scripting was greatly expanded to allow even asynchronous commands to be fully scriptable, and extensions made to allow for an optimal script environment. Most of the time, you will want to use -script to ensure that you have full control over the environment and that prompts are suppressed, and then feed your list of commands into ttytter. For example, if you pipe this to ttytter -script,


TTYtter will fetch your 20 most recent tweets on the timeline (since /r will start from the beginning, having no history), your 20 most recent direct messages, and then wait for those requests to end before quitting (if you omitted the last line, an end-of-file is treated as /quit and any outstanding queued requests will be immediately cancelled). Everything is emitted to standard output.

You don't even need to use a file at all, of course, and naturally you can pipe it to something else such as in this marginally useless example:

echo "/again twitterapi" | ttytter -script -anonymous | grep -i banana

Any command that the console understands can be passed, even history substitutions and actual tweets.

Starting in 0.9.3, you can also specify an arbitrary Perl expression on the command line for simple filtering of tweet content; see the -filter option under Command-line options. For example, here is the banana example again, using TTYtter to do the filtering:

echo "/again twitterapi" | ttytter -script -anonymous -filter="\!/banana/i"

Or, if you're using 0.9.4 and up, you can even search Twitter for hashtags and keywords. For example, you can find a lot of Japanese poets this way:

echo "/search #haiku" | ttytter -script -anonymous

Such things suffice for simple tasks, but you cannot change the format of tweets this way (except with things like -timestamp), and there is no reliable error detection or conditional logic. For much more custom behaviour, you need to write an extension in Perl, which brings us to ...

Extending TTYtter with custom behaviour and filtering (-lib)

If scripting isn't enough, you can completely override the engine's guts for your specific purpose. Using the -lib=... option, you can specify a custom library to augment TTYtter's core behaviour, including but not limited to how received tweets and DMs are dealt with, how errors are reported or even how the console itself is handled. You can either use this in interactive mode, or, if you use -daemon, even make a Twitter bot.

For more information on this very useful function, see Advanced usage.

Using TTYtter as a bot or daemon (-daemon)

If you launch ttytter as a detached process using the -daemon option, it will immediately return but after installing a background process that monitors tweets and direct messages just like the asynchronous monitor does in interactive mode. The PID of the new background process is printed for your reference.

If you just pass -daemon and don't specify any custom behaviour with -lib=..., then tweets and DMs are printed asynchronously in the background and you can watch them while you use the terminal session for something else (it will just print over what you're doing). However, you must do something like ttytter -status=... to post tweets, as there is no console process, and you must kill the daemon process manually to turn it off.

Combine -daemon with the -lib=... option and, as mentioned above, you can use ttytter as a Twitter bot. Again, for more information on this very useful function, see Advanced usage.

Now that you've read all that ...

... read the list of command line options, or,

... go download 0.9.11 and look at the change log and known bug list.

Send comments and blank cheques to ckaiser@floodgap.com.

Cameron Kaiser