Ubuntu Manpage: twidge - Microblogging client for Twitter, Identica

NAME

       twidge - Microblogging client for Twitter, Identica

SYNOPSIS

       twidge [ -d ] [ -c FILE ] command [ command_args ]

       twidge --help

DESCRIPTION

twidge is a client for microblogging sites such as Twitter <URL:http://twitter.com/> and Identica
<URL:http://identi.ca/> (identi.ca). Microblogging sites let you post short one-paragraph updates,
follow the updates that your friends post, and interact with everyone in the site in a conversation
style.

twidge is a client to make working with microblogging sites faster and easier. It is extremely
versatile, and can be customized to work the way you want to work, and combined with other tools to do
just about anything.

twidge can be used quite nicely interactively from the shell. It is useful directly as-is, and with
simple shell aliases can make a highly efficient system to do exactly what you want. It is perfectly
capable of being your only client for microblogging.

twidge also can be used in an automated way, via cron(1), or it can even integrate with your email
system.

A full list of twidge features, along with numerous suggestions on how to use it, can be found at the
twidge website at <URL:http://software.complete.org/twidge>.

But, if you'd like to get going RIGHT NOW, skip to the Quick Start section below. For now, I'll
summarize a few twidge features; a more comprehensive list is on the website.

FEATURE LIST
• Convenient, easy to learn, and fast command-line interface (it's simple to do simple things, and
advanced things are possible)

• This extensive manual, and numerous examples on the website

• Compatible with any microblogging service that implements the Twitter API. Tested with Twitter and
Identica (identi.ca). Should be compatible with any other system.

• Full support for reading the activity of your friends, replies to you, and your own activity.

• Optional capability to remember what you have seen already and suppress those updates in future runs.

• Optional automatic shortening of long URLs via is.gd

• Optional integration with your email system -- send and receive updates via email.

• Specifically designed to be friendly to use in shell scripts.

• Shell scripting makes it easy to do many things, such as scheduling future updates (with at), ignoring
certain updates (with grep), etc.

• Easy use of multiple accounts by having multiple configuration profiles. Mechanism lends itself to
shell aliases and tools.

• Small, minimalist footprint

• Output formats are easily parsed. Input formats are easily generated. Configuration file format is
liberal and easy to generate.

• Robust error detection and recovery throughout.

QUICK START

This section will describe how a first-time twidge user can get up and running quickly. It assumes you
already have twidge compiled or installed on your system. If not, please follow the instructions in the
INSTALL file in the source distribution.

To get started, simply run twidge setup at your shell prompt. twidge will lead you through the first-
time configuration -- which is very quick and completely self-explanatory!

Now, let's start exploring. twidge lsrecent -su will show you the 20 most recent updates from the people
you follow. After the first time, it will remember what you've seen and only show you new updates. In
place of lsrecent, you could substitue lsreplies to replies to you. You can also run twidge lsrecent
--help, or refer to this document, for more details on the command. In short, -s tells the system to
save what you've seen, and -u tells it to only show you unseen items.

You can subscribe to updates from friends by running twidge follow nick. To subscribe to updates for
twidge itself, you'd run twidge follow unixtwidge. If you've had enough of updates from someone, just
use the twidge unfollow command.

Now, how about posting your own updates? Just type twidge update. Type your update, and press Enter
when done. Your update may scroll past the end of the screen; don't worry about it. Just don't hit
Enter until you're done. You can also pass your update on the command line, taking care to quote it if
it contains spaces or shell characters.

That's the quick tour. For many more examples, refer to the website.

OPTIONS

       twidge  always  is invoked with the name of a specific operation, such as update or lsrecent.  In twidge,
       these operations are called commands.  Each command has its  own  options,  which  are  given  after  the
       command  on  the  twidge  command  line.  A full summary of each command's options is given later in this
       manual.

       You may obtain a list of all commands with twidge lscommands.   Help  is  available  for  any  individual
       command with twidge command --help.  Global help is available with twidge --help.

   GLOBAL OPTIONS
       These options may be specified before any command.

       -c FILE

       --config=FILE
              By  default,  twidge  uses  ~/.twidgerc  for  configuration.  With this option, you can specify an
              alternate file.  twidge will read configuration information from it.   In  certain  cases,  twidge
              will  also  write  to it, such as with the twidge setup command, or the -s option to one of the ls
              commands.

       -d

       --debug
              Enables debugging output.  This verbose output helps you learn what twidge is doing every step  of
              the way and diagnose any problems you may encounter.

