Return to Main Page

TTYtter Command Line Options

There are many useful options you can pass on the command line. You can pass many of them in your rc file or change them dynamically within the client, too. You can even pass gas. No, not really. But they sure are useful.

In earlier versions of this document, I exhaustively documented all the individual URL options for small tweaks to the API. These are almost totally unnecessary and just added cognitive bulk to this page, but remain supported and expanded. If you need these options, look at the opt_urls block in the main script. Only the major ones are now documented in this most current version.

Command-line options

The following options are given in their command line form, with more common options listed first. Some of these options can be changed at runtime using the /set command (for example, /set ansi 1 enables -ansi, and /set ansi 0 turns it off -- or see below for a shortcut for Boolean options), but not all. Options that can't be changed are listed with an asterisk (*).

You can generally see the current value of an option at runtime with /print, such as /print verbose.

Boolean options can just be given as is on the command line (e.g., -ansi). With /set, you can specify an explicit 0 or 1 for false or true respectively, as we illustrated in the /set ansi 0 and /set ansi 1 example above, or simply say /set ansi and /unset ansi. String and numerical arguments that follow on the command line need an equals sign (e.g., -pause=auto); for /set, it just needs to be specified (.e.g, /set pause auto or /set pause 300).

Most options are, well, optional. The only one that isn't is -keyf, and only then if TTYtter is unable to get authentication information any other way (q.v.).

-keyf=[keyfile] (*)
Specifies the location of your keyfile, namely, the bag of OAuth keys and secrets used for accessing Twitter using OAuth. In particular, the file contains your OAuth custom app key and secret, and your user token key and secret. If you do not specify a keyfile, ~/.ttytterkey is used; whatever you specify to this option is appended to it, e.g., -keyf=xyz causes the keys to be loaded from ~/.ttytterkeyxyz. If you specify a full path starting with /, then that is used as the filename without further interpretation.

