Downloading TTYtter, change log, bug list, etc.

I strongly and totally politely and not a bit hostilely suggest that you read this whole page, particularly the FAQs, before running TTYtter.

Frequently asked questions (read first! before you download!)

• Help! I can't log into Twitter with OAuth (Invalid nonce)!

  Check your system's clock. If your clock is off more than a few minutes in any direction, Twitter may give you that message. It's NTP time, homeslice.

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

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

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

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

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

  By default, assuming normal usage, TTYtter is designed to use no more than 50% of the declared rate limit for fetching tweets and DMs. Posting DMs and tweets do not count against your limit. If you're running over the rate limit, check the following:

  • Are you using automatic rate control (i.e., -pause=auto, the default)? This is designed to take into account how often you want direct messages, along with querying the server to see how much activity Twitter is allowing. Unless you have a good reason, use automatic rate limiting -- it's good for you and it's good for Twitter.

  • If, however, you are using fixed time intervals for -pause and/or -dmpause anyway, make sure the effective total does not exceed the posted rate limit or that the intervals aren't set too low (i.e., to frequently request new tweets). Setting -pause to 60, for example, makes TTYtter fetch every minute, meaning you're up to 60 requests an hour without anything else running. Although TTYtter warns you when the rate limit changes, you may also want to check the Twitter status tumblr.

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

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

• Unicode characters look like garbage. or, I can't enter UTF-8 characters properly.

  See the section on TTYtter and UTF-8 support.

• My backspace doesn't work!

  Use stty at your shell to set your correct backspace key (either DEL or BS), with something like stty erase ^? (for DEL) or stty erase ^H (for BS). The easiest way is to type stty erase, a SPACE, CTRL-V and press your backspace key. The right sequence will be inserted. Hit RETURN/ENTER, then start TTYtter. If you have to do this a lot, consider putting it in your login script(s).

  For some users, picking one or the other is necessary. You can try, for example, using ASCII 0x08 for your backspace: stty erase SPACE CTRL-V CTRL-H RETURN/ENTER

• I keep fatfingering my tweets!

  Look at the -verify and -slowpost options.

• How do I turn ANSI on?

  Use -ansi, or put ansi=1 in your .ttytterrc. See Command-line options.

• How do I encrypt my session?

  See the section on TTYtter and SSL.

• How do I run my session with readline, or under a client like ssfe or screen?

  See the sections on TTYtter and readline and custom environments.

• My readline driver doesn't work right.

  TTYtter reports the driver it is using on startup. By default, it looks for Term::ReadLine::TTYtter; if it doesn't find it, it falls back on the basic but impoverished ::Stub driver. You can tell Term::ReadLine to use a different driver by setting the PERL_RL environment variable before starting TTYtter. For example, in tcsh, setenv PERL_RL Perl or setenv PERL_RL Gnu will select T::RL::Perl or T::RL::Gnu respectively. You can also install Term::ReadLine::TTYtter, of course.

  If you have multiple Perls installed on your computer (such as, on Mac OS X, the system-provided Perl and the MacPorts Perl), make sure you are running TTYtter with the right Perl or it won't see T::RL::T (even though it's technically installed somewhere, it's not installed in that Perl's view).

• Can I do groups or lists in TTYtter?

  Yes! 1.2 and up directly support lists.

  For 1.1 and earlier, there is a TTYtter extension by the awesome @vkoser to enable groups support. Get it from his blog, along with his other TTYtter hacks.

Other notes