COMMANDS IN TWIDGE

       twidge  has  many  different  commands.  You must specify a command when using twidge.  This section will
       discuss each command in detail.  Note that all  commands  are  case-sensitive  and  should  be  given  in
       lowercase.

       All commands support the option --help.  Running twidge command --help will display information about the
       command and its options.  Since all commands support this, it won't be explicitly listed for each command
       below.

COMMANDS TO DISPLAY UPDATES

twidge ls* [ -a ] [ -l ] [ -s ] [ -u ]

Several commands can display updates from yourself or others. They all share a common syntax and common
set of options. The commands are lsdm, lsdmarchive, lsrecent, lsreplies, and lsrtreplies. Here are the
common options:

-a

--all Normally, microblogging sites return one "page" of results -- typically, 20 or 100 results,
depending on the operation. Specifying --all requests twidge to continually send requests to the
microblogging site until it receives an entire set of information. Normally this is a bad idea,
but when used in combination with -u -- especially if you have used -s before -- it can be a
useful way to poll for all new updates.

If not used carefully, this command can generate many requests to the server and can use a
significant amount of bandwidth. Microblogging sites have traffic limits, and will not take
kindly to this. Be careful when you use --all.

-e command

--exec=command
Causes any normal output to be suppressed. Instead, for each item that is retrieved, call the
given command. The command will be passed exactly four arguments. Care should be exercised when
using them in shell scripts due to the likelihood of the presence of shell metacharacters. The
arguments are:

1. The update ID for the given update.

2. The username that created the update

3. A suggested Message-ID for representing the update in email. Contains the enclosing angle
brackets.

4. The update text itself. Likely contains spaces and other shell metacharacters.

-l

--long The default output format shows a nickname and a message, formatted nicely for display. Using
this option causes output to include these columns: message ID, sender nick, recipient nick (empty
unless a direct message), update text, and date created. The output format is suitable for
machine parsing. horizontal tab character \t separates the columns, and is guaranteed to appear
nowhere else. It is also guaranteed that \n will appear nowhere within a line when using -l.

The columns as presented are anticipated to remain stable. However, additional columns could be
added to the right of these columns in future versions of twidge. Well-behaved parsers should be
prepared to discard any surplus columns to the right of those specified in this document.

-m address

--mailto=address
Causes any normal output to be suppressed. Instead, for each item that is retrieved, generate an
email and send it to the given address. The subject line will contain the sender nickname and the
first 30 characters of the text. The body will contain the entire text. The message is sent by
using the program listed as sendmail in the configuration file. If mailfrom is listed in the
configuration file, it is listed as the from address and the name of the sender is listed as the
from comment.

A Message-ID designed to uniquely identify this update is generated and included. In addition,
headers beginning with X-Twidge- will be added, with various metadata.

It should be noted that a simple script could be used with --exec to achieve this same purpose,
but with greater flexibility. The functionality is built into twidge as well for convenience.

-s

--saveid
Saves the ID of the most recent fetched message for future use with -u. Requires write access to
your configuration file.

-u

--unseen
Causes the command to show only items since the last use of -s with this particular command. If
-s has never before been used with this command, has no effect.

Some of these options don't make sense together; for instance, --long, --exec, and --mailto are mutually
exclusive. Results are undefined if you use such options simultaneously.

LSDM
Lists direct messages sent to you. Note: identi.ca does not support direct messages, and this will cause
an error with that service.

LSDMARCHIVE
Lists direct messages you have sent. Note: identi.ca does not support direct messages, and this command
will cause an error with that service.

LSRECENT
Lists recent posts made by you or the people you follow.

LSREPLIES
Lists recent replies made by anyone on the microblogging site to you.

LSRTREPLIES
List retweets of your statuses made by others.

Note: identi.ca doesn't support new-style retweets and will return an error on this command.

COMMANDS TO DISPLAY OTHER INFORMATION

       These commands honor --all and --long like the other commands, but do not honor --saveid or --unseen,  as
       these options make no sense.

   LSFOLLOWERS
       twidge lsfollowers [ options ] [ username ]

       Will  slow  a  list of people following you.  If given an optional username, shows the people that follow
       that user.  If given --long, shows the IDs for each person.  You may need to use --all to get a  complete
       list, but again this may generate significant traffic.

   LSFOLLOWING
       twidge lsfollowing [ options ] [ username ]

       Shows a list of the people you follow.  Arguments and actions are the same as with lsfollowers.

