Return to Main Page

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

When this document was early in its origins for TTYtter, 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.

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 Texapp is unable to get authentication information any other way (q.v.).

-keyf=[keyfile] (*)
Specifies the location of your keyfile, namely, the bearer token used for accessing ADN using OAuth. If you do not specify a keyfile, ~/.texappkey is used; whatever you specify to this option is appended to it, e.g., -keyf=xyz causes the keys to be loaded from ~/.texappkeyxyz. If you specify a full path starting with /, then that is used as the filename without further interpretation.

If you start Texapp 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 a valid OAuth bearer token using -bearertoken (below). Be careful of exposing this on the command line; using a keyfile is much safer (especially if the keyfile is only readable by you).

It is not possible to access itself without authentication. However, you may be able to access an ADN-alike service without authentication, which is explained under the -anonymous option.

If your keyfile gets corrupted or you inadvertently revoke Texapp's access, you can refresh your keyfile either by deleting it and restarting Texapp, or by passing -oauthwizard. 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, pass this option, especially for older Perls. This option is mostly for impoverished Perls and/or terminals with deficient 8-bit character support, as well as those systems still using 5.005; you should not use it if you can avoid it. For 5.005 and 5.6, you probably also need to add -oldperl. Remember that Perl versions prior to 5.8.6 are in "extended support" mode and may break at any time.
-curl=[/path/to/curl] (*)
Forces Texapp to use a cURL binary you specify instead of the first one it finds. If you don't expect Texapp to properly find your user agent, or it might find the wrong one, you can specify an absolute filename. 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.
Forces Texapp to enable "ANSI" colour sequences. If you don't specify, Texapp 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 .texapprc, or for those pathological situations where your $TERM setting must be verifiably wrong. You cannot use it with /set, but you can say /unset ansi 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 (*)
Reserved for future support of the ADN Streaming API. Do not use this option yet.

-synch (*)
Enables synchronicity mode, where Texapp only fetches posts when you post an update, or when you press ENTER/RETURN on a blank line. (Commands don't cause a fetch on purpose.) 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 -pmpause only specifies whether to fetch private messages or not, not the actual interval (0 = don't). Synchronicity mode disables streaming (see -dostream).

Specifies the timeout in seconds for the background process. If you don't specify, then Texapp uses auto for the argument, which may dynamically change the rate depending on information received from the server. Right now, Texapp uses a flat 20 second timeout between fetches in automatic mode, but this will be made more intelligent in future versions. You can always bounce refreshes manually with /refresh, and a refresh is always triggered after a post is made.

