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 on the command line. You can even pass gas. No, not really. But they sure are useful.

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).

-keyf=[keyfile] (optional, except if there is no default keyfile stored in ~/.ttytterkey) (*)
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 prefer not to 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).

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

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 instead unless you want to use the new pure OAuth workflow. Note that regenerating tokens will cause your previous keyfiles for that screen name and all copies of them to become invalid. These options should rarely be necessary.

-seven (optional) (*)
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 (optional) (*)
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 and -noansi (optional)
Forces ttytter to enable or disable ANSI colour sequences, respectively. If you don't specify, ttytter turns on ANSI colour 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. -noansi overrides -ansi, so if you pass both together, then -ansi is ignored. This is also true for -script, which implies -noansi (see -script).

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

-noansi 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.

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

-synch (optional) (*)
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).

-pause=[pause] (optional)
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 120-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 120 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. I wouldn't make this any lower than 60, even if you're whitelisted, unless you have a good reason. 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).

-dmpause=[interval] (optional)
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.

-track=[trackterms or hashtags] (optional)
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. Remember, limits on this service are by IP address and you may be separately rate-limited by the Search API even if you have enough rate limit for your regular authenticated timeline.

-mentions (optional)
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).

-readline=[completer preload string] (optional) (*)
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.

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="@doctorlinguist @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 1.1 and TTYtter 1.1.7 or higher for these options to take effect.

-ssl (optional) (*)
Rewrites the default Twitter URLs (but only the standard Twitter URLs; not, for example, the Search API or non Twitter URLs like -queryurl, -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 (optional) (*)
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).

-status=[status text] (optional) (*)
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 absolutely need to be posting hyphens and can't pass a '-' on stdin, you can use -oldstatus as a deprecated stopgap. This option will be removed in 2.0.

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 (optional) (*)
Forces a specialized mode designed for running commands from a script file or passed via standard input. -script implies (forces) -noansi, -vcheck=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] (optional) (*)
Implies -script, and executes a single command as if it were typed into the console. See Scripting TTYtter and Advanced usage.

-timestamp=[template] (optional) (*)
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 (optional) (*)
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 (optional) (*)
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 every three minutes 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 if the kittens-of-death are using the Obvious server room for a scratching post.

-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 (optional) (*)
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:

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. However, Twitter is checking for abuse and your IP address will be ratelimited to around 100 per hour unless you are whitelisted or have made prior arrangement.

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

Access to the Twitter Search API is inherently anonymous, so you don't need this option to make your searches and tracks anonymous, and you can still access and make requests for tracked terms and searches if you are anonymous (like /search, /track, etc.). However, if you overdrive the Search API, you may be ratelimited or kicked off (this is enforced by IP).

-authtype={oauth,xauth,basic} (optional) (*)
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.

"Little X" xAuth support is included, but is only supported with OAuth keys that have this support specifically authorized by Twitter. Its use is beyond this document's specification, and this support should be considered experimental. xAuth support is deprecated as of 1.2 and will be removed in 2.0. It requires -user=... (below). If you are not using Twitter's service for tokens, change the URL using -xauthurl=....

-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 Twitter 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] (optional)
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] (optional)
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, and abuse of the Search API with ridiculous values may get your IP banned.

-location (optional)
-lat=[latitude in decimal] (optional)
-long=[longitude in decimal] (optional)
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.

-apibase=[url] (optional) (*)
Sets the base URL for the default Twitter URLs (but only the standard Twitter URLs; not, for example, the Search API or non Twitter URLs like -queryurl, -shorturl, etc. [below]). This is pretty much what you want to use for identi.ca or other 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.

This may not be enough for some services, btw. Depending on what the service supports, you may need any of -authtype=..., -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.

-credurl=[url] (optional) (*)
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] (optional)
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 (or, if you are anonymous, from the public timeline at same). For example, you can specify you always want the public timeline with this, even if you're authenticated; see the Twitter API for the relevant URLs.

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.