• Are you using automatic version checking with -vcheck? You should be!
• TTYtter knows nothing of proxies and depends on cURL or Lynx to do that. You can set your own options in each program's respective configuration file. TTYtter will override certain headers and timeouts, but will not override proxy or security settings, so make sure they are correct. Whatever is in your .curlrc or .lynxrc is what it will use.
• Apart from ANSI colours and attributes, TTYtter does not take advantage of any special terminal features or sequences. This is currently a feature of omission so that even the dumbest of dumb terminals can use it, but get used to updates interrupting your typing (just keep typing, it's still there). MUDders will not bat an eye at this.
• Entities like \r \n are intentionally not turned into newlines to avoid scrollspam on small screens. If you really don't like this, use -newline.
• Similarly, a lot of the Twitter metadata is thrown away right now, either because it has no relevance in a text oeuvre, or it makes the screen even more cluttered and dense.
• Search results can't be threaded currently because the Search API does not provide in-reply-to information. Once it does, this should "just work."
• Due to the arbitrary syntax possible with /set tquery and /search, it is not possible to do highlighting within hits generated by those commands.
• Oddiments specific to Lynx: Old versions of Lynx that send incorrect Accept-Encoding: headers will spit out binary data (essentially failing to decompress the response from Twitter) and cause TTYtter to panic. At least 2.8.5rel1 or 2.8.6 is required to avoid this. Also, Lynx users may find that not all errors are caught correctly. For example, when using Lynx as the user-agent and querying a username with /again or /whois, if you query a protected username that you do not have access to, you may get a "no data" error instead of the expected "no permission" message. This is a quirk of Lynx when handling requests that fail authentication or generate errors, and can't be worked around easily. curl does not have this problem. This does not damage your data in any way.
• Where's the JSON interpreter? There isn't one and I'm not using any of the current JSON-oriented modules -- the Perl interpreter itself is doing the heavy lifting for us. Read the &parsejson subroutine to see how this works. There is some token code to prevent malicious servers from being allowed to embed arbitrary Perl in the returned JSON, but just the same, connect to trusted Twitter sources only (using -url or the defaults).

Download and change-log

• ttytter 1.2.05 (Perl script text; 194KiB). TTYtter is under the Floodgap Free Software License.

• Term::ReadLine::TTYtter (optional), version 1.3: available from CPAN. T::RL::T is under the Perl Artistic License. This driver is a beta. It is still in development. Expect bugs.

• Archives and older releases:
  • All 1.x.x versions (warning: versions prior to 1.1.8 will not work with current Twitter API; versions prior to 1.2.0 will only work for existing users)

  • All other pre-1.0 versions (warning: buggy!; will not work with current Twitter API; use at your own risk)

ttytter has been tested against Perl 5.8.6, 5.12.3 and 5.14.0 running on Mac OS X 10.4.11 (PowerPC) with cURL 7.16.3; Perl 5.8.9 running on AIX 6.1 (POWER6) with cURL 7.21.4; Perl 5.8.9 running on Mac OS X 10.5.8 (x86_64) with cURL 7.20.0; Perl 5.10.1 running on NetBSD/x86_64 with cURL 7.20.0; Perl 5.12.0 running on Ubuntu 10.04; and Perl 5.10.0 on Knoppix and Perl 5.8.8 running on the OLPC XO-1 with curl; connecting both directly and through an HTTP proxy (configured for Lynx/curl). It is guaranteed to make Larry Wall nauseous just looking at it. There are also successful reports from users of Cygwin.

Important support note for Perls < 5.8.6

Changes in version 1.2.5:

• Fixes for signals on Linux 3.x kernels, which includes newer releases of Debian and Ubuntu. This requires Term::ReadLine::TTYtter 1.3, which is released simultaneously and has the following fixes:
  • Matching fixes for signals on Linux 3.x kernels.
  • CTRL-D as the first character on a line is now correctly seen as EOF, matching the non-readline version.

• URL-sniffing logic now uses the earlier, more conservative algorithm to eliminate spurious characters (thanks @fukr for the report).

• The -status=- patch in 1.2.3 broke passing statuses on the command line (that'll teach me to proof patches better). Fixed; thanks @dogsbodyorg for the spot.

• Signals restructured to allow $SIG or POSIX.pm-based signalling. The latter is preferred for Perl 5.14+; the former is preferred for for 5.8.6+, 5.10 or 5.12, and is the only supported method for unsupported Perls (viz., 5.8.5 and earlier). This should eliminate the need to manually set PERL_SIGNALS to unsafe for Perl 5.14+, assuming that you have POSIX.pm. You can force TTYtter to use POSIX.pm signals with -signals_use_posix, but it's better to let it choose which method it prefers.
• Repairs to -retoke, which should once again work with dev.twitter.com.
• Tweak for multi-line -status=- (thanks @paulgrav for the patch).
• The old, undocumented debugging option -freezebug was obsolete as of 1.2, and now is completely removed.

• New /entities command extracts t.co links from tweets and DMs so you can see where they point.
• Fixed /trends to use new URL (thanks @Donearm for the report).
• Fixed /trends not to double-double-quote strings when they are already double-quoted. Because that would double-quote them double, you dig?

• Changes to Search API optimizer to accommodate other entities. (A more complete solution eliminating the optimizer entirely is planned for 2.0.)
• RAS syndrome corrected in keyfile generator (with thanks to the supremely pedantic @FunnelFiasco ;).

• Perl 5.8.6 is now the minimum tested version (but see this note on 5.005 and 5.6).
• xAuth support is now deprecated and will be removed in 2.0. Speak now if this will affect you.
• New list support, including building, editing and disposing of lists directly from the client, and mixing lists into your timeline dynamically. You can even turn off your regular timeline and just use a list as your timeline to see only a subset of users. Don't worry, your favourite grouping extensions still work too.
• Many commands can now take an optional +count, allowing limited pagination.
• NewRTs are now the default for /retweet, and the NewRT interface is now complete with retweet counts in tweets, NewRT marking for tweets and /rtsof. /thread also tracks NewRT linkages (thanks @augmentedfourth for the suggestion), and you can /delete them like any other tweet. Appending to a retweet or /oretweet uses the old RT format, or you can say -nonewrts.
• New users now authorize with standard OAuth, eliminating our dependence on the old Twitter key clone system. Users who already have cloned keys don't need to do anything; they will still work. New users should use OAuth. 1.2's -retoke credentials generator also uses OAuth.
• A "pastebrake" reduces spurious tweets caused by accidentally pasting into the TTYtter window.
• The promised /dmsent command is now implemented.
• TTYtter's fetch algorithm has been changed to a "sliding window" system to try harder to get tweets posted out of order, as well as cope with high frequency search keywords.
• You can now specify a custom path to your notify tool for both Growl and notify-send using -notify_tool_path=....
• You can use %%* if you misfired an argument. For example, /re e5 right on bro followed by /re f4 %%* becomes /re f4 right on bro
• The /vcheck command will now automatically populate %URL% with the appropriate URL, so now you can just /open it (thanks @dirtyHippy for the idea).
• -statusurl lets you shorten and append a URL to a -status (thanks @microlifter for the patch).
• .ttytterrc is treated as UTF-8 by default (thanks @kseistrup for the report; wontfixed for 1.1 for compatibility reasons).
• -backload=0 shouldn't load anything, and now it doesn't (thanks @jfriedl for the report; wontfixed for 1.1 for compatibility reasons).
• -lib and -olib are now completely removed.
• API changes: $userhandle for displaying user objects, and new library functions &postjson &getbackgroundkey &sendbackgroundkey.
• All bug fixes from 1.1.11 and 1.1.12.

• Patches for Perl 5.14 (thanks @rkfb for the report).
• Keyfiles can now be regenerated if they are corrupted or need to be updated with -retoke.
• /doesfollow should give true or false with -runcommand (thanks @kaleidoscopique for the report). Similarly, /short should also work, emitting the URL (thanks @microlifter for that report).
• Properly understands a new Twitter ad-hoc error format, which repairs some operations that would unexpectedly appear to succeed but didn't actually (thanks @augmentedfourth for the report).
• -readline autocomplete command list now up-to-date.

• Fixed a bug where TTYtter crashes ungracefully if OAuth credentials fail.
• Fixed regex in command processor that interpreted all commands starting with /p as /print.
• -notimeline is now properly recognized by /set as a boolean.
• One last issue related to URL shortening.

• Code adjustments to avoid double-decoding UTF-8 sequences internally (thanks @cristiangauma for the fix).
• Fixed crash in readline autocompletion when metacharacters were present (thanks @stormdragon2976 for the report).
• Optimized readline statistics are now case-insensitive so that weighting is more correct.
• Corrected flaw with -verify where prompts went to the wrong filehandle.
• Keyword terms in /trends are now quoted for search (thanks @WofFS for the report).
• /short more securely encodes its input so that certain URLs will not be shortened incorrectly (thanks @alexfalkenberg for the report).
• Custodial code cleanup pre-1.2.

• Signals now should operate correctly on Solaris and other systems using SIGXCPU/XFSZ (thanks @jgeorgi for the report).
• StatusNet and Identi.ca support is restored, using a shim that dynamically works up the missing stringified-int fields 1.1.8+ requires.
• -linelength lets you set an arbitrary linelength for Twitter-alike APIs not limited to 140 characters (the default is, of course, 140).
• -notifyquiet turns off the test notify sent by your chosen notification driver.
• -daemon mode is no longer limited by the need to assign menu codes, allowing it to accept ridiculously large data slurps.
• Changes related to Term::ReadLine::TTYtter version 1.2:
  • T::RL::T now keeps up with changing terminal sizes, which should reduce overpaint (thanks @WofFS for the fully functioning patch).
  • Pressing DEL at position 0 no longer causes the app to exit. This was, unbelievably, an intentional feature of T::RL::Perl.

• Emergency fix for signature errors (due to status IDs now overflowing the base ID fields). This may cause TTYtter to be incompatible with some Twitter-alike APIs; I can't do anything about that until they start supporting the *_str versions.
• Smoother fetching from the Search API.

• -daemon mode works again.
• New-format Twitter error messages are automatically unwrapped.
• Changes related to Term::ReadLine::TTYtter (version 1.1 is required for this support):
  • Perl 5.6 is now required explicitly to use T::RL::T. (You can still use 5.005 without -readline, but see the support note above).
  • Most UTF-8 characters should now be properly accepted, and more keyboard layouts work properly on more operating systems.
  • Prompts that are not transmitted to Twitter do not have the character counter, such as Y/N confirmation prompts and so on.
  • The character counter can be disabled completely with -nocounter (as an option to ttytter) for screen readers.
  • The prompt now defaults to ANSI off, unless you pass ttytter the -ansi option. This also allows you to turn ANSI on and off and the prompt will follow. (If you use T::RL::T 1.1 with TTYtter 1.1.6, you will notice that the prompt is no longer highlighted because 1.1.6 doesn't know how to synchronize ANSI state.)

• /unset now sets non-Boolean options now to undef so that it will "do the right thing."
• I swear, /troff no longer strips quotes off quoted terms. If it does, give me your exact track list and the keyword you used. I swear by all that is holy I fixed it this time!
• API tweak: &wraptime, which was "optimized" out in 1.1.6, has been restored as a stub in 1.1.7 for compatibility.

• 1.1.6 is a very large systems update, touching quite a bit of low-level code. In particular, this version requires full POSIX signals to function at all, whereas previous versions only needed them in certain circumstances: your system must support either or both of SIGUSR1/2 or SIGPWR/SYS (i.e., signals 30 and 31), which are used as software interrupt signals between the foreground and background processes, or TTYtter will crash or hang. This has been verified to work on all the supported systems above.

  If your TTYtter abruptly quits when you type commands, your system does not support these signals correctly. Send me a report so that I can investigate a workaround.

• Support for repaintable readline prompts, when combined with a supporting driver such as Term::ReadLine::TTYtter. T::RL::T is custom-designed for this purpose, including dynamic repainting, history synchronization, background signaling, improvements to UTF-8 support and even a character counter. You can add support to your favourite readline driver with some extra stub functions. If you use T::RL::T as your readline driver (which is now the default for -readline if it is installed), /vcheck and -vcheck check its version too. This driver is a beta. It is still in development. Expect bugs.
• Location support with -location, -lat and -long. Your account must be geo-enabled, which cannot be done from TTYtter; you must do it from the Twitter web interface. You can then set a (default) location with -lat/-long, and use -location to toggle if/when to send it.
• /block and /unblock for those users you hate, like @dickc.
• The foreground now sends squelch signals to the background when a command is running, which should reduce command output stepping on background updates.
• -searchhits specifies how many search results to grab from the Search API, both with /search (thanks @jdvalentine) and tracked results.
• /set [boolean] can now be used to set a Boolean option to 1, like /set ansi. Similarly, /unset can now set an option to zero (or literal string "0"). These commands are mostly intended for booleans and may not work right with other options.
• -status can now be passed a line of text over standard input if you use -status=- (that's dash "status" equals dash), which is useful for scripts that can't trust their input but really want to use -hold (speaking of, a bug with -hold holding for an incorrect duration should now be fixed too). If your script can't cope with this and absolutely needs the old behaviour, -oldstatus is available as a deprecated stopgap to use the old -status behaviour, but may disappear in future versions.
• Faster UTF-8 processing.
• Growl notifications on Mac OS X are now asynchronous, which significantly improves their processing speed.
• Background event loop rewritten to drive select() in a more compatible fashion, which should eliminate random freezes (-freezebug is still in 1.1.6 for purposes of debugging, just in case).
• TTYtter now tells you what readline driver it is using, if any. You can set the PERL_RL environment variable to override this (such as Gnu, Perl, TTYtter or Stub).
• All prompts now use -readline when enabled.
• Command line options didn't always override what was in the .ttytterrc file. Fixed.
• Retweeting a tweet with UTF-8 characters should no longer generate a signature error.
• Foreground menu codes are now shown in bold to set them off from background updates.
• -simplestart prints an abbreviated startup banner for slower systems or more dire screen readers.
• JSON fetches are more compatible with arbitrary OAuth signature algorithms, which should help extension authors and /eval jockeys.
• The -readline TAB completion routine now includes all the supported commands (thanks again @jdvalentine).
• API changes: new library functions &sendnotifies and &senddmnotifies, which decouple notification from &defaulthandle and &defaultdmhandle respectively. This allows extensions to send their own notifications without relying on the default handlers (thanks @stormdragon2976 for the use case). In TTYtter 2.0, with the next major revision of the internal API, this idea will be explored much further.

• Backed out select() debugging code due to way too many false positives. It can be re-enabled with -freezebug for testers.
• Small custodial changes in progress.

• You can now ask for additional tweets to backfill your timeline with -backload=[number]. Careful with this option: Twitter can ignore it, and often does, and loading large amounts of data can dramatically slow TTYtter down. This is a down payment on pagination, to come in the very near future.
• You can now specify multiple arguments to -notifytype, such as =growl,libnotify. You will probably need an extension for your particular notification scheme. (suggested by @stormdragon2976)
• Correctly recognizes the StatusNet "fail whale" (thanks @seppo0010 and @yrvn).
• Adjusted user-agent timeouts for iffier links.
• Rescue code for buggy user-agents that ignore timeouts.
• More HTML entities are deciphered in both regular and -seven modes.
• A platform-inless dependent change of the default keyfile umask for better security (thanks @herrold).
• Gopher URLs are now forwarded to the Floodgap Gopher proxy, since Firefox 4 is dropping Gopher support, unless -urlopen uses lynx as its user agent, and /short on gopher URLs adds the proxy on to get an HTTP URL. (Hey, this is a text client. I have to support gopherspace.)

• The JSON parser incorrectly rejects some null strings, which can interfere with logging into OAuth. Fixed. (thanks @alfredhallmert)
• Metacharacters in URLs are now (should be) correctly rejected when fed to the TAB-shortener in -readline. (thanks @johndalton)
• Replies now take priority always over search results with -mentions.
• Exception messages are now timestamped also if -timestamp is on. (suggested by @colindean)
• /cls command to clear the screen. (suggested by @schapendonk)
• Spurious failure with perl -c in 5.005 worked around.
• Corrections to messages and the introductory blurb.

• -status with UTF-8 characters now works correctly again from the command line (as long as your locale is set correctly, of course). (thanks @jlm314)
• $shutdown now correctly fires even if a child process was not launched.

• Corrected (fingers crossed) OAuth signature bugs and UTF-8 problems. Tested on Ubuntu 10.04, Mac OS X 10.6/10.5/10.4 (PPC and x86), AIX and NetBSD 5 with 5.005 through 5.10.1, so if it doesn't work for you, I'll just find a quiet corner and shoot myself. Yes, it's actually shorter than 1.1.0 due to some efficiencies that were possible. (thanks @j4mie, @dariuus, @seppo0010 and many others for data points)
• When looking for tools, TTYtter will now check your path first before its built-in locations. (thanks @seppo0010)
• Better handling for impoverished environments where $HOME may not be defined.
• New mention in Guinness Book of World Records for quickest replacement of a version of TTYtter. It's in the back somewhere, near record number of hours watching Monty Python while singing from the Hungarian Bongosok.

• Official support for OAuth, which is now the default method of authentication. OAuth requires cURL -- Lynx will not work. Basic Auth is still supported for users of StatusNet and Identi.ca, and still works with Lynx, but you must ask for it with -authtype=basic. After 16 August 2010, only TTYtter 1.1.0 and later will be able to access Twitter due to the Basic Auth shutdown. No earlier version of TTYtter will work! Read the main page for how to get your credentials converted to OAuth. You only have to do this once per account.

• Foreground menu codes now roll continuously and wrap around instead of resetting with every foreground command (except for /thread, which still uses zz0 to zz9). This is the completion of the menu code change first introduced in 1.0.0.
• Support for automatically fetching replies with -mentions, even from users you do not follow.
• /deletelast deletes the most recent tweet you made, if you don't like using proper safety nets like -verify or -slowpost.
• /doesfollow command (part of 1.0.4, but originated with the aborted 1.1.0 public beta), telling you if a user follows another or if a user follows you.
• For users requiring -seven, certain single character entities will now be translated from UTF-8 to the nearest ISO-8859-1 equivalent (part of 1.0.4, but originated with the 1.1.0 public beta). This table will expand in the future.
• Various API changes: -lib and -olib are now removed; new library functions; $getpassword and $shutdown (suggested by @colindean).
• All bug fixes from 1.0.3 and 1.0.4.

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