If you specify -pause=0, then all updates (including PMs 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 posts arrive as usual.

Specifies the ratio of updates for private messages. The default is four, so every fourth check for posts, a private messages check is done too; if you do most of your posting through channels, you might consider making it 1:1 (so an interval of 1). If -pause is auto, then this number is also considered when computing how often to fetch updates.

If you set this to zero, automatic PM checking is disabled. However, you can still do manual refreshes with /pm; 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. An update is always triggered after a PM is sent.

PM 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 PM updates, and non-zero allows them, regardless of the actual value.

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

If you only want to see PMs and channels, use -notimeline (below).

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. This option may be used when computing the rate when -pause=auto.

Causes Texapp to also request messages from people you follow that reply to users you don't (without this setting, you only see messages from them to people that you, also, follow). In other clients this may be referred to as "see directed posts."

-personal (*)
Causes Texapp to default to your personal timeline instead of the global timeline. You can switch back and forth with /global and /personal regardless of which mode you start in. Texapp will remind you when the client starts which stream it is defaulting to.

-track=[trackterms or hashtags]
Starts Texapp 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 .texapprc 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.

-threads=[thread ID,thread ID,...]
Comma-separated list of thread IDs to mix into your timeline. On routine fetches, these threads are scanned and new posts added to your regular timeline along with everything else, even from users you don't follow. See -filterthreads for its almost literal opposite. This is the command line option manipulated by /thf and /thunf.

-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/ and a compatible driver. -readline is not supported for Perls before 5.6.0 (and remember that Perl versions prior to 5.8.6 are in "extended support" mode anyway).

If you have it installed, Texapp uses Term::ReadLine::TTYtter as your default driver. If you want to change this, change the PERL_RL environment variable before starting Texapp 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 dalton".

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

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

-vcheck (*)
-vcheckinterval=[seconds] (*)
On startup, pings with a version check request for the current advertised release of Texapp 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 posts and PMs). 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, Texapp does not send me anything about you personally, only your IP (of course, it's a web request) and your user agent, and the implication that you are using Texapp, 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 ADN. So, besides being kept up to date, your statistics benefit the community! Please use -vcheck!

If you also specify a timeout with -vcheckinterval, then an automatic ping is performed on your behalf after the specified number of seconds has passed. If you don't give a value, 86400 seconds (one day) is used as the default. If you don't specify -vcheck, automatic pings are also disabled.

The ping information may be sent to a mirror of Floodgap at any time.

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

-status=[status text] (*)
Allows you to use Texapp 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 the Texapp API documentation for examples. 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 posts 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.

Additionally, if you pass data over standard input using the above menthod, -status will attempt to slurp all the lines together into one big line (and -autosplit can split upon it), merging the lines with spaces. If you add -multiline to -status, then newlines are preserved, and Texapp uses a different method to try to get all the lines which may be more useful for certain utilities. -multiline disables -autosplit, since they are fundamentally opposed, and is irrelevant without -status.

If you want Texapp 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 the Texapp API documentation.

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

-runcommand=[command] (*)
Implies -script, and executes a single command as if it were typed into the console. See the Texapp API documentation.

-timestamp=[template] (*)
Forces timestamps to appear on all posts and system messages, all the time, instead of just on private 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 Texapp 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 the data output from commands still appears (but no prompts or UI). -silent is implied by -script.
-hold (*)
If ADN is being recalcitrant and you know that your login information and URL are correct, you can make Texapp 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 ADN's just having a bad day and will be up real soon.

-hold also works for -status, in which case it keeps trying until the post is transmitted. In autosplit mode (see -autosplit), this is done for each individual portion. -hold does not apply for sending posts in the interactive client because if there is a problem on ADN's end, you don't want the interactive 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 posts. (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=... and -anonymous, -anonymous takes precedence and user credentials are not transmitted.

-bearertoken=[token] (optional, except if no keyfile available and not anonymous) (*)
Sets the OAuth bearer token transmitted to ADN or the remote service. This overrides any keyfile and is mostly intended for debugging; using a keyfile is more convenient and generally more secure. Be cautious using this option on the command line if you are on a machine with multiple users. For security reasons, /save and -savequit will refuse to write the current value of -bearertoken to your rc file; you must always manually specify it.

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

Sets the requested number of posts to backfill your timeline with at startup and when requested with /again. DO NOT GO CRAZY WITH THIS OPTION, for two reasons: first, ADN is free to ignore the request (and often will during times of high system load), and second, Texapp 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 Texapp 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 ADN doesn't honour requests over 200. This does not apply to tracked terms; for that, see ...
Sets the requested number of posts matching tracked terms to backfill your timeline with at startup and when requested with /again. The default is dynamically set based on the number of terms you have so as not to lag startup unnecessarily. The more terms you have, the slower this gets, since it fetches the same number of posts for each term. In practice, using values over 10 or 20 for a moderate number of keywords or terms starts to really delay startup, and ADN will not honour requests over 200 (and like -backload is free to ignore any request under load).
Sets the requested number of search results to get with /search and with tracked keywords. Notice that this is a request also: like -backload, ADN is free to ignore it.

-lat=[latitude in decimal]
-long=[longitude in decimal]
Sets the latitude and longitude of your "location," which will be sent with your posts 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 Texapp. You can see coordinates and geo-enabled status for a post by using the /dump command.

To deal with incompletely specified coordinates, both must be specified before Texapp 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] (*)
Sets the base URL for the default ADN URLs (but only the standard ADN URLs; not non-ADN URLs like -shorturl, etc. [below]). Should anyone ever create a service that emulates the ADN API, you can use this option to redirect Texapp there and it should "just work." 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 does not allow anonymous access to the API.

-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 ADN. Generally you cannot mix services with this option unless you know the authentication service is interchangeable.

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 Texapp uses as a template. If you don't specify, Texapp uses to query'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 -apibase options; similarly, if you want to use SSL, you will need to explicitly ask for it with this option if your service supports it.

-linelength=[character length]
Sets the maximum line length for posts (see -pmlength=... for PMs). This is characters, not bytes; since UTF-8 and -16 encoding is possible, the post may be greater than 256 bytes if encoding is required for characters outside of Latin-1. This defaults to 256 for ADN; you could use this to shorten your posts if you are crossposting to that "bird service." This setting directly affects the behaviour of -autosplit=... (q.v.).
-pmlength=[character length]
linelength : posts :: pmlength : PMs

The default is 2048 for ADN, and this setting also affects the behaviour of -autosplit=.... Speaking of:

-autosplit={word,char,cut} (*)
Enables autosplit mode, which uses an intelligent algorithm to accept input over 256 (or 2048, for PMs) characters and turn it into multiple posts. The algorithm recognizes @ replies and /pm username (etc.) as salient, and will add them to succeeding autogenerated posts so that replies and PMs 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=... and -pmlength=... settings (q.v.).

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

When used in the interactive client, Texapp will split your post, post the first section, and then put the next part (which may still be over the allowed length) into %%. When your first post 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 ADN for a purpose requiring you to interactively send really long messages.

Even with all this, -autosplit is at the mercy of ADN. There is no guarantee your posts will be received or posted, let alone posted in-order, and if Texapp happens to autosplit in such a way that back-to-back posts are exactly the same then ADN 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 ADN send large multipart messages, period.

-alsopost=[command line]
Tells Texapp to also pipe your post to the indicated tool (you can add command line options if needed; example: ttytter -status=-). Useful for crossposting to that "bird service" or maintaining your own local copies of your posts.

In this mode, the posting is automatic; anything you post that isn't threaded to a reply is passed to -alsopost. If you also pass -manualalsopost, then you must use the /alsopost command (/also,/ap) to post to both (regular posts just go to ADN; posts you precede with /alsopost go to both ADN and -alsopost). If this option is not specified, /alsopost is meaningless, and you get an error.

Turns off your timeline, but does not disable background refreshes, so tracked terms (if you're watching any) and private 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 Texapp is eerily quiet.
Reversibly disables tracking without clobbering your current keyword set. Useful for turning off automatic searches quickly.

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).
Turns on wordwrap for received posts and PMs 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 Texapp prompts are not wrapped and thus it is not supported for those values in case you are ADNing from your Commodore VIC-20 (but you can still specify, say, -wrap=22 and at least get posts and PMs 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. If readline is enabled, this is not entirely independent of the readline command history, and may be completely different if you are not using Term::ReadLine::TTYtter.
If enabled, forces Texapp (and you) to confirm every post 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 post is not posted. If this is a little too annoying, consider ...
If enabled, introduces an artificial delay of the specified number of seconds before a post 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 Texapp prompt (hitting Ctrl-C at any other time or after Texapp indicates posting now will terminate Texapp). 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 -colourpm -colourfollow -colouralien -colourreply -coloursearch -colourwarn -colourdefault)
Specifies a colour name for, respectively, the prompt, your own posts, your PMs, people you follow, people you don't, replies to you or containing your username, posts found by the search system, warning messages and posts 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 posts are yellow, PMs are green, people you follow are boring, people you don't are cyan too, your replies are red, search results are cyan also, warnings are magenta and unclassified posts are boring. There is a priority sequence: your posts, PMs and replies always appear in their indicated colours, regardless of if you follow the person speaking to you or not, and if you follow a user, it appears in the "following" colour even if they also appear in search. Colours do not affect boldfacing or underlining, which occurs even if you are a boring sod and turn that particular colour OFF.
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 post has multiple URLs, then the command will be executed multiple times, sequentially, with each individual URL in order of appearance in the post from left to right.

By default /url suppresses mere mention of from being turned into a URL. If you're weird and you like that action in your browser, that hot hot pointless action, then ... ugh. This only applies to the root page; subpages on are still parsed as links.

-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 10.4+ (using -notifytype=growl), OS X Notification Center for Mac OS X 10.8+ with alloy/terminal-notifier (using -notifytype=osxnc), and modified libnotify for other compatible systems (using -notifytype=libnotify). If your posting agent is in a non-standard place, you can tell Texapp the path to it with -notify_tool_path=....

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 "Texapp" driver in the Growl preference pane, and you can adjust stickiness, timeouts and appearance in the preference pane specifically for Texapp. 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 Notification Center driver requires alloy/terminal-notifier to send notifications on its behalf. Download the app package and put it in /Applications. Make sure that OS X will run it (you may need to change your security setting in System Preferences) or clicking on messages may not properly snap back to the Terminal. The NC driver keeps PMs as separate messages (since they are, truly, messages), but overwrites other notifications to avoid replyspam and the like.

The libnotify driver uses 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. Alternatively, you can also compile this libnotify wrapper (see instructions) and point Texapp to it with -notify_tool_path=/path/to/where/you/put/it. Notifications currently appear as standard libnotify notifications. Currently this is only well-tested on Linux.

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.

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

Specifies the types of notifications to be passed onto the driver specified by -notifytype=..., which are, respectively in order of precedence, private messages, posts you wrote yourself, posts replying or mentioning you, posts generated by search, and everything else. If any of the possible classes for the post or PM are met, the post/PM is sent to the notifier. Note that any posts you make yourself are always classified as "me", even if you mention yourself or repost yourself. You can select multiple types (e.g., -notifies=pm,reply passes PMs and replies onto the notifier, and -notifies=pm,me,reply,search,default sends nearly everything).

Any post class can be specified, though Texapp only defines a subset. If you have defined custom post classes in your Texapp extension's $posttype 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.

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.

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

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.
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. ssfe in particular benefits from this.
-simplestart (*)
Uses a simpler startup banner for slower connections or less intelligent screen readers.

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).
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 posts relating to Obama and ice cream if any were in fact filtered on each refresh; see below for the filtering options you can use). As of 0.6.10, Texapp bunches these counts so you don't get a stream of "filtered" unless other updates occur, or the deferred count goes over a threshold. You can set that threshold with -filtercountmin (the default is 5).

