| 1 | # clix - Command-line XMPP tool |
| 2 | |
| 3 | ## Description |
| 4 | Clix is a small utility to interact with an XMPP server. It can be |
| 5 | used to send messages, presence, and info queries to any XMPP address. |
| 6 | |
| 7 | ## Example |
| 8 | clix send --to=user@example.com "The kettle has now boiled" |
| 9 | |
| 10 | ## Usage |
| 11 | Syntax: clix COMMAND [OPTIONS] [...] |
| 12 | |
| 13 | Different commands accept different sets of options, but they all |
| 14 | follow some general conventions. The command must be the first |
| 15 | parameter, followed by a series of flags or options. Global options |
| 16 | include: |
| 17 | |
| 18 | --account=default |
| 19 | The account to use from the configuration file (default |
| 20 | is 'default') |
| 21 | |
| 22 | -c |
| 23 | --chatroom[=chatroom address] |
| 24 | Join a chatroom, if no address is specified then the value |
| 25 | of the --to parameter is used. |
| 26 | |
| 27 | --nick=nickname |
| 28 | The nickname to use if clix joins a chatroom, default "clix" |
| 29 | |
| 30 | -o |
| 31 | --presence |
| 32 | Send presence, that is - appear online to contacts. |
| 33 | |
| 34 | -p |
| 35 | --password=password |
| 36 | Set the password to use for authentication (overrides config) |
| 37 | |
| 38 | -r |
| 39 | --resource=resource |
| 40 | Set the resource to use (default is to let the server choose) |
| 41 | |
| 42 | -q |
| 43 | --quiet |
| 44 | Suppress informational messages |
| 45 | |
| 46 | -v |
| 47 | --verbose |
| 48 | Enables verbose logging of the XMPP connection |
| 49 | |
| 50 | When no command is specified, clix will print a list of the names |
| 51 | and descriptions of all built-in commands. |
| 52 | |
| 53 | ## Configuration |
| 54 | Clix looks for its config file at $XDG_CONFIG_HOME/.clixrc or |
| 55 | $XDG_CONFIG_HOME/.clix (XDG_CONFIG_HOME defaults to ~/.config) - it is |
| 56 | a simple 'ini' format, which looks like this: |
| 57 | |
| 58 | [default] |
| 59 | jid=user@example.com |
| 60 | password=mypassword |
| 61 | |
| 62 | [otheraccount] |
| 63 | jid=otheruser@example.org |
| 64 | password=theirpassword |
| 65 | |
| 66 | and so on. You can define as many accounts as you want, if no account |
| 67 | is called 'default' then the first account is the default. If there is |
| 68 | no [] header at the start of the file it is assumed to be [default]. |
| 69 | |
| 70 | ## Building and installing |
| 71 | Building clix is (by no accident) quite simple. It depends on Verse, |
| 72 | an XMPP client library for Lua. Verse in turn depends on several |
| 73 | libraries, all dependencies are listed here. |
| 74 | |
| 75 | Verse 2.0+: http://matthewwild.co.uk/projects/verse |
| 76 | At the time of writing Verse 2.x has not been released yet and |
| 77 | is available only from: http://code.matthewwild.co.uk/verse/ |
| 78 | |
| 79 | LuaExpat: http://www.keplerproject.org/luaexpat/ |
| 80 | Lua XML parser. Available in Debian as liblua5.1-expat0 |
| 81 | |
| 82 | LuaSocket: http://www.tecgraf.puc-rio.br/~diego/professional/luasocket/ |
| 83 | Lua networking library. Available in Debian as liblua5.1-socket2 |
| 84 | |
| 85 | Clix can be run directly from source if the above dependencies are |
| 86 | installed. To make life easier it can be installed to standard directories, |
| 87 | on most systems this means to copy clix.lua to /usr/bin/clix and the clix |
| 88 | directory to /usr/lib/lua/5.1/clix (on some non-Debian systems the 5.1 |
| 89 | directory isn't needed). |
| 90 | |
| 91 | Alternatively you can use Squish to compress all Clix's files into a single |
| 92 | executable. If you have Squish installed then simply type 'squish' in |
| 93 | clix's source directory to generate the compacted 'clix.bin' file. Squish |
| 94 | can be found at http://matthewwild.co.uk/projects/squish . |