TTYtter for Perl (Legacy 0.8.6)

*** Subscribe to updates over Twitter! -- twitter.com/ttytter

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.

• In interactive mode, it is a fully interactive client with asynchronous background updates and commands. Use it over telnet, ssh or even a dummy terminal.
• From the command line, use it to update your Twitter in shell scripts, from cron, and so on.
• Supports standard timelines and automatically fetches direct messages.
• Extensible using the -lib option.
• Run detached in -daemon mode, and make your own Twitter bot!

Note to identi.ca users: According to this wiki entry, laconi.ca and identi.ca users can use Twitter-compatible API clients to access those services. I don't use either one of these, so I can't say -- your experiences would be appreciated. Note that some services may not support direct messaging, so you may need to turn that off (-dmpause=0 will accomplish this; see the options below).

Using TTYtter as an interactive client

(NB: If you have a password like pa$$word that has shell metacharacters in it, try a command string like ./ttytter '-user=screwtape:pa\$\$word' [note single quotes around the entire option and backslashes before the metacharacters].) Yes, you can put the password in an external file; more about that when we get to .ttytterrc.

ttytter will try to detect which client you have (it prefers cURL but you can force Lynx with -lynx), and then starts up if it can run a test query successfully. It then starts a background process that every 120 seconds (customizable) will 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
test-login SUCCEEDED!

######################################################        +oo=========oo+ 
         TTYtter 0.8.6 (c)2008 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
                                                                   #+$$AB=.
         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.                           @=@ @=@

You can tunnel your traffic under SSL if your Lynx or cURL supports it, but make sure you read the rest of this page before reading about TTYtter and SSL.

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 fatal error will occur if foo doesn't exist. We'll talk about scripting TTYtter in a moment, but first let's talk about ...

Basic tweeting

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 your tweet is over 140 characters, 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 re-tweet command history (q.v.).

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.

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

Built-in commands

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.

/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, even old ones.

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

If you specify a filter with -avatar (below), 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. 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)

/again:/refresh::/dmagain:/dmrefresh

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

/history (/h)

Displays the last set of commands entered (see Command history below).

/me

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

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

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.

See the -dmpause option below.

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

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

Command history ("re-tweeting")

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.

You can only append after the re-tweet, not prepend before it (although /%% is allowed to let you escape tweets that look like commands). This is on purpose due to the risk of ambiguity. Thus, something like you can get the third command with %-3 is tweeted out without substitution, but %-3 and Phyllis does 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. Note that this does not work with :p.

Command-line options

-user=[name]:[passwd] (required, except if you specify -anonymous [see below])

Specifies username and password. If you have a password like pa$$word that has shell metacharacters in it, try a command string like ./ttytter '-user=screwtape:pa\$\$word' (note single quotes around entire option, and backslashes before the metacharacters). If you want to explicitly override this and access Twitter without authentication, look at -anonymous.

-seven (optional and deprecated)

Specifies that UTF-8 support should not be enabled. As of the current implementation of the Twitter API, this does not affect receiving already decoded UTF-8 characters (assuming your terminal can display them), but it disables encoding UTF-8 characters so that you cannot tweet in UTF-8, and \u or HTML-encoded entities outside of normal ASCII will be rendered as dots. If Perl complains it has no UTF-8 support and/or can't find utf8.pm, pass this option, especially for older Perls. This option is mostly for impoverished Perls, as well as those systems still using 5.005; you should not use it if you can avoid it.

-lynx and -curl (optional)

Forces ttytter to use Lynx or cURL respectively. If the one you want isn't installed, an error occurs. If you don't specify, ttytter will try cURL, and then Lynx if it's not found.

Starting in 0.8.2, you can specify an absolute filename to the cURL or Lynx binary you want to use (e.g., -lynx=/weird/bin/lynx). This is useful for running in improverished circumstances where you might not have (or might not trust?) your environment variables, or if the program is not usually in your PATH.

-ansi and -noansi (optional)

