Return to Main Page
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
- 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
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
- 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
- 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
- How do I turn ANSI on?
Use -ansi, or put ansi=1 in your .ttytterrc. See
- 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
- 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
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
- 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,
- 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
Subscribe to updates over Twitter! --
(or visit Floodgap Updates)
- ttytter 1.2.05
(Perl script text; 194KiB). TTYtter is under the
Floodgap Free Software License.
- Term::ReadLine::TTYtter (optional), version 1.3:
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
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
Important support note for Perls < 5.8.6
The version 1.1 branch was the last version to include out-of-the-box
support for versions of Perl prior to 5.8.6. Starting with version 1.2,
there is no routine testing on 5.005 or 5.6
as I am not using
TTYtter on those machines routinely. However, none of the existing
compatibility code will be removed unless necessary, and patches for these
earlier versions of Perl
will still be accepted assuming they are reasonable (in my sole judgment)
and work without modification on later Perls. To run TTYtter
under 5.005 or 5.6, you must pass the -oldperl option, or put
oldperl=1 in your .ttytterrc. Bug reports for
these earlier versions without patches will be ignored as I have no
ability to test code on them. Please note Perl 5.004 and previous have
never been supported. Send your patches to me at
Changes in version 1.2.5:
Changes in version 1.2.4:
- 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
Changes in version 1.2.3:
- The -status=- patch in 1.2.3 broke passing statuses on the
command line (that'll teach me to proof patches better). Fixed; thanks
Changes in version 1.2.2:
- 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
- Repairs to -retoke, which should once again work with
- Tweak for multi-line -status=- (thanks
for the patch).
- The old, undocumented debugging option -freezebug was
obsolete as of 1.2, and now is completely removed.
Changes in version 1.2.1:
- 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
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
Changes in version 1.2.0:
- 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
Changes in version 1.1.12 (bug fixes and critical improvements only;
these fixes are also in 1.2.0):
- 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
- 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
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
for the idea).
- -statusurl lets you shorten and append a URL to a
for the patch).
- .ttytterrc is treated as UTF-8 by default
for the report;
wontfixed for 1.1 for compatibility reasons).
- -backload=0 shouldn't load anything, and now it doesn't
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
- All bug fixes from 1.1.11 and 1.1.12.
Changes in version 1.1.11 (bug fixes and critical improvements only;
these fixes are also in 1.2.0):
- Patches for Perl 5.14 (thanks
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
for the report). Similarly, /short should also work, emitting the
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
for the report).
- -readline autocomplete command list now up-to-date.
Changes in version 1.1.10:
- 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
- One last issue related to URL shortening.
Changes in version 1.1.9:
- Code adjustments to avoid double-decoding UTF-8 sequences internally
- Fixed crash in readline autocompletion when metacharacters were present
- Optimized readline statistics are now case-insensitive so that weighting
is more correct.
- Corrected flaw with -verify where prompts went to the wrong
- 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
for the report).
- Custodial code cleanup pre-1.2.
Changes in version 1.1.8:
- Signals now should operate correctly on Solaris and other systems
using SIGXCPU/XFSZ (thanks
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
- -notifyquiet turns off the test notify sent by your chosen
- -daemon mode is no longer limited by the need to assign
menu codes, allowing it to accept ridiculously large data slurps.
- Changes related to
- 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.
Changes in version 1.1.7:
- 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.
Changes in version 1.1.6:
- -daemon mode works again.
- New-format Twitter error messages are automatically unwrapped.
- Changes related to
(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
Changes in version 1.1.5:
Changes in version 1.1.4:
- Backed out select() debugging code due to way too many
false positives. It can be re-enabled with -freezebug for
- Small custodial changes in progress.
Changes in version 1.1.3:
- 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
- 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
- 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.)
Changes in version 1.1.2:
- 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.
- Replies now take priority always over search results with
- 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.
Changes in version 1.1.1:
- -status with UTF-8 characters now works correctly again from
the command line (as long as your locale is set correctly, of course).
- $shutdown now correctly fires even if a child process was
Changes in version 1.1.0 (this version is an updated form of the public
beta, released as is due to the switchover; expect minor bugs, which will
be rectified in 1.1.1):
- 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
many others for data points)
- When looking for tools, TTYtter will now check your path
first before its built-in locations. (thanks
- 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.
For changes in version 1.0.4 and prior (all the way back to 0.2!), see the
- 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.
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
- /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
- All bug fixes from 1.0.3 and 1.0.4.
Send comments and blank cheques to firstname.lastname@example.org.
Top of the page |
Return to main page