-dmurl=[url] (optional)
Specifies the source for direct messages, again in JSON format. If you don't specify, direct messages are downloaded from your inbox 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.
-rurl=[url] (optional)
Specifies the source for replies, once again in JSON format. If you don't specify, replies are downloaded from your source 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.
-uurl=[url] (optional)
Specifies the user timeline URL. This is a little odd in that this URL is actually specified incompletely as a template upon which ttytter builds the actual URL it accesses. If you don't specify, user timelines are downloaded using the URL http://twitter.com/statuses/user_timeline as a base, which is expanded to http://twitter.com/statuses/user_timeline/username.json. Again, all data should be in JSON format. This applies to authenticated and anonymous users. If you want to use this to specify an SSL URL (https://), read the section on TTYtter and SSL.
-wurl=[url] (optional)
Specifies the user query URL. Like -uurl, this is a partial URL that ttytter uses as a template. If you don't specify, user information is downloaded using the URL http://twitter.com/users/show as a base, which is expanded to http://twitter.com/users/show/username.json. Again, all data should be in JSON format. This applies to authenticated and anonymous users. If you want to use this to specify an SSL URL (https://), read the section on TTYtter and SSL.
-frurl=[url] (optional)
Specifies the relationship query URL, which is given user_a and user_b arguments and is expected to return a JSON true or false result. If you don't specify, Twitter is queried directly for relationship statuses. 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.
-update=[url] (optional)
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.
-delurl=[url] (optional)
Specifies the tweet deletion URL. Like -uurl, this is a partial URL that ttytter uses as a template. If you don't specify, tweets are deleted using the URL http://twitter.com/statuses/destroy as a base, which is expanded to http://twitter.com/statuses/destroy/id.json. Again, all data should be in JSON format. 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.
-dmdelurl=[url] (optional)
Specifies the direct message deletion URL. Like -delurl, this is a partial URL that ttytter uses as a template. If you don't specify, DMs are deleted using the URL http://twitter.com/direct_messages/destroy as a base, which is expanded to http://twitter.com/direct_messages/destroy/id.json. Again, all data should be in JSON format. 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.
-myfavsurl=[url] (optional)
Specifies the URL for downloading your most currently favourited tweets. If you don't specify, your list on Twitter.com is accessed. Again, all data should be in JSON format. 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.
-favsurl=[url] (optional)
Specifies the URL to query the favourites for other users. This is also another partial URL used as a template. If you don't specify, favourites are downloaded from Twitter.com using the URL http://twitter.com/favorites as a base, which is expanded to http://twitter.com/favorites/username.json. Again, all data should be in JSON format. 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.
-favurl=[url] (optional)
Specifies the URL for marking a tweet as a favourite. This is also another partial URL used as a template. If you don't specify, favourites are added using the URL http://twitter.com/favorites/create as a base, which is expanded to http://twitter.com/favorites/create/id.json. Again, all data should be in JSON format. 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.
-favdelurl=[url] (optional)
Specifies the URL for removing a tweet you no longer wish to be a favourite. This is also another partial URL used as a template. If you don't specify, favourites are deleted using the URL http://twitter.com/favorites/destroy as a base, which is expanded to http://twitter.com/favorites/destroy/id.json. Again, all data should be in JSON format. 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.
-rtsofmeurl=[url] (optional)
Specifies the URL for fetching "Retweets of me" (that is, NewRTs), in, you guessed it, JSON format. If you don't specify, "retweets of you" are downloaded from your source at twitter.com. This is ignored if you are anonymous, or if you have specified -nonewrts (see below). If you want to use this to specify an SSL URL (https://), read the section on TTYtter and SSL.
-queryurl=[url] (optional)
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. 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 (Twitter Search presently does not), and you should read the section on TTYtter and SSL first.
-trendurl=[url] (optional)
Specifies the trends URL for the /trends command, which is expected to return data in JSON format compatible with the format given by the Twitter Search API service. If you don't specify, the Twitter Search API service is queried. 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 (Twitter Search presently does not), and you should read the section on TTYtter and SSL first.
-shorturl=[url] (optional)
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] (optional)
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 StatusNet install supports it and most of them do. This setting directly affects the behaviour of -autosplit=... (q.v.).
-autosplit={word,char,cut} (optional) (*)
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 (optional)
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 (optional) (*)
Uses a simpler startup banner for slower connections or less intelligent screen readers.
-notimeline (optional)
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 (optional)
Reversibly disables tracking without clobbering your current keyword set. May be required/recommended for certain incomplete Twitter-alike APIs.
-nonewrts (optional)
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 (optional) (*)
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] (optional)
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] (optional) (*)
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 (optional)
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] (optional)
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) (optional)
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 (optional)
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] (optional) (*)
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, say -notifyquiet.

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 in 1.1.4 and later 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).

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

-avatar (optional)
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 (optional)
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 (optional)
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] (optional) (*)
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.
-filter=[option,{option,...}Perl expression] (optional)
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).

Certain options may be added to the filter code to change how the filter is applied. The currently supported one is count, which reports a count of filtered posts on each cycle (so -filter="count,/Obama/i && /ice cream/" shows a number of filtered tweets if any were in fact filtered on each refresh).

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. However, if you really dislike a user so much that you want to filter by username and/or prevent that user from sending you DMs, perhaps you should consider just not following them? For total control, look at the various TTYtter API options.

-daemon (optional) (*)
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,...]] (optional) (*)
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] (optional) (*)
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] (optional) (*)
Used for selecting from multiple .ttytterrc files; see below.
-norc (optional) (*)
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
lynx=1
url=https://twitter.com/statuses/public_timeline.json
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 identi.ca, or one you use for accessing the public timeline, 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