![[Back to the Floodgap main page]](/pix/hosted.gif "[Back to the Floodgap main page]")
Return to Floodgap Software
*** TTYtter is currently at version 1.1.2 (22 June 2010). You can skip to the changelog/download if you like.
*** Subscribe to updates over Twitter! -- twitter.com/ttytter
*** Check out Vince Koser's TTYtter extensions, including groups!
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.
TTYtter logs into Twitter using a system called OAuth, not with your Twitter username and password. OAuth uses a set of keys and secrets to authenticate your installation of TTYtter to Twitter. The OAuth keys and secrets for each account are stored in that account's TTYtter "keyfile" and are used by TTYtter as credentials. You need a keyfile for each account you access Twitter with (but you only need to do this once for each account, and you can copy the keyfile to multiple computers if you use it multiple places). We'll talk about how you create that keyfile in a second.
To install TTYtter, download it to the location you want to run it from (such as your home directory or bin/), make it executable with chmod +x, and then start it from your shell prompt with something like ./ttytter. If your Perl is not in /usr/bin, change the first line (/usr/bin/env on some systems does not support passing arguments in shebang lines, so for maximum compatibility it is not used here).
When you start TTYtter without a keyfile, which will be the case the first time you run it (or the first time you run it after the Basic Auth switchover), it will automatically start an assistant to help you create the keyfile. You only need to create the keyfile once for each account. It will never expire. TTYtter will find where your cURL is located, and if successful, you should see something like this:
% ./ttytter trying to find cURL ... /usr/local/bin/curl -- no version check performed (use /vcheck, or -vcheck to check on startup) ++-------------------------------------------------------------------++ || WELCOME TO TTYtter: let's get you set up with an OAuth keyfile! || ++-------------------------------------------------------------------++ Twitter now requires all applications authenticating to it use OAuth, a more complex authentication system that uses tokens and keys instead of screen names and passwords. To use TTYtter with this Twitter account, you will need your own app key and access token. This requires a browser. The app key/secret and user access token/secret go into a keyfile and act as your credentials; instead of using -user, you use -keyf. THIS KEYFILE NEVER EXPIRES. YOU ONLY NEED TO DO THIS ONCE FOR EACH ACCOUNT. If you DON'T want to use OAuth with TTYtter, PRESS CTRL-C now. Restart TTYtter with -authtype=basic to use a username and password. THIS IS WHAT YOU WANT FOR STATUSNET, BUT WON'T WORK WITH TWITTER AFTER 30 JUNE 2010. If you need help with this, talk to @ttytter or E-mail ckaiser@floodgap.com. Otherwise, press RETURN/ENTER now to start the process.
(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.)
Assuming you got that far, when you press RETURN, you go to the second step. You will need a web browser for this part.
Start your browser. 1. Log in to https://twitter.com/ with your desired account. 2. Go to this URL (all one line). You must be logged into Twitter FIRST! http://dev.twitter.com/apps/key_exchange?oauth_consumer_key=XtbRXaQpPdfssFwdUmeYw 3. Twitter will confirm. Click Authorize, and accept the terms of service. 4. Copy the entire string you get back. -- Paste it into this terminal, then hit ENTER and CTRL-D to write it ---------
Follow the steps exactly; namely, make sure you are logged into Twitter in your browser, then visit the key exchange. What this does is generate a new application key and secret and a new user token and secret, cloned from TTYtter's master key, exclusively for you. Don't worry if you have to do this multiple times; Twitter will just give you the same keys and secrets back each time.
When completed successfully, Twitter will display in your browser a textbox containing a long string of gibberish. These are your keys and secrets. Copy the entire string and paste it into your terminal window, then press ENTER, and CTRL-D. (This tells the shell you have finished pasting data.) Don't worry about spaces or newlines; those will get filtered out. If you did this right, you should see something like this (the key in the example below is non-functional):
ck=fjiVEJObjmeo83793NVjrengDJ984r032NFIEgj3809CXFVUIEoe83wnVN223NFER09&at=123456 7-eighpGEPI389vmVikoGG3483vgijrekfjFVB293xqd&ats=00GeivnPPPqncpodsuQ18VNi3eiBBig OuOchekwIGE ^D -- EOF ------------------------------------------------------------------------ Written new key file /home/screwtape/.ttytterkey Now, restart TTYtter to use this keyfile -- it will use this one by default. (For multiple key files with multiple accounts, write them to separate filenames, and tell TTYtter where the key is using -keyf=... .)
The keyfile this creates lives by default in your home directory, in ~/.ttytterkey. This is the first place TTYtter will look for a keyfile. When you restart TTYtter, it will log you into Twitter using that keyfile, like so:
% ./ttytter
trying to find cURL ... /usr/bin/curl
-- no version check performed (use -vcheck to check on startup)
(checking credentials) test-login SUCCEEDED!
-- processing credentials: logged in as screwtape
###################################################### +oo=========oo+
TTYtter 1.1.2 (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
You have now successfully logged into TTYtter and you can use that keyfile indefinitely for that Twitter screen name. If you use this screen name on other machines you use TTYtter on, simply copy the keyfile there; the credentials are machine-independent. If you are on a machine with other users, consider a prophylactic chmod go-r on your keyfile(s) so that only you can read them.
At this point, the client is ready to go and you can start tweeting, and we'll talk about that below. In the background, TTYtter will automatically fetch new tweets and optionally direct messages and mentions, and feed them to you at regular intervals, allowing you to follow your timeline just like in any other interactive client.
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):
This will be posted as the user in your keyfile (in our examples above, that was screwtape). If you add -silent, then there is no output, which is good for unattended jobs. 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 HTTP Basic Authentication |
TTYtter and StatusNet/Identi.ca
TTYtter and your special terminal environment |
TTYtter and readline support
Scripting TTYtter |
Writing extensions for TTYtter
To send a tweet, just type it. Whatever doesn't appear to be a command (see Built-in commands) 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 don't like the background updates, and only want updates to occur when you request them, use the -synch option. In this mode, only tweets, or pressing RETURN/ENTER, cause updates to occur. This is useful for input methods like Kotoeri that may make it hard to refresh your current line, or if you simply don't like the effect, but robs you of automatic updates.
If you want to cancel what you're typing and start over, press CTRL-U.
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 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. For both of these (very useful: I couldn't live without -slowpost) options, again see Command-line options.
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 /. If you enter a bogus command,
TTYtter will complain at you instead of tweeting it,
which cuts 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.
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 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 /dm with a username and message, e.g., /dm zaphod trillian is gonna kill you when you get home you two-faced jerk. Direct messages are also subject to -verify, -slowpost and -autosplit (again, see Command-line options).
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
and the number from 0-9,
with tweets za0-zz9 reserved for temporary menus the
foreground process constructs (zz0-zz9 always reserved
for thread requests).
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 uses special menu codes 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:
Replies and mentions (with /replies), asking for a user's tweets (/again username) and searches all create foreground menu codes starting with z. These roll forward from za0 to zy9; when the foreground process runs out of menu codes, it simply wraps around (viz., after zy9 comes za0 again).
Threads occupy their own special temporary menu from zz0-zz9 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. Each time you request a new thread, the previous thread menu is destroyed and a new set of codes generated. 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,
Likewise, because you are always receiving new tweets, the background menu codes also roll forward, viz., after tweet y9 comes a0 again. This means that the background has a "memory" of 250 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 using a foreground menu code.
If you don't know if a tweet still exists, don't fret. Whatever is the most recently displayed tweet with that code is always the tweet it will reference.
Deletion (/delete), retweets (/retweet, /eretweet and /fretweet), marking and unmarking favourites (/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 /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.
/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. You can use /deletelast as a shortcut for deleting the most recently posted tweet in this session.
/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 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.
Direct messages also have their own menu codes. These three-character codes always start with the letter d, and 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 250 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
You can follow or unfollow users using /follow, and
/unfollow or /leave, respectively. You can always find out
if a user follows you with /whois or /doesfollow.
Tracking keywords and hashtags, and integration with Twitter Search API
TTYtter can also talk to and run queries
automatically against 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 (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). 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, then the split tweets get placed into %%. See Command-line options for how this works.
In addition, a proper and full command history is also 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.
When using %-substitution sequences, 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). /%% is specifically allowed to let you escape tweets that look like commands.
You can also use %-sequences to do primitive history editing. Since a particularly common task is to try to take words off the end to shorten a tweet, you can 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, e.g., this is cool >> %-3-2. Note that this does not work with :p.
The most recently-shortened URL is always 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.
%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.
As mentioned above, 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 %% so that you can use the other %-substitution sequences to edit it or shorten it.
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 all bytes in a "wide" multibyte 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. Pressing CTRL-U will always clear your line in this case. You might also consider using -synch if your input method is unhappy with TTYtter's background updates.
As of 1.0.1, TTYtter counts tweets in characters, not bytes, allowing you to post a 140-character tweet even if it is longer than 140 bytes when encoded as UTF-8. This is properly supported by -autosplit such that you can split on character and word boundaries. Note that -autosplit=word might be a little odd if you mix, say, Japanese and English in your tweets, because TTYtter currently only knows to split words on spaces and may make a wrong best guess about where to split up your tweet; no okurigana support yet, すみません。
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. If you are using HTTP Basic Authentication, your password is sent in the clear; and even if you are using OAuth (the default), all updates and information you send and receive are also transmitted in the clear except your OAuth secrets, which are only used to generate cryptographic signatures. This 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. All of the applicable URLs will be changed for you. (This assumes you are using the regular Twitter API URLs and might not work properly with Twitter-alike APIs. Also, 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 aren't using the Twitter default URLs, you can use the various URL command-line options to manually specify https:// URLs, or using -apibase to establish a single "root" URL for services such as Identi.ca or StatusNet.
By default, cURL's certificate bundle is old and does 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. Once it's downloaded and converted, copy the resulting bundle file over the old one, or put a line in your ~/.curlrc to specify --cacert to the location of the new bundle (such as --cacert /home/zivadavid/ca-bundle.crt). (On Mac OS X and probably most systems, the default bundle lives at /usr/share/curl/curl-ca-bundle.crt.)
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, ...)
Depending on your operating environment's support,
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 currently experimental, 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.
To switch to Basic Authorization, override TTYtter's normal authentication with -authtype=basic. You will need to specify your username and password with the -user option, like so:
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. (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'.) You can also put these options into your .ttytterrc. In this mode, any keyfile you may specify is ignored.
Avoid using Basic Auth with Twitter: it will not work after 16
August 2010.
TTYtter and StatusNet/Identi.ca
(and other Twitter-alike APIs)
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. Identi.ca only supports Basic Authentication, so additionally add -authtype=basic (described above). Thus, a command like
, plus your usual login options (such as -user=.. with your username and password) and such, will suddenly enable you to authenticate and twitter on that server.
You may need to disable certain features if your remote system doesn't support them; this can cause TTYtter to halt unexpectedly with a security warning if it gets data it isn't expecting. Relevant options might include -notrack, to disable the Search API; -nonewrts, to disable NewRTs; -dmpause=0, to disable checking for direct messages; or -noratelimit, to disable automatic rate limit checking (use -pause with a fixed interval also). You can also put these options 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. 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.)
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 an extension to accomplish this,
please let me know at
ckaiser@floodgap.com. Please,
no attachments unless I request them. Thank you :)
TTYtter and readline support
If you need more advanced command line management than the basic
client offers, TTYtter also 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. The -synch option can help you here, but disables automatic updates.)
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 or your replies, simply passing commands can be all you need. When passing commands to TTYtter, 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. For example, if you put this in a file and pipe it to ttytter -script,
TTYtter will fetch your 20 most recent tweets on the timeline (since /r will start from the beginning, having no history) and your 20 most recent direct messages, and emit them all 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:
Any command that the console understands can be passed, even history substitutions and actual tweets.
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:
Or you can make it even simpler and use -runcommand, which combines -script and your (single) console command all in one:
You can even search Twitter for hashtags and keywords. For example, you can find a lot of Japanese poets this way:
Or you can get your replies on the command line (I have this very line in my crontab so that replies to @ttytter get E-mailed to me at regular intervals -- notice it's not 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 ...
Writing
extensions for TTYtter (-exts)
If scripting isn't enough, you can completely override the engine's guts
for your specific purpose.
Using the -exts=... option, you can specify extensions to
augment TTYtter's core behaviour, including but not limited to
adding new user commands, changing
how received tweets and DMs are dealt with, changing
how errors are reported or altering 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. You can load as many extensions
as you like and mash them up together.
For more information on this very useful function, see Advanced usage.
If you just pass -daemon and don't specify any custom behaviour with -exts=..., 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 -exts=... 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 TTYtter and look at the change log and known bug list.
Send comments and blank cheques to ckaiser@floodgap.com.