Forces ttytter to enable or disable ANSI colour sequences, respectively. If you don't specify, ttytter turns on ANSI colour if your terminal type given in the $TERM environment variable is either ansi or xterm-color (xterm is intentionally not included because of variable support between implementations), and uses no special terminal sequences otherwise. -noansi overrides -ansi, so if you pass both together, then -ansi is ignored. This is also true for -script, which implies -noansi (see -script).

-pause=[pause] (optional)

Specifies the timeout in seconds for the background process. If you don't specify, the timeout is 120 seconds between refreshes, which is designed not to hit the remote server too hard. Remember that setting this too low and thus grabbing tweets from twitter.com too often may cause you to be temporarily prevented from getting them later if you exceed the rate limit (see the FAQ below), so leave this as is unless you have a good reason. You can always bounce this manually with /refresh.

Starting in 0.8, if you specify -pause=0, then all updates (including DMs) are disabled and must be requested manually. This is forced if you specify -script (see -script).

-dmpause=[interval] (optional)

Specifies the ratio of updates for direct messages. The default is four, so every fourth check for tweets, a direct messages check is done too. If you decrease this to 1:1, keep in mind you may hit the rate limit depending on what your timeout is.

If you set this to zero, automatic DM checking is disabled. However, you can still do manual refreshes with /dmrefresh and /dmagain; note that all messages are considered "new" the first time you query in this mode, so you'll get a full twenty with the initial request.

DM checking is also disabled if you are anonymous (see -anonymous), or if -pause is also zero (such as with -script; see -script).

-status=[status text] (optional)

Allows you to use ttytter as a command line tool, like from a cron job or shell script, and automatically post the provided text and exit. You should probably quote the text (e.g., -status="Yo mama is so fat") or your shell may eat portions of it. You cannot use this option if you are anonymous (see -anonymous). See Scripting TTYtter below. This is usually more efficient than posting with -script (below).

You can also use this with -daemon (below) so that you can post from the command line while still using your shell, and having the background process asynchronously monitoring tweets like usual.

-script (optional)

Forces a specialized mode designed for running commands from a script file or passed via standard input. -script implies (forces) -noansi, -pause=0 and -silent. This is optimized for automatic or unattended command sequences performing simple tasks. See Scripting TTYtter below.

Note that for posting single tweets, -status is generally more efficient than -script.

-timestamp=[template] (optional)

Forces timestamps to appear on all tweets, all the time, instead of just on direct messages. If you just say -timestamp with no argument, then the server-provided GMT timestamp is used without further customization or localization. On the other hand, if you have Date::Parse and Date::Format (both part of TimeDate), then you can specify a template to which it will be formatted and displayed instead as an argument (an argument of default will invoke the default of "%Y-%m-%d %k:%M:%S"). If these modules do not exist, then trying to use a timestamp template will cause a fatal error.

-silent (optional)

Redirects stdout to the bitbucket, rendering ttytter mute. This is really stupid to do in interactive mode but may be very useful for scripts, or -daemon or -status. Exit status is still returned in the usual convention so shell scripts with && and || work as expected, and tweets and DMs will still appear in 0.8+ (but nothing else).

-hold (optional)

If Twitter is being recalcitrant and you know that your login information and URL are correct, you can make ttytter automatically retry the initial test connection every three minutes until it gets through. Since this is not what a first-time user will want to do, this option is not the default. However, once you're set up, consider adding it if the kittens-of-death are using the Obvious server room for a scratching post.

-hold also works for -status, in which case it keeps trying until the tweet is transmitted.

-anonymous (optional, except if you do not specify -user)

Indicates that you will not be using an authenticated username to read tweets. (You must either explicitly indicate this option, or otherwise use -user; there is no "implied anonymity.") When anonymous mode is enabled, there are several significant changes:

• You have no user or friends timeline, so the timeline defaults to the public timeline if you don't specify.
• You can't tweet or, by extension, send direct messages.
• You can't read direct messages.
• You can't be replied to, so therefore you don't have any replies, even if you could read them, but TTYtter won't let you anyway.

