Return to Main Page

TTYtter Command Line Options

There are many useful options you can pass on the command line. Not all options are supported in prior versions; see the changelog when support for a particular option was added.

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), 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). However, with /set, you must 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. 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).

-user=[name][:passwd] (required, except if you specify -anonymous [see below]) (*)
Specifies username and password. If you have a password like pa$$word that has shell metacharacters in it, quote the string like ./ttytter '-user=screwtape:pa$$word'. (Versions 0.9.5 and prior also require backslashes before the metacharacters.) If you want to explicitly override this and access Twitter without authentication, look at -anonymous.

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. You should still make sure to backslash metacharacters here too, although you do not need the quotes.

If you're even more paranoid and want an even more locked-down way of saving your credentials, look at the $authenticate method in the TTYtter API.

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

Starting in 0.8.2, 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.

-pause=[pause] (optional)
Specifies the timeout in seconds for the background process. Starting in 0.9.0, 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 -dmpause setting 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).

Starting in 0.8, 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).

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

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

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.

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

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

-timestamp=[template] (optional) (*)
Forces timestamps to appear on all tweets, 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 in 0.8+ (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 %%.

-anonymous (optional, except if you do not specify -user) (*)
Indicates that you will not be using an authenticated username to read tweets. (You must either explicitly indicate this option, or otherwise use -user; 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 -user 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).

-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. For example, with Identi.ca, as of this writing you also have to enable -notrack and -noratelimit, and then specify -pause=90 -dmpause=0 (or some other fixed interval for -pause=...).

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

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

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 the re-tweet. 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).
-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.
-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; if you are Evel Knievel, 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 a library with -lib) 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).

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 the patch in trac ticket 147 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 define your own notification system driver using the API.

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 not really very 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.
-olib=[Perl text] (optional) (*)
Used for inlining Perl to pre-execute as a command line extension ("one line library"). See Advanced usage. If your library includes spaces or shell metacharacters, and I bet it does, they should be escaped or quoted as with any other argument.
-lib=[filename] (optional) (*)
Used for installing an extension from a file. See Advanced usage.
-twarg=[argument] (optional) (*)
Specifies a user defined argument string, where you can pass any data you like. TTYtter doesn't make any use of this by definition, but your extension library can by looking at $twarg. 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:

user=screwtape:wormwood
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 your password has shell metacharacters in it, they must be backslashed in versions prior to 0.9.6 (e.g. pa\$\$word).

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 laconi.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. If you don't specify -rc, or explicitly say something like -rc="" with a null argument, then the default ~/.ttytterrc is used.

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.

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