Documentation

Help

Here's the output of "qataki h" (could be outdated):

qataki [i|t|s:<SITE>] [n:<NICK>] [<OPTION> [<ARGUMENT>]]

The first (optional) flag can be: i (identi.ca) OR t (twitter) or
s:<SITE> (see below). If none of of these three flags are given,
then Identi.ca will be used. It is possible to use only 1 OPTION
and, eventually, its ARGUMENT. If no option is passed, messages
from people you follow will be retrived by default.
Options have a default value, but it is possible to modify defaults
by adding/changing key_*=OPTION in $conf_file.

OPTION    ARGUMENT           RESULT
          [+]                Retrive messages from people you follow.
                             If you use the optional "F" argument, all statuses
                             will be displayed. Otherwise only new statuses.
p                            Retrive messages from public timeline.
                             key_public=p
g         <GROUP>      Retrive messages from <GROUP> timeline.
                             key_group=g
u         "message"          Update your status with a "message".
                             key_update=u
U                            Type a message interactively and update status
                             (finish your message with ^D (that is, Control-d)).
                             key_update_w=U
m         [F]                Show notices where you are mentioned (@you).
                             If you use the optional "F" argument, all statuses
                             will be displayed. Otherwise only new statuses.
                             key_mentions=m
r         <NUMBER> "message" Reply to message number <NUMBER>.
                             key_reply=r
c         <NUMBER>           Show conversation relative to notice <NUMBER>.
                             key_context=c
n:<NICK>  <OPTION>           Use an alternate nick. This option can be
                             preceded by [i|t|s:<SITE>] (i by default).
                             key_alt_nick=n
N         <USER>             Show <USER>'s timeline (last statuses).
                             key_user=N
L                            Show previous (last) messages.
                             key_last=L
d         <NUMBER>           Show details about notice <NUMBER> (note that
                             short links will be replaced by real links).
                             key_details=d
s:<SITE>  <OPTION>           Use <OPTION> (exept s itself) on <SITE>.
                             key_sn=s
k                            Configure an account.
                              key_configure=k
S         "string"           Search messages with "string".
                             key_search=S
R         <NUMBER>           Retweet message number <NUMBER>.
                             key_resend=R
M         <USER> "message"   Send a DM (with text "message") to <USER>.
                             key_dir_msg_send=M
f         <USER>|<NUMBER>    Follow someone (AKA subscribe).
                             key_follow=f
F         <USER>|<NUMBER>    Unfollow someone (AKA unsubscribe).
                             key_follow=F
j         <GROUP>            Join <GROUP>.
                             key_join=j
J         <GROUP>            Unjoin <GROUP>.
                             key_unjoin=J
a         <NUMBER>           Add notice <NUMBER> to favorites list.
                             key_like=a
o         <NUMBER>           Open a link present in notice <NUMBER> in your
                             $BROWSER. If more than 1 link is present, a menu
                             to choose from will be displayed.
                             key_open=o



NOTES:

"message" is the message/status you want to send. Enclose it in single or
          double quotes. (Remember to escape them if you use them in your
          message: "It's \"my message\"" or 'It\'s "my message"'.
          It's possible to include a pastebin link in your message. If you
          want to upload, for instance, a shell file and inlude it's link in
          the message include it like "This is my script: %%bash:file.sh". It
          will be replaced by "This is my script: http://pastebin.com/example".
          The general "paste string" is %%syntax:file or %%file. In the former
          case the paste will be highlighted according to syntax. Available
          syntaxes are shown here: http://pastebin.com/api.php

<NUMBER>  is the tweet/dent number displayed on the left when you run
          "qataki [i|t|s<SITE>] [n:<NICK>] [N <USER>]".
<GROUP>   is the name of a Identi.ca/StatusNet group.
<NICK>    is an alternate nickname. You have to pass *alternate* nicknames
          on the command line as n:<NICK>. On the contrary, you don't have
          to specify your *default* nickname. For this, your default nick
          has to be placed in $HOME/.qataki/qataki.conf. This is done by default
          when you use the "k" option. Anyway, the syntax for default nicks is:

          default_user_SERVICE=YOUR_DEFAULT_NICK

          where "SERVICE" can be identica, twitter or <SITE> (see below)
          and YOUR_DEFAULT_NICK is... your default nick on SERVICE.
          You can use alternate accounts if you already have <SITE>
          aliases (this is also done when you run "qataki k"; you can read
          about it below).
<USER>    is a user's nickname (AKA screen_name; no spaces).
<SITE>    is an alias for a StatusNet compatible site. This alias is
          the second field of a line on $HOME/.qataki/qataki.conf structured like:

          site ALIAS http://micro.example.com

          You'll be able to use ALIAS as argument for "s" option, like:

          "qataki s:ALIAS [n:<NICK>]".

          (with the latter example you'll see notices from people you
          follow on http://micro.example.com). For convevience, try to keep
          ALIAS short.

Authorisation is handled by curl with it's "-n" option. This means that a
.netrc file (located in $netrc) is used. Qataki generates .netrc dinamically
when it's run (a 0077 umask is used). When it exits .netrc is restored.

When you run qataki with the "k" option, you can add your username and password
to $HOME/.qataki/qataki.conf. If you ever need to do it by hand, its syntax is:

machine SERVICE login YOU password PASS

where SERVICE can be identi.ca OR twitter.com (and api.twitter.com) OR
a StatusNet compatible microblogging site (without "http://").

FAQs

Are these really frequently asked questions?
No. ;-)
Why Qataki?
I wanted a way to read/post status updates from/to microblogs from the command line. Thus, I started with a couple of lines to download statuses, then added send updates, replies, … (Yes, I know there are already some other CLI clients out there. Reinventing the wheel? Maybe.)
How come the output from conversations is different?
As of April 2010, there's no API for conversations. So, the script just downloads the actual HTML page and formats it. The output, however, seems nice.

Twitter support

In short, you can use Twitter with OAuth. Just download qataki.utils available in the git repo: http://github.com/chr/qataki (remember to check also in the 'next' branch). After you download it you have to put it in $conf_dir (which by default is in $HOME/.qataki). That's all.

Twitter decided to use OAuth for authentication and removed Basic Auth. This implied that supporting it required code OAuth support. I found a simple OAuth Bash library here: http://blog.yjl.im/2010/05/bash-oauth.html and modified it to my needs (including removing a perl dependency, replaced by a modified version of an urlencode script available here: http://www.shelldorado.com/scripts/cmds/urlencode).

StatusNet support

You can use variuos StatusNet sites with the s option. Run qataki k and follow the instructions, otherwise you'll have to do it manually. In this case, you'll have to write in the configuration file (by default $HOME/.qataki/qataki.conf) one row for each site you want to use. For instance, if you have an account on http://test-subdomain.status.net (let's say @you), you have to put (in qataki.conf):

site example http://test-subdomain.status.net
machine test-subdomain.status.net login you password SECRET

where "example" is just an arbitrary alias for http://test-subdomain.status.net.

Done that (luckily that should be done once!), you can run:

qataki s:example u "my message"

to post "my message" on http://test-subdomain.status.net as @you. Of course, you can have a shell alias like:

alias mysub="qataki s:example"

and then post your notices to http://test-subdomain.status.net this way:

mysub u "hello world"

Multiple accounts

If you have multiple accounts, you can configure Qataki in order to allow you to use one of these accounts with, e.g., qataki n:YOU (where YOU is an alternate account; in this example an account on Identi.ca). You don't have to use the n:YOU option for your default account. Read the note about <NICK> in the help screen above.

Killfile

Are you tired of seeing again and again messages which contains a certain word/tag? Let's say that you don't really care about foobar: If you add foobar in .qataki/killfile, you won't see again those messages!

.qataki/killfile is a file which should contain a word/tag on each line, like: 

foo
bar
foobar
#qux

Themes

Optionally, the default look of Qataki's output can be changed. All you need is to specify the option opt_theme in the configuration file (by default $HOME/.qataki/qataki.conf) with a name of a file to be located in $conf_dir (by default $HOME/.qataki/) where colours (ANSI escaped) are set (the file can have the name and the extension you want, e.g., opt_theme=default.txt.

Colors are:

col_normal
Normal color. If you set any of the remaining colours, this needs to be set.
col_nick
Nicks of people you don't follow
col_follow
Nicks of people you follow
col_reply
Nicks of mentioned people (e.g., @user)
col_link
Links
col_hash
Hashtags
col_group
Groups

Some examples can be found in http://chr.tx0.org/qataki/themes/.

If you want to contribute a theme, contact me. A summary of escape sequences is available at ftp://sdf.org/pub/computers/vt100/color.pdf.

Tips

The script does one thing at a time. If you want to do crazy stuff, then you have to create a wrapper around qataki. Some examples below.

Update multiple accounts

For instance, let's say that you have accounts on Identi.ca, Twitter and http://micro.example.com. If you want to update your accounts with the same notice, you can create this script (let's call it up-all.sh): 

#!/bin/sh
for flag in i t s:mic "s:mic n:other" ; do
	qataki $flag u "$1"
done

(mic is an alias for http://micro.example.com and other is an alternate account on http://micro.example.com; see above). You can then make the script executable (chmod +x up-all.sh) and run it like:

./up-all.sh "My message!"

Real time updates

If you want qataki to check for new notices (from people you follow) every ten minutes (not real time, but probably sufficient), you can do it with this script (say follow.sh): 

#!/bin/sh
while true; do
     qataki f 1>/dev/null
     if [ "$?" -eq 0 ] ; then
         echo ; echo "Update: $(date)" ; echo ; qataki p
     fi
     sleep 600
done

Then, after making it executable, you can ./follow.sh and it will display notices when they become available.

Read context when displaying timelines

OK, say you are reading the statuses from people you follow and notice a {context} string in, say, the third one (it means that someone has replied to that notice). Do you really have to scroll down all the messages and then run qataki c 3? No way. You can simply type Ctrl-z (that is, the control key and z), then qataki c 3, and then go back typing fg.

More

You can contribute usage tips on the wiki.