This is mostly useful for bots, or the voyeuristic sort that wants to watch what's going on and snoop on users without getting hits on their rate limit. Also, because you don't need to get any credentials checked, access is much quicker in anonymous mode, which again is also good for bots.

If you specify both -user and -anonymous, -anonymous takes precedence and user credentials are not transmitted.

-url=[url] (optional)

Specifies the source for tweets. Tweets are only accepted in JSON format, not XML or RSS. If you don't specify, tweets are downloaded from your friends list at twitter.com (or, if you are anonymous, from the public timeline at same). For example, you can specify you always want the public timeline with this, even if you're authenticated; see the Twitter API for the relevant URLs.

If you want to use this to specify an SSL URL (https://), read the section on TTYtter and SSL.

-dmurl=[url] (optional)

Specifies the source for direct messages, again in JSON format. If you don't specify, direct messages are downloaded from your inbox at twitter.com. This is ignored if you are anonymous. If you want to use this to specify an SSL URL (https://), read the section on TTYtter and SSL.

-rurl=[url] (optional)

Specifies the source for replies, once again in JSON format. If you don't specify, replies are downloaded from your source at twitter.com. This is ignored if you are anonymous. If you want to use this to specify an SSL URL (https://), read the section on TTYtter and SSL.

-uurl=[url] (optional)

Specifies the user timeline URL. This is a little odd in that this URL is actually specified incompletely as a template upon which ttytter builds the actual URL it accesses. If you don't specify, user timelines are downloaded using the URL http://twitter.com/statuses/user_timeline as a base, which is expanded to http://twitter.com/statuses/user_timeline/username.json. Again, all data should be in JSON format. This applies to authenticated and anonymous users. If you want to use this to specify an SSL URL (https://), read the section on TTYtter and SSL.

-wurl=[url] (optional)

Specifies the user query URL. Like -uurl, this is a partial URL that ttytter uses as a template. If you don't specify, user information is downloaded using the URL http://twitter.com/users/show as a base, which is expanded to http://twitter.com/users/show/username.json. Again, all data should be in JSON format. This applies to authenticated and anonymous users. If you want to use this to specify an SSL URL (https://), read the section on TTYtter and SSL.

-frurl=[url] (optional)

Specifies the relationship query URL, which is given user_a and user_b arguments and is expected to return a JSON true or false result. If you don't specify, Twitter is queried directly for relationship statuses. This is ignored if you are anonymous. This was disabled in 0.8.4 due to problems in the Twitter API and is currently a no-op in 0.8.5. If you want to use this to specify an SSL URL (https://), read the section on TTYtter and SSL.

-update=[url] (optional)

Specifies the update URL. Although nothing is much done with the returned confirmation except to check that it's there, the URL should still return something useful in JSON format. This option allows you to use a third-party posting service if you like, assuming it supports the Twitter API. If you don't specify, tweets are sent to the standard one at twitter.com. This is ignored if you are anonymous. If you want to use this to specify an SSL URL (https://), read the section on TTYtter and SSL.

-avatar (optional)

Specifies a command to be passed to your shell for processing the picture URL from /whois. The string %U in your command is replaced with the URL, which is single-quoted automatically for you to avoid metacharacter madness. The return code is not checked and your command can do anything that it wants; I use this for displaying avatar images in ASCII art with commands like this:

• lynx -source %U | djpeg -pnm | ppmascii -photo -x2 -winx=4
• curl -s %U | convert - -colorspace Gray -colors 16 -antialias ppm:- | ppmascii -x2 -photo -winx=4

Note that in both these cases you will need the requisite image converter installed (namely djpeg and ImageMagick respectively), but you can use whatever image converter you want.

Here is an example of the output (the image is inverted because this was originally from a light-on-dark terminal).

-verbose (optional)

Prints additional status information. Sometimes spammy. There is another version of this option with really really spammy output, but those who need to use it should be able to figure it out themselves.

-maxhist=[entries] (optional)

Number of entries to add to the history buffer. Since the history buffer is always at least one command long, the total number of history entries will be (maxhist + 1). The default is 19, making a twenty-line buffer.

-daemon (optional)

Launches ttytter's background process detached so that you return to the shell immediately, but tweets are still being monitored. In this mode you can use TTYtter in the background while you still use your shell and tweet manually from it with -status=.... This is also how you could set up a stand-alone Twitter bot. See below.

-lib=[filename] (optional)

Used for installing extensions. See below.

-twarg=[argument] (optional)

Specifies a user defined argument string, where you can pass any data you like. TTYtter doesn't make any use of this by definition, but your extension library can by looking at $twarg. See below. If you plan to pass spaces or shell metacharacters, they should be escaped or quoted as with any other argument.

user=screwtape:wormwood
hold=1
lynx=1
url=http://twitter.com/statuses/public_timeline.json

Blank lines and lines starting with # are ignored. If your password has shell metacharacters in it, they must be backslashed (e.g. pa\$\$word).

If you specify command line options, they override anything in .ttytterrc. To negate a Boolean option, specify it with a value of zero, e.g., to disable the -hold option using the example .ttytterrc above, pass -hold=0.

TTYtter and SSL

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). This requires changing the relevant URLs using the options above, or you can cut and paste this into your .ttytterrc file:

url=https://twitter.com/statuses/friends_timeline.json
rurl=https://twitter.com/statuses/replies.json
uurl=https://twitter.com/statuses/user_timeline
wurl=https://twitter.com/users/show
update=https://twitter.com/statuses/update.json
dmurl=https://twitter.com/direct_messages.json
frurl=https://twitter.com/friendships/exists.json

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.

Scripting TTYtter

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,

/r
/dm
/end

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 -- usually not what you want in a script). Everything is emitted to standard input.

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.

