![[Back to the Floodgap main page]](/pix/hosted.gif "[Back to the Floodgap main page]")
Return to Floodgap Software
*** This is the super duper fully featured 0.9.2 version of TTYtter (15 December 2008). This is now well-tested and is the official version, but if you need or prefer 0.8.x, you can also download 0.8.6. Otherwise, you can skip to the changelog/download if you like.
*** 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.
Yes, I do eat my own dog food.
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 or rate limit probing, or other Twitter-specific features. Please make sure your installation works with Twitter before sending me bug reports about laconi.ca and etc.
(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.
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
test-login SUCCEEDED!
###################################################### +oo=========oo+
TTYtter 0.9.2 (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. @=@ @=@
TTYtter> <barely> Looks like I am going to Baltimore next week
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):
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 ...
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 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.
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
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.
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.
/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).
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.
Also see the -dmpause option under Command-line options.
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") 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 (the "re-tweet") 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 appended to. 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> <doctorlinguist> now is the time
<doctorlinguist> now is the time for all good men to eat pizza
[DM cbqueue/Mon Oct 01 07:31:54 +0000 2007] stop doing that
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.
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.
Remember to read TTYtter and readline support if you intend to use readline support.
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.
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. 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):
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 rlurl=https://twitter.com/account/rate_limit_status.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.
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
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.
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.
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 no 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. 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,
/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 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.
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)
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.
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.
... go download 0.9.2 and look at the change log and known bug list.
Send comments and blank cheques to ckaiser@floodgap.com.