Provided by: twidge_1.1.0_amd64 bug

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.

       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.

       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.

SEE ALSO

       curl(1)

       The twidge homepage at  <URL:http://software.complete.org/twidge>.