This suffices 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)

For more information on this very useful function, see Advanced usage. This page is intended for 0.9 users.

Using TTYtter as a bot or daemon (-daemon)

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. This page is intended for 0.9 users.

To-do

• UTF-8 is a lot better supported now, but remember that a lot of terminal programs might not like UTF-8, and proper interpretation can be further affected by any bugs in your particular version of Perl, Lynx or curl. If you are using an old Perl or a version without UTF-8 support, remember to pass the -seven option or it might bug out. There are probably still some problems with Unicode, so please report any weirdness.
• Support for custom terminal drivers, such as readline and the like. This is in 0.9 now!
• Changing certain settings dynamically (/set). This is in 0.9 now!
• En-masse swapping http for https instead of doing it in .ttytterrc. This is in 0.9 now!
• Rate-limit automonitoring. This is in 0.9 now!
• Adding the username to -avatar for making holding areas. This is in 0.9 now!
• Configuring colours (for message classes, maybe even for specific users).
• Pagination.
• Summize Twitter Search API features for keyword tracking.

Other notes

• ttytter knows nothing of proxies and depends on curl or Lynx to do that. You can set your own options in each program's respective configuration file. ttytter will override certain headers and timeouts, but will not override proxy or security settings, so make sure they are correct.
• When Twitter is overloaded, frequently tweets are accepted but the server returns no data within the timeout period (the length of which IMHO is fairly generous, btw). To avoid spamming people, consider waiting a couple minutes if you get a curl error 28 after you try to send a tweet, just to see if it was "silently" accepted. This should get better as Twitter adds more backend power.
• Apart from ANSI colours and attributes, ttytter does not take advantage of any special terminal features or sequences. This is currently a feature of omission so that even the dumbest of dumb terminals can use it, but get used to updates interrupting your typing (just keep typing, it's still there). MUDders will not bat an eye at this.
• Entities like \r \n are intentionally not turned into newlines to avoid scrollspam on small screens.
• Similarly, a lot of the Twitter metadata is thrown away right now, either because it has no relevance in a text oeuvre, or it makes the screen even more cluttered and dense.
• When using Lynx as the user-agent and querying a username with /again or /whois, if you query a protected username that you do not have access to, you may get a "no data" error instead of the expected "no permission" message. This is a quirk of Lynx when handling requests that fail authentication, and can't be worked around easily. curl does not have this problem.
• Where's the JSON interpreter? There isn't one and I'm not using any of the current JSON-oriented modules -- the Perl interpreter itself is doing the heavy lifting for us. Read the &grabjson subroutine to see how this works. There is some token code to prevent malicious servers from being allowed to embed arbitrary Perl in the returned JSON, but just the same, connect to trusted Twitter sources only (using -url or the defaults).

• What are those *** warning: timeout or no data messages? Is TTYtter really that flaky?

  Those messages are informational only, and reflect network conditions. If Twitter is having problems, or your network is down, you will see these. These are non-fatal messages.

  Similarly, messages like *** JSON warning: connection cut or *** JSON warning: null list are problems with the data received from Twitter, not TTYtter, normally that the JSON is incomplete or not properly parseable. TTYtter will automatically refetch until it gets something it can use.

  The reason these messages are printed is so you can see immediately why tweets aren't being fetched or posted.

• TTYtter is killing my rate limit (I get messages saying I'm over the allowed requests per hour).

  By default, assuming normal usage, TTYtter makes a very stingy 38 requests/hour on the average. Posting DMs and tweets do not count against your limit. If you're running over the rate limit, check the following:

  • Is the rate limit reduced? Twitter may reduce the rate to 30/hour or even less under high load. The future 0.9 will check for this automatically, but for now you may want to check the Twitter status tumblr.

  • Are you using your Twitter username and password in another application? Many people accidentally leave ttytter running at home and then ssh in from work, starting two sessions (don't ask how many times I've done this). Also, if you have widgets or other applets that use your username and password to fetch tweets, these will also count against your rate limit, and if you have ttytter running a cron job that isn't -anonymous, that will count too.

  • Make sure you don't have -pause or -dmpause set too low (i.e., to frequently request new tweets). Setting -pause to 60, for example, makes TTYtter fetch every minute, meaning you're up to 60 requests an hour without anything else running.

  • Be aware of what impact your commands have. Refreshing your timeline or DM box manually is another hit, and commands like /replies, /again are a hit each, and /whois is another hit (so (so /wagain is double). If you don't understand what impact your usage habit has, consider using ttytter -verbose so you can see exactly what is occurring behind the scenes.

• How do I encrypt my session?

  See the section on TTYtter and SSL.

Download and change-log

• ttytter 0.8.6 (Perl script text; 36KiB)

• Old versions (warning: buggy!; not guaranteed to work with current Twitter API; use at your own risk)

ttytter has been tested against Perl 5.0050x running on AIX with Lynx 2.8.2, Perl 5.8.6 running on Mac OS X 10.4.11 with curl 7.13.1, Perl 5.6.1 and 5.8.8 running on NetBSD/macppc with Lynx 2.8.5, and Perl 5.8.8 running on the OLPC XO-1 Build 650 (Linux) with curl connecting both directly and through an HTTP proxy (configured for Lynx/curl). It is guaranteed to make Larry Wall nauseous just looking at it. There are also successful reports from users of Cygwin.

Changes in version 0.8.6:

• Status changed to 'deprecated' fork.
• Control character filter added (backported from 0.9.x) and expanded to pre-interpret most common mistaken entries.
• Bug fixed with @ names framed with certain punctuation not getting highlighted.
• Backed out kludges for bowdlerized /whois and less efficient workaround JSON fetch.

• Split into 'stable' fork.
• Bug fixed with UTF-8 handling, even on systems and Perls that don't understand UTF-8.
• Bug fixed with users with no DMs.

• Several temporary workarounds for glitches in the Twitter API, namely a kludge for eating invalid JSON generated by tweet deletes, disabling some fields in /whois that were pulled, and turning off friendship checks as they currently generate 500 errors. The tweaked JSON fetch is also marked as kludge. These temporary fixes will be backed out when they are fixed on Twitter's end.

• Tweaked fetch routine pending eventual format of null responses (i.e., much less spurious timeout or no data messages).

• Twitterer names, and @ names, are now boldface and underline respectively based on patches submitted by @smb.
• Expanded /whois with code for looking up friendships, and processing avatar images (-avatar, -frurl).
• API additions ($precommand, $prepost, $postpost).
• Certain HTTP status codes could cause the JSON parser to freak out. Fixed.
• -noansi didn't take precedence over -ansi like it was supposed to. Fixed.

• $lasttwit, and origination classes for $handle, both API enhancements suggested by @emilsit.
• -lynx and -curl can be told to run a specific binary, useful for PATH-deficient environments or version testing.
• -status correctly warns for tweets over 140 characters.
• Speaking of which, normal tweet activity also has better warning text for oversize tweets too.
• Additional debugging information for failed test logins available.

• Robust scripting support for simple command-line queries (/end and -script).
• -pause=0 is now valid.
• Popping words off the end of the line (%%--, etc.) works.
• API additions (&standardtweet, &standarddm, DUPSTDOUT).
• Null array references could escape from certain asynchronous commands and cause uncaught exceptions. Fixed.
• &prinput allegedly took arguments, but ignored them and just used $_ like it used to. Kludged around.

• Null array references could leak from the JSON parser, which would throw an uncaught Perl error. Fixed.
• /ruler (suggested by @jspath55).

• Changes suggested and coded/adapted from code by @br3nda:
  • ANSI colour and highlighting (and -ansi/-noansi).
  • Timestamp support, including templates on supported installations (-timestamp).

• Replies support (/replies and -rurl).
• /again expanded to allow querying user timelines (and -uurl).
• API expanded with $prompt, &defaultprompt and -twarg.
• Anonymous mode (-anonymous).
• User query (/whois and /wagain, and -wurl).
• JSON parser upgrades to accomodate user queries.
• Error message reporting fixed.
• Proper detection of presence/absence of modules (particularly fixing problems with -seven) and streamlined BEGIN block.
• No need to pause with -silent.
• Several side effects have now been incorporated as virtues.
• Author breaks 10,000 tweets. What a dweeb he must be.

• Improved stability in JSON validator when using Lynx as the user-agent.

• Direct message support added to both interactive client and API, with -dmurl and -dmpause.
• -silent mode and exit statuses.
• Abstraction of console input processing to facilitate future expansion in both API and internal code.
• Recognizes new-format Twitter error messages. (Correspondingly, some API exception codes are now deprecated; see documentation.)
• Command abbreviations.
• Expanded command history support and -maxhist.
• Reworked error messages.
• Various custodial fixes and upgrades to JSON interpreter.

• Patched for various entities in the new Twitter JSON release. This version will correctly handle both ampersand-escaped and standard entities and quotes.

• Support for rate-limited API, in two ways: first, increasing default timeout to 120 seconds, and two, properly recognizing when rate-limiting has kicked in.
• Stability improvement in JSON validator.
• Additional API exception codes for the above features.
• select() loop tightened up to make timeline hits as minimal as possible.

• UTF-8 now works right (most of the time). Added -seven option for backwards compatibility.
• First support for the TTYtter API and the -lib option.
• Detached mode using -daemon, allowing bot building.
• Tweaks to defaults.
• Work-around for out-of-order tweets "stuttering" or getting stuck. This is technically a Twitter bug, but this version can now ignore the anomaly.

• Even bigger morer robuster JSON validator.
• Posting from the command line using -status.
• Can now configure update source using -update, allowing complete abstraction of TTYtter assuming the other side supports the Twitter API over JSON.
• -hold timeout tweaked.
• Messages tweaked for accuracy and semi-user-friendliness.

• Improved detection of Twitter HTML status messages and better tolerance of partially-transmitted data (which could sometimes cause ttytter's JSON validator to freak out).
• Added "re-tweet" facility for ... retweeting.
• Added -hold option.
• Another hal-fassed attempt at better UTF-8 handling.
• Exit statuses of curl/Lynx sessions are properly reported.
• Proper command line precedence over default options.