ACTION COMMANDS

These commands perform an action on the server.

DMSEND
twidge dmsend recipient [ status ]

Causes twidge to send a new direct message to the designated recipient. If a status is given on the
command line, it must be presented as a single argument to twidge by the use of shell quoting if needed.
If no status is given on the command line, a single line will be read from stdin and used as the status.

The maximum length of updates on various microblogging sites is 140 characters. Twidge will abort with
an error if your update attempt exceeds that length.

By default, Twidge will attempt to shorten URLs in your updates via an URL shortening service, but only
if your update's length exceeds 140 characters. This means long URLs shorter than 140 characters WILL NOT
be shortened.

If you want all your URLs to be shortened all the time regardless of their length, then set shortenall =
yes in the [DEFAULT] or [dmsend] section of your configuration file.

You can disable URL shortening altogether by setting shortenurls = no in the [DEFAULT] or [dmsend]
section of your configuration file.

FOLLOW
twidge follow username

This command will cause twidge to request that the microblogging site add the given username to the list
of people you follow. It is considered an error to attempt to add someone you already follow.

SETUP
twidge setup

Enters the interactive first-time setup tool.

UNFOLLOW
twidge unfollow username

This command will cause twidge to request that the microblogging site remove the given username from the
list of people you follow. It is considered an error to attempt to remove someone you do not follow.

UPDATE
twidge update [ -i MSGID | --inreplyto MSGID ] [ status ]

twidge update -r

Causes twidge to post a new status to the server. If a status is given on the command line, it must be
presented as a single argument to twidge by the use of shell quoting if needed. If no status is given on
the command line, a single line will be read from stdin and used as the status.

The maximum length of updates on various microblogging sites is 140 characters. Twidge will abort with
an error if your update attempt exceeds that length.

If you want all your URLs to be shortened all the time regardless of their length, then set shortenall =
yes in the [DEFAULT] or [dmsend] section of your configuration file.

You can disable URL shortening altogether by setting shortenurls = no in the [DEFAULT] or [dmsend]
section of your configuration file.

When -r is given, twidge expects to read an RFC2822 email message in stdin. The body of the message will
be used as the content of the update. The References header of the message will be briefly scanned, and
if appropriate, the reply-to attribute of the update will reflect the Message-ID referred to therein.
This way, if you use twidge lsrecent --mailto to email recent items to you, then use your email reply
button to reply to them, twidge will link the two on Twitter. This linkage can be done even if you omit
@reply, but will likely confuse many people because most other clients can't do this. You should still
include @reply.

It should be noted that, in an effort to minimize size and complexity, twidge has an extremely simple
email parser. You should send it only plain text messages. Do not use HTML, RTF, attachments, or
anything that would cause MIME headers to appear in the RFC2822 body. You probably want to turn off your
signature as well. twidge will convert newline characters to spaces when processing your message body.

When -i is given, the internal Twitter ID of a message is expected to be passed. This sets the "in reply
to" flag on Twitter appropriately.

OTHER COMMAND

   LSCOMMANDS
       twidge lscommands

       This command will display a list of all available twidge commands along with a brief description of each.

TWIDGE CONFIGURATION FILE

twidge has a configuration file in which you can set various options. This file normally lives under
~/.twidgerc.

The configuration file has multiple sections. Each section has a name and is introduced with the name in
brackets. Each section has one or more options.

The section named DEFAULT is special in that it provides defaults that will be used whenever an option
can't be found under a different section. If you specify no section names, DEFAULT is the assumed
section. Some items, such as urlbase, are assumed to be in DEFAULT.

Let's start by looking at an example file, and then proceed to examine all the options that are
available.

[DEFAULT]

; If your password contains a percent sign (%), list it twice (%%)

; Path to server API interface -- no trailing slash
urlbase = https://twitter.com

shortenurls = yes

; Last IDs seen by different commands. Written to with -s.

[lsrecent]
lastid = 914881241

Whenever twidge looks for information about a particular option, it first checks to see if it can find
that option in a section for that option. If not, it checks the DEFAULT section. If it still doesn't
find an answer, it consults its built-in defaults.

GENERAL OPTIONS
These are specified in the DEFAULT section.

serverbase
The base URL to access the API of the microblogging site. This should contain the server name but
not the API path. The default is https://api.twitter.com. For Identica, you would use
http://identi.ca/api (note that some users have trouble if attempting to use SSL with identica)..