If you start TTYtter without this option (or the default keyfile doesn't exist), then it will automatically launch the OAuth wizard so that you can create a keyfile. However, if you prefer to not actually use a keyfile, you can manually specify OAuth keys and secrets using -tokenkey -tokensecret -oauthkey -oauthsecret (below). Be careful of exposing these on the command line; using a keyfile is much safer (especially if the keyfile is only readable by you).

It is no longer possible to access Twitter without authentication. However, you may be able to access certain Twitter-alike services without authentication, which is explained under the -anonymous option.

If your keyfile gets corrupted or you inadvertently revoke TTYtter's access, you can refresh your keyfile either by deleting it and restarting TTYtter, or by passing -oauthwizard. Users with legacy cloned API keys should use -retoke, but it is strongly encouraged simply to migrate to the new pure OAuth workflow unless you have a custom key. Note that regenerating tokens will cause your previous keyfiles for that screen name and all copies of them to become invalid.

-seven (*)
Specifies that UTF-8 support should not be enabled. Characters with the high bit set are rendered as dots, and decoding/encoding UTF-8 is disabled. If Perl complains it has no UTF-8 support and/or can't find utf8.pm, pass this option, especially for older Perls. This option is mostly for impoverished Perls, as well as those systems still using 5.005; you should not use it if you can avoid it. See TTYtter and UTF-8 for more information. For 5.005 and 5.6, you probably also need to add -oldperl.
-lynx and -curl (*)
Forces ttytter to use Lynx or cURL respectively. If the one you want isn't installed, an error occurs. If you don't specify, ttytter will try cURL, and then Lynx if it's not found. Remember, Lynx is only supported when using Basic Authentication (see -authtype=...); for all other authentication methods, you must use cURL.

If you don't expect TTYtter to properly find your user agent, you can specify an absolute filename to the cURL or Lynx binary you want to use (e.g., -lynx=/weird/bin/lynx). This is useful for running in improverished circumstances where you might not have (or might not trust?) your environment variables, or if the program is not usually in your PATH.

-ansi
Forces ttytter to enable "ANSI" colour sequences. If you don't specify, ttytter turns on this option if your terminal type given in the $TERM environment variable is either ansi or xterm-color (xterm is intentionally not included because of variable support between implementations), and uses no special terminal sequences otherwise.

If you don't like the colour defaults, look at the -colour* options below (-colourme, etc.).

-noansi is an old vestigial option that exists mostly to override an -ansi that exists in your .ttytterrc, or for those pathological situations where your $TERM setting must be verifiably wrong. You cannot use it with /set, but you can say /set ansi 0 which will do the same thing. You can also say -ansi=0, which is entirely equivalent and forward compatible. -noansi overrides -ansi, so if you pass both together, then -ansi is ignored. This is also true for -script, which implies -noansi (see -script).

-ansi may also be relevant to your ReadLine driver; see -readline.

-dostream (*)
Requests streaming mode (specifically compatible with Twitter User Streams only). Streaming API support is only enabled if you specify this option, and only then if you satisfy the prerequisites required for Streaming API access. Certain options are not compatible with streaming and will disable it even if you specify this option; they are discussed below. Streaming also changes how replies are received and processed. If streaming is not enabled, TTYtter will transparently fall back on the REST API. See TTYtter and the Streaming API.

-synch (*)
Enables synchronicity mode, where TTYtter only fetches tweets when you post an update, or when you press ENTER/RETURN on a blank line. (Commands don't cause a fetch on purpose to spare your API limit.) Otherwise, it sits there and waits patiently, possibly forever until your system crashes due to Y2038. This is useful for input methods -- Kotoeri comes to mind -- that might not like background updates overwriting the screen, but robs you of a continuously updated feed, unless you have the wherewithal or a small, hyperactive child to bang on the RETURN key at regular intervals. In this mode, -pause (below) is ignored, and -dmpause only specifies whether to fetch direct messages or not, not the actual interval (0 = don't). Synchronicity mode disables streaming (see -dostream).

-pause=[pause]
Specifies the timeout in seconds for the background process. If you don't specify, then TTYtter uses auto for the argument, which will watch the declared rate limit on Twitter and automatically compute an optimum rate based on your -mentions and -dmpause settings to use about 50% of your rate limit for automatic fetches. This gives a good balance of being nice to Twitter, but snappy responsiveness. Automatic mode also automatically stops fetching when your remaining request count gets below a critical threshold, and resumes it for you when the rate limit resets. If TTYtter can't get a rate limit amount, it will use a 180-second default until it can. You can always bounce refreshes manually with /refresh.

Otherwise, you can also specify a number of seconds; the recommended timeout is 180 seconds between refreshes, which is designed not to hit the remote server too hard. Remember that setting this too low and thus grabbing tweets from twitter.com too often may cause you to be temporarily prevented from getting them later if you exceed the rate limit (see the FAQ). This may also be true for other Twitter-like microblogging services, and the Search API might even lock you out entirely. Note that even if you specify an actual quantity, the rate limit is still fetched for your information, so if you want to totally suppress this you will need to specify an actual number and -noratelimit (see below).

Automatic rate limiting is only designed for Twitter and exact copy Twitter-like APIs. If you get weird behaviour or TTYtter bugs out, use an explicit number, and/or use -noratelimit (see below).

If you specify -pause=0, then all updates (including DMs and tracked terms) are disabled and must be requested manually. This is forced if you specify -script (see -script).

In streaming mode, -pause only controls how quickly the backing API fetches (and Search API fetches) are retrieved; streaming tweets arrive as usual.

-dmpause=[interval]
Specifies the ratio of updates for direct messages. The default is four, so every fourth check for tweets, a direct messages check is done too. If you decrease this to 1:1, keep in mind you may hit the rate limit depending on what your timeout is. If -pause is auto, then this number is also considered when computing how often to fetch updates.

If you set this to zero, automatic DM checking is disabled. However, you can still do manual refreshes with /dmrefresh and /dmagain; note that all messages are considered "new" the first time you query in this mode, so you'll get a full twenty with the initial request.

DM checking is also disabled if you are anonymous (see -anonymous), or if -pause is also zero (such as with -script; see -script). In -synch mode, zero disables DM updates, and non-zero allows them, regardless of the actual value.

In streaming mode, -dmpause only controls how quickly the backing API fetches are retrieved; streaming DMs arrive as usual.

-track=[trackterms or hashtags]
Starts TTYtter with a default set of terms and/or hashtags to automatically monitor with updates, which should be space-delimited (and thus will need to be quoted so your shell leaves it alone), as if you had entered a /track command from the console. You can use double-quotes for quoted strings, but if you do that, make sure the entire list to -track is surrounded with single quotes so your shell doesn't chop it up. You can put it into your .ttytterrc that way also.

If you only want your tracked terms, and no timeline, use -track together with -notimeline (below).

If you have keywords specified, but you simply want to mask tracking and turn it on and off at will (starting in the off mode), use it with -notrack (below) and then turn it on and off with /set. You should probably also use -notrack to disable tracking when you are connected to a non-Twitter service like Identi.ca so as not to waste Twitter's CPU cycles (or get rate-limited).

-mentions
Causes background fetches to also load any mentions and replies to you, even if they are from a user you don't follow. These mentions are then mixed into your timeline. Because this is done at a 1:1 ratio, if you use -pause=auto this reduces your fetch speed by half (but this may be perfectly adequate, depending on your rate limit).

In streaming mode, -mentions is generally superfluous because you will receive mentions and replies from anyone, anyway (and you will get a warning). The only reason you might want it in streaming mode is if you have frequent issues reconnecting to the stream and absolutely don't want to miss replies.

-nostreamreplies
Only relevant in streaming mode, where it turns off all replies received from the streaming socket. This option is useful if you want to limit your replies to only what you would normally receive from your timeline, such as a harrassing user that for some reason you don't want to actually block (?!) or to ignore users you don't follow and don't care to. If you enable this option, you also are required to get a hoodie and aviator sunglasses, bang out on your fading Smith-Corona typewriter a noodling, meandering manifesto about how the world sucks, and build bombs in your basement. And you can't use TTYtter, because all you have is a typewriter, see.

-nostreamreplies and -mentions together are pointless, because not only will -mentions fetch the replies you are ostensibly ignoring from the stream but it will also burn an unnecessary API call doing so (and you will get a warning).

-streamallreplies (*)
Only relevant in streaming mode, where it enables not only replies to you from anyone, regardless of whether they follow you or not, but also replies from people you follow to anyone else and the replies from those people back to them. This is super-spammy if you have even a medium-size following list or follow accounts with lots of vocal followers. -filterats=... and -filter=... can be very helpful; for example, /\b\@twitter\b/ could filter all replies to @twitter (don't forget that backslash) and keep the rest. For technical reasons, you must restart the client to change this option, unlike -mentions and -nostreamreplies.

-readline=[completer preload string] (*)
Enables readline support, with cursor-key history, interactive editing and TAB completion if your Perl's readline driver supports them. You must have Term/ReadLine.pm and a compatible driver; see TTYtter and readline to make sure that your system meets the requirements. -readline is not supported for Perls before 5.6.0 in any version of TTYtter, even the versions that do support Perls that old.

If you have it installed, TTYtter uses Term::ReadLine::TTYtter as your default driver. If you want to change this, change the PERL_RL environment variable before starting TTYtter to the module name (such as Gnu, Perl, Stub, etc.).

If you specify an optional string, then it is seen as a list of space-delimited options to preload into the TAB completion routine. Because of the spaces, you will probably need to quote the string to prevent your shell from interpreting it, like -readline="@floodgap @ttytter".

-readline is not compatible with -silent, or anything that forces -silent such as -script. You may need to include a -readline=0 on your command line if you have -readline in your .ttytterrc.

Enabling this mode dramatically changes certain aspects of TTYtter's behaviour, so you should definitely read the section on TTYtter and readline before using this option.

There are specific TTYtter options related to Term::ReadLine::TTYtter. These can be specified on the command line, can be changed dynamically, and can be placed in your .ttytterrc. You need T::RL::T for these options to take effect.

-ssl (*)
Rewrites the default Twitter URLs (but only the standard Twitter URLs; not, for example, non-Twitter URLs like -shorturl, etc. [below]) to use SSL with https:// URLs. Before you do this, however, read the section on TTYtter and SSL as there is important information there about certificate support with your client. If you use -apibase (below) to specify an HTTPS URL, you don't need this option (but it's less wordy if you're a regular Twitter user).
-vcheck (*)
Pings floodgap.com with a version check request for the current advertised release of TTYtter and tells you if you are up to date (along with any server messages regarding support status, security announcements, etc.). This check occurs during startup, and is reported twice (once before the test-login, and immediately after the background process has displayed initial tweets and DMs). You can also do this manually with /vcheck. If you are using Term::ReadLine::TTYtter (see -readline), its version is checked too.

If you don't use -vcheck, you will be politely prompted to do so, but I have not made it the default because of the hyper-paranoid. However, TTYtter does not send me anything about you personally, only your IP (of course, it's a web request) and your user agent (cURL or Lynx), and the implication that you are using TTYtter, of course. This helps me know how popular the package is and what people are using as user agent, and the more users we have, the more I can use this as leverage with Twitter. So, besides being kept up to date, your statistics benefit the community! Please use -vcheck!

-vcheck is disabled by -status or -script (below).

-notco (*)
Tells TTYtter not to compensate for t.co autowrapping (and if you are using Term::ReadLine::TTYtter 1.4 or higher, this option is passed to the readline driver so that it also does not use this as part of its length computations).

By default, TTYtter assumes you are connected to Twitter, and that being the case it will parse your tweets for links and correctly compensate for the length (turning URLs and recognizeable domain names into canonically sized 20 or 21 character t.co links) when posting. It will also scan tweets and events and deshortify t.co links back into their source URLs (however, these may themselves be shortened with some other link shortener; extensions like deshortify can help you with this). However, /url still references the t.co URL, as required by Twitter TOS.

This process is transparent and mostly "just works." However, if you are not connected to Twitter, then it is slow and unnecessary, and you can use this option to turn it off. Also, length computations are designed to be more fast than they are accurate, and certain pathologic domain names may be seen as "unshortenable" (whereas Twitter may be able to recognize and shorten them perfectly well; this algorithm is intentionally imperfect).

-status=[status text] (*)
Allows you to use ttytter as a command line tool, like from a cron job or shell script, and automatically post the provided text and exit. You should probably quote the text (e.g., -status="Yo mama is so fat") or your shell may eat portions of it. You cannot use this option if you are anonymous (see -anonymous). See Scripting TTYtter. This is usually more efficient than posting with -script (below), can automatically split up and autopost overlong input with -autosplit (below), and supports automatic retries with -hold (below) to boot.

You can also use this with -daemon (below) so that you can post from the command line while still using your shell, and having the background process asynchronously monitoring tweets like usual.

If you use a single hyphen as your argument (i.e., "-status=-"), then a single line is fetched from standard input and used in place. This is useful when you can't trust your input to go on the command line.

If you want TTYtter to preshorten your URL for you, you can also add the -statusurl=... option, which will be shortened and appended to your -status=... string.

-script (*)
Forces a specialized mode designed for running commands from a script file or passed via standard input. -script implies (forces) -noansi, -vcheck=0, -dostream=0, -pause=0 and -silent, and changes the behaviour of -hold (see below). This is optimized for automatic or unattended command sequences performing simple tasks. See Scripting TTYtter and Advanced usage.

Note that for posting single tweets, -status is generally more efficient than -script. Similarly, for a single command, -runcommand (next) is much more compact than piping commands to TTYtter.

-runcommand=[command] (*)
Implies -script, and executes a single command as if it were typed into the console. See Scripting TTYtter and Advanced usage.

-timestamp=[template] (*)
Forces timestamps to appear on all tweets and system messages, all the time, instead of just on direct messages. If you just say -timestamp with no argument, then the server-provided GMT timestamp is used without further customization or localization. On the other hand, if you have Date::Parse and Date::Format (both part of TimeDate), then you can specify a template to which it will be formatted and displayed instead as an argument (an argument of default will invoke the default of "%Y-%m-%d %k:%M:%S"). If these modules do not exist, then trying to use a timestamp template will cause a fatal error.
-silent (*)
Redirects stdout to the bitbucket, rendering ttytter mute. This is really stupid to do in interactive mode but may be very useful for scripts, or -daemon or -status. Exit status is still returned in the usual convention so shell scripts with && and || work as expected, and tweets and DMs will still appear (but nothing else). -silent is implied by -script.
-hold (*)
If Twitter is being recalcitrant and you know that your login information and URL are correct, you can make ttytter automatically retry the initial test connection at respectful intervals until it gets through. Since this is not what a first-time user will want to do, this option is not the default. However, once you're set up, consider adding it for those situations where the fail whale has crushed the Twitter server room.

-hold also works for -status, in which case it keeps trying until the tweet is transmitted. In autosplit mode (see -autosplit), this is done for each individual portion. -hold does not apply for sending tweets in the interactive client because if there is a problem on Twitter's end, you don't want the client ending up in a retry loop. In that case, you can always retry with %%.

If you specify -script, then the argument you pass to -hold is seen as the maximum number of retries (to prevent, say, a cron job from getting hung up retrying an infinite number of times). Since Perl sees -hold internally as -hold=1, then -script -hold only allows a single retry; otherwise, specify an explicit value such as -hold=5. Without -script, -hold is infinite (unless you, again, specify an explicit value -- in this case, greater than 1).

-anonymous (*)
Indicates that you will not be using authentication of any kind to read tweets. (You must explicitly indicate this option; there is no "implied anonymity.") When anonymous mode is enabled, there are several significant changes:

Assuming you are connected to a service that supports it, this is mostly useful for bots or the voyeuristic sort that wants to watch what's going on and snoop on users without using credentials. Also, because you don't need to get any credentials checked, access is much quicker in anonymous mode, which again is also good for bots.

If you specify both -keyf=... (or -user=..., where applicable) and -anonymous, -anonymous takes precedence and user credentials are not transmitted.

-authtype={oauth,basic} (*)
Specifies the authorization method TTYtter will use with the remote server. The default is =oauth, which uses OAuth authentication based on your keyfile (see -keyf=...). You do not need -user=... (below), and in fact if you do specify a user name and password anyway, it will be ignored with a warning message. OAuth is required for Twitter.

To specify Basic Auth, use -authtype=basic. This requires you to specify a username and password with -user=... (below), unless you explicitly specify -anonymous. You should read the section on TTYtter and HTTP Basic Authentication before using this option for important security considerations. Streaming mode is not compatible with Basic Auth.

"Little X" xAuth support is no longer supported.

-user=[name][:passwd] (optional, except if not anonymous and the authentication method is not OAuth) (*)
Specifies username and password; only relevant if you are not -anonymous and the specified -authtype=... is anything but =oauth. Most of the time, this is used for TTYtter and HTTP Basic Authentication (i.e., -authtype=basic), and you should read that section first. If you have a password like pa$$word that has shell metacharacters in it, quote the string like ./ttytter '-user=screwtape:pa$$word'.

If you don't want to specify anything on the command line, you can put your username and password in a .ttytterrc file.

If you specify only a username and not a password on the command line, and/or TTYtter can't get it from a .ttytterrc file, then then TTYtter will ask you to type in the password. If your Perl supports POSIX::Termios (most do), then your password will not be echoed.

If you want to explicitly access your service without authentication, look at -anonymous.

-oauthkey=[app key]
-oauthsecret=[app secret]
-tokenkey=[user token]
-tokensecret=[user secret] (optional, except if no keyfile available and not anonymous) (*)
Sets the OAuth key and secret, and OAuth user token key and secret. These override any keyfile, but if you specify any of these options, you must specify all of them or TTYtter will not be able to start. This is mostly intended for debugging; using a keyfile is more convenient and generally more secure. Be cautious using these options on the command line if you are on a machine with multiple users.

If you simply want to specify a different set of credentials, it is preferred to place them in a separate keyfile and point to it with -keyf=... (above).

-backload=[number]
Sets the requested number of tweets to backfill your timeline with at startup and when requested with /again. DO NOT GO CRAZY WITH THIS OPTION, for two reasons: first, Twitter is free to ignore the request (and often will during times of high system load), and second, TTYtter has to work exponentially harder to merge timelines with more data in them -- if you ask for a ridiculous amount, say, several hundred, not only will it take TTYtter as long as several minutes to finally start up but it will also overflow the menu buffer and you won't get to see all of them. The default is 30. In practice, using values over 50 starts having noticible effects on performance, and Twitter usually won't honour values much over a couple hundred.
-searchhits=[number]
Sets the requested number of search results to get with /search and with tracked keywords. Notice that this is a request also: like -backload, Twitter is free to ignore it.

-location
-lat=[latitude in decimal]
-long=[longitude in decimal]
Sets the location for your tweets. Your account must be geo-enabled to use this option, which cannot be done from TTYtter; you must turn this support on from the web interface. Once this is done, you can set your latitude and longitude, which will be sent with your tweets if -location is true (if it is false, which is the default, no location information is sent so that you can toggle this on and off at will). You can change your coordinates as much as you like, but coordinates are only accepted in signed decimal: you must convert directions and seconds/minutes before passing them to TTYtter. You can see coordinates and geo-enabled status for a tweet by using the /dump command.

To deal with incompletely specified coordinates, both must be specified before TTYtter will transmit them. Zero is seen as an undefined value on the command line. If you absolutely are sitting on the exact Equator or the Prime Meridian, or just want to make my day, use 0.0 as the needed coordinate.

-woeid=[woeid]
Sets the default Yahoo! WOEID (Where On Earth ID). This is currently used as the default for /trends, but is not transmitted as your geolocation information. It is not automatically set when you change your location with -lat and -long, but if you set these variables, you can then use the /woeids command to find WOEIDs nearest to your location and then set this variable. If you don't set this, WOEID 1 is assumed (global scope).

-apibase=[url] (*)
Sets the base URL for the default Twitter URLs (but only the standard Twitter URLs; not non-Twitter URLs like -shorturl, etc. [below]). This is pretty much what you want to use for Twitter-alike APIs and makes it a lot simpler to move from service to service. Any of the -*url options override this one, but only for that particular URL. If you use -anonymous, you must also use this option, because Twitter does not allow anonymous access to Twitter API 1.1.

This may not be enough for some services, btw. Depending on what the service supports, you may need any of -authtype=..., -oauthbase=..., -notrack, -noratelimit or -nonewrts and/or hard-specifying -pause=90 -dmpause=0 (or some other fixed interval for -pause=...), and you may need to specify your username and password with -user=... if the service does not support OAuth.

If you just want to tunnel your requests to Twitter under SSL and are using the standard URLs -ssl is simpler, but read the section on TTYtter and SSL first.

-oauthbase=[url] (*)
Sets the base URL for the OAuth credential URLs. If you specify an -apibase, that becomes the -oauthbase unless you specify otherwise. By default it uses Twitter. Generally you cannot mix services with this option, since the tokens do not transfer.

If you just want to tunnel your requests to Twitter under SSL and are using the standard URLs -ssl is simpler, but read the section on TTYtter and SSL first.

-credurl=[url] (*)
Specifies the credentials verification service. This is only needed when first logging in, and only if using OAuth as your authentication method (default). All data should be in JSON format, not XML or RSS. If you don't specify, your credentials are verified against twitter.com. If you want to use this to specify an SSL URL (https://), read the section on TTYtter and SSL.
-url=[url]
Specifies the source for tweets. Tweets are only accepted in JSON format, not XML or RSS. If you don't specify, tweets are downloaded from your friends list at twitter.com.

If you want to use this to specify an SSL URL (https://), read the section on TTYtter and SSL.

If you're just trying to turn your timeline off, -notimeline is a better option.

-update=[url]
Specifies the update URL. Although nothing is much done with the returned confirmation except to check that it's there, the URL should still return something useful in JSON format. This option allows you to use a third-party posting service if you like, assuming it supports the Twitter API. If you don't specify, tweets are sent to the standard one at twitter.com. This is ignored if you are anonymous. If you want to use this to specify an SSL URL (https://), read the section on TTYtter and SSL.
-queryurl=[url]
Specifies the query URL for running searches and tracking, which is provided a q= argument with the current search set and expected to return data in JSON format. If you don't specify, the Twitter Search API service is queried.
-shorturl=[url]
Specifies the shortening service URL for use with the /short command (or, if you are using -readline, the TAB completer). Like some of the above options, this is a partial URL that TTYtter uses as a template. If you don't specify, TTYtter uses http://is.gd/api.php?longurl= to query is.gd's API for shortened URLs (and any URL you specify must be accessible/compatible with the same methods). Note that this is not affected by the -ssl or -apibase options; if you want to use SSL, you will need to explicitly ask for it with this option if your service supports it, and you should read the section on TTYtter and SSL first.

-linelength=[character length]
Sets the maximum line length. This defaults to 140 for Twitter and virtually every Twitter-alike API also supports it; changing it is (mostly) irrelevant for Twitter, but allows you to enter long tweets if your local Twitter-alike installation supports it and most of them do. This setting directly affects the behaviour of -autosplit=... (q.v.).
-autosplit={word,char,cut} (*)
Enables autosplit mode, which uses an intelligent algorithm to accept input over 140 characters and turn it into multiple tweets. The algorithm recognizes @ replies and D username as salient, and will add them to succeeding autogenerated tweets so that replies and DMs are properly split too. It is also UTF-8 safe. You can instruct autosplit to preferentially break on word boundaries (=word, the default), or character (=char or =cut).

-autosplit obeys your current -linelength=... setting (q.v.).

In automatic mode (i.e., with -status), the automatically generated tweets are automatically posted in sequence. If you have -hold enabled (strongly advised), then ttytter will hold for each tweet to be successfully accepted before posting the next. If you say =cut, then the tweet is simply split on the character boundary and only the first segment is posted (the rest is thrown away).

When used in the interactive client, ttytter will split your post, post the first section, and then put the next part (which may still be over 140 characters) into %%. When your first tweet goes through, send the next section with %%. If it is oversize also, then it will also be split, and the process repeats until the entire missive can be sent. In this mode, =cut is considered synonymous with =char since you can just ignore the rest and not post it. I have not made interactive client autosplit auto-posting on purpose because there is no -hold in the interactive client, and frankly, you shouldn't be using Twitter for a purpose requiring you to interactively send really long messages.

Even with all this, -autosplit is at the mercy of Twitter. There is no guarantee your tweets will be received or posted, let alone posted in-order, and if ttytter happens to autosplit in such a way that back-to-back tweets are exactly the same then Twitter may simply filter the duplicate(s). In short, autosplit is nothing more than a grotesque hack and should not be used as a reliable method to make Twitter send large multipart messages, period.

-newline
Translates \n and \r into newlines (as appropriate). Other backslashed entities retain their normal appearance. Pathologic numbers of newlines may cause wordwrap to appear odd (see below).
-simplestart (*)
Uses a simpler startup banner for slower connections or less intelligent screen readers.
-notimeline
Turns off your timeline, but does not disable background refreshes, so tracked terms (if you're watching any) and direct messages (if you get any) will still appear. This is mostly intended for bots who only want to follow hashtags and don't care about their regular timeline, or are otherwise anonymous. If you use this without -track, you may find TTYtter is eerily quiet.
-notrack
Reversibly disables tracking without clobbering your current keyword set. May be required/recommended for certain incomplete Twitter-alike APIs.
-nonewrts
Disables features related to NewRTs, such as /rtsofme, NewRT commands, NewRT retweet counts, and other commands for unwrapping or manipulating them. May be required/recommended for certain incomplete Twitter-alike APIs.
-noratelimit (*)
Tells TTYtter to not even bother to fetch rate limit information (without this option, rate limits are fetched even if you specify a fixed interval with -pause for purposes of user information). May be required/recommended for certain incomplete Twitter-alike APIs. However, if you specify it, you cannot use automatic rate limiting (duh) and must specify a fixed interval for -pause=....
-wrap=[width]
Turns on wordwrap for received tweets and DMs and certain prompts. If you specify a width, it is used directly; otherwise, it will either use your COLUMNS environment variable or the constant 79. Wrapped lines are indented, and the word-wrap routine also tries to take into account the displayed prompt length and use it in calculations as well.

Word-wrap will work for values less than 70, but for performance many of the TTYtter prompts are not wrapped and thus it is not supported for those values in case you are Twittering from your Commodore VIC-20 (but you can still specify, say, -wrap=22 and at least get tweets and DMs wrapped). Widths below a certain critical value will simply be mocked.

Although the word-wrap routine is UTF-8 aware, it will wrap but may not properly indent for certain code points (especially right-left writing systems like Arabic script) and pathologic quantities of newlines (when enabled with -newline). Sorry about that; I can't accommodate for every possible combination.

-maxhist=[entries] (*)
Number of entries to add to the history buffer. Since the history buffer is always at least one command long, the total number of history entries will be (maxhist + 1). The default is 19, making a twenty-line buffer.
-verify
If enabled, forces TTYtter (and you) to confirm every tweet you intend to post. This only occurs when you go to post, not commands. Useful if you're prone to dropping text fragments in the wrong window, for example, or have a really really fast temper flare. Only 'y' or 'Y' is considered an affirmative answer; any other answer to the verify prompt is ignored and the tweet is not posted. If this is a little too annoying, consider ...
-slowpost=[seconds]
If enabled, introduces an artificial delay of the specified number of seconds before a tweet is sent, after which it is sent. (The actual send occurs after any command line expansion has been completed, which can be delayed itself if the background process is busy.) A good value for most people with average reflexes is around two or three seconds (I have mine set to 3) -- if you are Evel Knievel and not dead, consider less; if you are Gomer Pyle, you might consider an hour or so. The slowpost delay is announced when it begins and ends. If you hit Ctrl-C or your equivalent interrupt during the slowpost delay, then the post is cancelled and you are returned to the TTYtter prompt (hitting Ctrl-C at any other time or after TTYtter indicates posting now will terminate TTYtter). This requires fairly compatible POSIX signal handling which might not work well on every OS, but seems to work well on most of them. If this doesn't work right for you, or you're too slow to jump on the keys, then use -verify.
-colourprompt=[colourname] (also: -colourme -colourdm -colourreply -coloursearch -colourwarn -colourdefault)
Specifies a colour name for, respectively, the prompt, your own tweets, your DMs, replies to you or containing your username, tweets found by the search system, warning messages and tweets otherwise unclassified. Totally coincidentally, this is almost exactly the same message classifications used by the notification framework (see -notifytype and -notifies below). You may choose from (case insensitive) RED CYAN BLUE YELLOW GREEN MAGENTA, or, if you are boring and colourless, OFF. Colours only appear if you have ANSI mode enabled, or force it on with -ansi. By default, the prompt is cyan, your tweets are yellow, DMs are green, your replies are red, search results are cyan also, warnings are magenta and unclassified tweets are boring. Colours do not affect boldfacing or underlining, which occurs even if you are a boring sod and turn that particular colour OFF.
-urlopen
Specifies a command to be passed to your shell for processing the URL(s) generated by /url. The string %U in your command is replaced with the URL, which is single-quoted automatically for you to avoid metacharacter madness. By default, this is echo %U, which just tells you what the URLs were (and prompts you to be more creative with this option next time). The return code is not checked and your command can do anything that it wants. Passing it to firefox or some such would be an obvious idea, but here are some less obvious suggestions:

If the specified tweet has multiple URLs, then the command will be executed multiple times, sequentially, with each individual URL in order of appearance in the tweet from left to right.

-notifytype=[notification driver] (*)
Specifies the internal (or external, if you passed in an extension with -exts) driver for notification support. Internally, currently Growl is supported for Mac OS X systems (using -notifytype=growl), and modified libnotify for other compatible systems (using -notifytype=libnotify).

Most well-behaved drivers will give you a "thumbs up" when they initialize (for example, the Growl driver sends out a sample notify to register it with Growl's prefs). If you want to suppress this, add a -notifyquiet also.

The Growl driver requires that /usr/local/bin/growlnotify be installed. This is an optional installation that is included in the standard Growl distribution. Notifications appear as the "TTYtter" driver in the Growl preference pane, and you can adjust stickiness, timeouts and appearance in the preference pane specifically for TTYtter. The Growl driver is broadly compatible with most Growl endpoints, including Prowl for those who want to pass notifications to their iPhone or other compatible mobile device.

The libnotify driver is currently experimental. It requires a modified notify-send to accept data over standard input; you should recompile your notify-send using this patch as it does not appear to be part of the standard binary. Notifications currently appear as standard libnotify notifications. Please report problems, as this interface needs further testing.

You can specify multiple notification endpoints by specifying them separated by commas. To make the most of it, however, you should define your own notification system driver(s) using the API.

If your posting agent is in a non-standard place, you can tell TTYtter the path to it with -notify_tool_path=....

Once you specify a notification driver, then you need to specify which types of messages and tweets you want to be sent to it. That is handled by ...

-notifies=[dm,me,reply,search,default]
Specifies the types of notifications to be passed onto the driver specified by -notifytype=..., which are, respectively in order of precedence, direct messages, tweets you wrote yourself, tweets replying or mentioning you, tweets generated by search, and everything else. The tweet is classified by its single highest classification; e.g., a tweet from search that mentions you is classified as a reply/mention (even if you don't follow them), and retweeting yourself counts as your own tweet, not as a mention. You can select multiple types (e.g., -notifies=dm,reply passes DMs and replies onto the notifier, and -notifies=dm,me,reply,search,default sends everything).

If you have defined custom tweet classes in your TTYtter extension's $tweettype handler, then you add them here to pass them onto the notifier (such as -notifies=dm,reply,foobar); see the API documentation.

The notification framework in no way affects the message handling otherwise; they are still shown on your screen, etc.

-avatar
Specifies a command to be passed to your shell for processing the picture URL from /whois. The string %U in your command is replaced with the URL, which is single-quoted automatically for you to avoid metacharacter madness. The return code is not checked and your command can do anything that it wants; I use this for displaying avatar images in ASCII art with commands like this:

Note that in both these cases you will need the requisite image converter installed (namely djpeg and ImageMagick respectively), but you can use whatever image converter you want.

Here is an example of the output (the image is inverted because this was originally from a light-on-dark terminal).

Mac OS X users may find this one particularly handy (have Preview.app open already for best results).

-verbose
Prints additional status information. Sometimes spammy. There is another version of this option with really really spammy output, but those who need to use it should be able to figure it out themselves.
-noprompt
Disables the prompt. This is probably only useful on the command line, but if you really want to turn it off while you're using it ...
-leader=[lead string] (*)
Prints a flag or leadline prior to any additional output, which may be useful for notifying a process manager or screen environment that you are starting the client. If the string has shell metacharacters in it, you should quote it, of course. See TTYtter and custom environments.

-nofilter
Disables the filtering options below. Can be used to dynamically "stick your head out of the bunker" to see if a current filter setting can be safely popped off the stack (as in, /set nofilter).
-filterflags=[option,option,...]
Sets the global flags for the filtering options below. The currently supported one is count, which reports a count of filtered posts on each cycle (so pairing -filterflags=count with -filter="/Obama/i && /ice cream/" shows a number of filtered tweets relating to Obama and ice cream if any were in fact filtered on each refresh; see below for the filtering options you can use).

In prior versions this was placed in front of the -filter option, and this is currently still possible but is deprecated (so you will get a warning; in future versions this "bridge" will be removed).

-filter=[Perl expression]
Implements simple filtering on tweet text. Perl expression can be anything that evaluates to a true or false (non-zero or zero) value, including a regular expression. Anything that evaluates to true is suppressed. For example, if you don't care what flavour of ice cream the President (or more likely his daughters) eat, consider -filter="/Obama/i && /ice cream/". Please don't get cute with this: while it may be possible to embed other things in the code, only expressions are supported and if you get some section of non-expression arbitrary Perl to work and it breaks in a future TTYtter, you were warned. Notice the quotes, since you're guaranteed to have some metacharacters in just about any Perl fragment. If you want positive filtering, such as a white-list, just invert the result of your expression (note that you may need to hide ! from certain shells such as csh).

The filter is compiled before use for speed every time it is changed. If compilation fails, an error message is displayed and filtering is disabled until you correct it.

-filter only supports filtering on tweet text; it is applied to replies, and it is also applied to search results and keywords or hashtags you're tracking, but not to DMs, usernames or anything else. If you're just trying to suppress your users in your timeline and watch tracked terms only, -notimeline is probably what you want, although this is really not particularly sociable. For total control, look at the various TTYtter API options.

-filterusers=[user,user,...]
-filterats=[same]
-filterrts=[same]
-filteratonly=[same]
These four options are grouped together because they control user filtering. Optimally you should not be following people you don't want to read, right? However, with the Search API and streaming it is possible to bring users into your timeline that you don't follow and that you don't actually want to see tweets from, and these options can control for that. In order:

You can put any user into these groups whether you follow them or not, even ones you have blocked or have blocked you, and you can put a user into multiple groups. For example, if user @naughty is in both -filterusers and -filterats, you won't see his tweets, his events, or any tweets mentioning him, nor can he be retweeted in pretty much any meaningful fashion. This user basically won't exist for you at this point.

Because filtering is so complete, intentional action is required on your part to access the tweets of a user that are being trapped by the filter. For example, you wouldn't be able to /again naughty with the example above; none of his tweets will ever appear. To temporarily halt filtering, use -nofilter as mentioned above (/set nofilter to turn filtering off and /unset nofilter to resume), which will disable all filtering including -filter. Note that your own tweets are no longer filtered, which is a change from previous versions where -filter could apply to you.

Changing any of these options causes TTYtter to recompile the filter for speed before use. If compilation fails, an error message is displayed and the filter setting is not installed until you correct it.

-daemon (*)
Launches ttytter's background process detached so that you return to the shell immediately, but tweets are still being monitored. In this mode you can use TTYtter in the background while you still use your shell and tweet manually from it with -status=.... This is also how you could set up a stand-alone Twitter bot. See Advanced usage.
-exts=[filename,[filename,...]] (*)
Used for installing extensions. Specify a comma-delimited list of filenames (which should be full paths); to escape a comma in a filename, simply backslash it like any other metacharacter. For more information on writing your own extensions than you ever dreamed, see Advanced usage.
-extpref_*=[argument] (*)
Options starting with -extpref_ are maintained internally for extensions. See Advanced usage. If you plan to pass spaces or shell metacharacters, they should be escaped or quoted as with any other argument.
-rc=[argument] (*)
Used for selecting from multiple .ttytterrc files; see below.
-norc (*)
Completely disables checking for a .ttytterrc* file; see below. Essentially, this tells TTYtter that you will be specifying everything on the command line, including required options.

The .ttytterrc file

 If you have a set of options you like, or (for example) you don't like giving your password out on the command line, you can make a file .ttytterrc in your home directory and put options in it. The format of the file is straightforward; here is one example: 

keyf=a
hold=1
ssl=1
curl=/opt/local/bin/curl
vcheck=1

Most command line options are simply placed into this file as is, dropping the dash. However, as with /set, Boolean options you are setting to true should be specified with a value of 1; for example, if you want -ansi to be turned on, then you would place ansi=1 into the file. Similarly, say something like ansi=0 if you want to force it to stay off.

Blank lines and lines starting with # are ignored.

If you specify command line options, they override anything in .ttytterrc. To negate a Boolean option in .ttytterrc from the command line, specify the option with a value of zero, e.g., to disable the -hold option using the example .ttytterrc above, pass -hold=0 on the command line; or, to disable ANSI, you might say -ansi=0.

If you have several .ttytterrc files, like one you use for a Twitter-alike service, or one you use with particular search terms, etc., then you can use the -rc=... option to select from them by appending the argument you specify to the base filename. For example, ttytter -rc=1 loads your options from ~/.ttytterrc1 (like -keyf=... does). If you don't specify -rc, or explicitly say something like -rc="" with a null argument, then the default ~/.ttytterrc is used. If you specify a complete path starting with / (such as -rc=/home/nerd/my_rc_file), then that path is used with no appending, also like -keyf.

If you want to make sure that all options are taken from the command line and only the command line (i.e., disable reading from a .ttytterrc file), use -norc (which overrides -rc=...). When this is specified, no rc files are accessed and all required options must be specified on the command line. The default keyfile is still referenced if it exists, however, assuming another one is not specified.

Please note that specifying rc= or norc=1 in a .ttytterrc* file itself is considered stupid and you will be mocked.

Top of the page | Return to main page

Cameron Kaiser