In earlier versions of TTYtter these flags were placed in front of the -filter option, and Texapp still supports this as a compatibility shim, but doing so is deprecated (so you will get a warning; in Texapp "1.0" this "bridge" will be removed).

-filter=[Perl expression]
Implements simple filtering on post 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 Texapp, 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 post text; it is applied to replies, and it is also applied to search results and keywords or hashtags you're tracking, but not to PMs, 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 Texapp API options. -filter is subject to -nofilter.

-filterclients=[Perl expression]
Implements simple filtering on the name of the client that made the post. Like -filter, Perl expression can be anything that evaluates to a true or false (non-zero or zero) value, including a regular expression, and, as above, anything that evaluates to true is suppressed. For example, -filterclients="/dlvrit/||/PourOver/" will suppress both clients.

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

Like -filter, -filterclients is applied to all posts, search results, keywords and hashtags and replies, but not to PMs, usernames or anything else. -filterclients is subject to -nofilter.

See also -notco and -noifttt.

-filterthreads=[thread ID,thread ID,...]
Comma-separated list of threads to filter. Any post that is connected to a thread ID in this list is suppressed. Again, this option is applied to all posts, search results, keywords and hashtags and replies, but not to PMs, usernames or anything else, and is subject to -nofilter. See -threads for its almost literal opposite. This is the command line option manipulated by /thb and /thunb.