urlbase
The URL to access the API of the microblogging site. The default, %(serverbase)s/1 is for
Twitter. To use Identica, you would specify %(serverbase)s. Do not put a trailing slash on this
option.

oauthrequesttoken
The URL to access the oAuth request token interface. The default,
%(serverbase)s/oauth/request_token, will work with most environments.

oauthaccesstoken
The oAuth access token URL. Default is %(serverbase)s/oauth/access_token.

oauthauthorize
The oAuth authorize URL. Default is %(serverbase)s/oauth/authorize.

oauthconsumerkey
The oAuth consumer key. Twidge is registered with Twitter and identi.ca and will supply a
reasonable default for those two based on the content of urlbase.

oauthconsumersecret
The oAuth consumer secret. A default is provided as with oauthconsumerkey.

oauthdata
Automatically written by twidge setup. Do not alter.

PER-COMMAND OPTIONS
These options may be specified in DEFAULT or in a per-option section. If placed in DEFAULT, they will
apply to all relevant options unless overridden.

lastid Stores the last ID seen for commands that support -s or -u.

mailfrom
Gives the email address to use for the From: header on messages generated by twidge. Normally
specified in [DEFAULT] so as to impact all commands. If not given, twidge specifies no From:
line, leaving the system's mail transport to assign a default one.

Should contain a bare email address only -- no brackets, parens, quotes, or comments.

When given, Twidge uses the nickname and this address for the From line. When not given, the
nickname is prepended to the Subject line.

savelast
For one of the "ls" class of commands, implies -s on every invocation, rather than require it to
be manually given. This option need only be present; the value you give it doesn't mater.

sendmail
Stores the path to the sendmail executable on your system, used for sending mail. Normally
specified in [DEFAULT] so as to impact all commands. Defaults to /usr/sbin/sendmail.

shortenurls
You may specify shortenurls in the [update] section. It defaults to yes. If set to no, will
cause twidge to omit its attempt to shorten URLs in your updates. If set to yes, will cause twidge
to shorten URLs in your updates, only if the latter's length exceeds 140 characters. See
shortenall

shortenall
You may specify shortenall in the [update] section. It defaults to no. If set to yes, will cause
twidge to shorten all URLs in your updates, all the time. It only makes sense if shortenurls is
set to yes.

URL SHORTENING OPTIONS
twidge uses is.gd as its default URL shortening service.

To enable the bit.ly or j.ump URL shorteners, you must add a [bitly] or [jmp] section to the
configuration file. This should contain two entries: login and apikey as found in
<URL:http://bit.ly/account/>. For example:

[jmp]
login: bitlyapidemo
apikey: R_0da49e0a9118ff35f52f629d2d71bf07

ALIASES
You can add an [alias] section to the config file which will effectively create new commands. For
example:

[alias]
recent: lsrecent -u
replies: lsreplies -u

TIPS & HINTS

       Here are a few tips and hints to make twidge more pleasant for you.

   GOING THROUGH A PROXY
       If your connections must go through a proxy, you'll need to set an environment variable.  If you  use  an
       environment  variable,  your settings may will also impact other applications -- and that's probably what
       you want.  See the Environment section later for tips on doing that.

ENVIRONMENT

       twidge does not read any environment variables directly.  However, it does pass on the environment to the
       programs it calls, such as Curl.  This can be useful for specifying proxies.  Please see curl(1) for more
       details.

CONFORMING TO

       • The Extensible Markup Language (XML) <URL:http://www.w3.org/XML/> standard (W3C)

COPYRIGHT

       twidge, all code, documentation, files, and build scripts are Copyright (C) 2006-2008 John Goerzen.   All
       code, documentation, sripts, and files are under the following license unless otherwise noted:

       This  program  is  free  software;  you  can  redistribute it and/or modify it under the terms of the GNU
       General Public License as published by the Free Software Foundation; either version 2 of the License,  or
       (at your option) any later version.

       This  program  is  distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
       the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General  Public
       License for more details.

       You  should have received a copy of the GNU General Public License along with this program; if not, write
       to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA

       The GNU General Public License is available in the file  COPYING  in  the  source  distribution.   Debian
       GNU/Linux users may find this in /usr/share/common-licenses/GPL-2.

       If  the GPL is unacceptable for your uses, please e-mail me; alternative terms can be negotiated for your
       project.

AUTHOR

       twidge, its modules, documentation, executables, and all included files, except where noted, was  written
       by John Goerzen <jgoerzen@complete.org> and copyright is held as stated in the COPYRIGHT section.