![[Back to the Floodgap main page]](/pix/hosted.gif "[Back to the Floodgap main page]")
Return to Floodgap Software
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.
(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
#+$$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> a0> <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):
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):
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
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
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.
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.
If you type /print by itself with no key, the (visible) settable values are displayed.
/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 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,
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
(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
Then you can see the threads that any of those belong to:
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,
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:
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
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:
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 <<< TRENDING TOPICS >>> /search #sxsw OR SXSW /tron #sxsw SXSW /search Twilight /tron Twilight /search Ireland /tron Ireland [...] <<< TRENDING TOPICS >>>
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.
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):
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. 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 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
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
, 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
and run that, then we're rolling. You can also make this automatic by putting
apibase=http://identi.ca/api noratelimit=1 notrack=1 pause=90 dmpause=0
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:
(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,
/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). 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.
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.11 and look at the change log and known bug list.
Send comments and blank cheques to ckaiser@floodgap.com.