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.
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.
- •
- The Extensible Markup Language (XML) <URL:http://www.w3.org/XML/>
standard (W3C)
COPYRIGHT¶
twidge, all code, documentation, files, and build scripts are Copyright
© 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>.