Suppresses posts with links and posts made with IFTTT, respectively, which are often a sign or method for crossplanting tweets and other annoyances. These options are completely equivalent to the above general-purpose filtering options with suitable arguments, but are left as a legacy convenience. Again, either option is applied to all posts, search results, keywords and hashtags and replies, but not to PMs, usernames or anything else, and is subject to -nofilter.



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 posts from, and these options can control for that. In order:

-neverfilter is listed by itself because of its radically different purpose: use this for users you explicitly wish to whitelist. Users in this list will never be filtered.

You can put any user into these groups whether you follow them or not, even ones you have muted, blocked or have blocked or muted 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 posts, his events, or any posts mentioning him, nor can he be reposted 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 posts 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 posts will ever appear (they would if you only mute him). 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. (This does not disable muting or blocking.) Your own posts are never filtered, by the way.

Changing any of these options causes Texapp 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.

A comma-separated list of users you don't want /replyall or /replyh to automatically reply to (you can always explicitly specify names, of course). Note that you can still directly reply to posts from these users; Texapp just won't automatically add mentions for them to the reply text if they weren't the poster. Best paired with one of the filter options, or if you follow an account that gets mentioned a lot and don't want to inadvertently spam it.
-daemon (*)
Launches Texapp's background process detached so that you return to the shell immediately, but posts are still being monitored. In this mode you can use Texapp in the background while you still use your shell and post manually from it with -status=.... This is also how you could set up a stand-alone ADN 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.
Automatically saves your settings (these settings!) to your .texapprc file in your home directory, or the one you indicated if you specified a different one with -rc=... (see below), when you quit the client. You can of course save them at any time with the /save command.
-rc=[argument] (*)
Used for selecting from multiple .texapprc files; see below.
-norc (*)
Completely disables checking for a .texapprc* file; see below. Essentially, this tells Texapp that you will be specifying everything on the command line, including required options.

The .texapprc 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 .texapprc in your home directory and put options in it. The format of the file is straightforward; here is one example:


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 use the /save command, or specify -savequit and the client terminates normally, your settings in any existing .texapprc file, or the one specified, are overwritten with the current settings.

If you specify command line options, they override anything in .texapprc. To negate a Boolean option in .texapprc from the command line, specify the option with a value of zero, e.g., to disable the -hold option using the example .texapprc above, pass -hold=0 on the command line; or, to disable ANSI, you might say -ansi=0. Note that if -savequit is on, you will automatically overwrite your old settings with the new ones, so also specifying -savequit=0 may be prudent. Because of the way Texapp processes your command line, it is not possible for it to determine whether you want these to be new defaults or not, so you must be explicit.

If you have several .texapprc files, like one you use for a ADN-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, texapp -rc=1 loads your options from ~/.texapprc1 (like -keyf=... does). If you don't specify -rc, or explicitly say something like -rc="" with a null argument, then the default ~/.texapprc 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 /save or turn on -savequit, then the indicated filespec becomes the target.

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 .texapprc 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 .texapprc* file itself is considered stupid and you will be mocked.

Top of the page | Return to main page

Cameron Kaiser