README

# clix - Command-line XMPP tool

## Description
Clix is a small utility to interact with an XMPP server. It can be 
used to send messages, presence, and info queries to any XMPP address.

## Example
clix send --to=user@example.com "The kettle has now boiled"

## Usage
Syntax: clix COMMAND [OPTIONS] [...]

Different commands accept different sets of options, but they all
follow some general conventions. The command must be the first 
parameter, followed by a series of flags or options. Global options
include:

  --account=default
  	The account to use from the configuration file (default 
  	is 'default')
  
  -c
  --chatroom[=chatroom address]
  	Join a chatroom, if no address is specified then the value
  	of the --to parameter is used.
  
  --nick=nickname
  	The nickname to use if clix joins a chatroom, default "clix"
  
  -o
  --presence
  	Send presence, that is - appear online to contacts.
  
  -p
  --password=password
  	Set the password to use for authentication (overrides config)
  
  -r
  --resource=resource
  	Set the resource to use (default is to let the server choose)
  
  -q
  --quiet
  	Suppress informational messages
  
  -v
  --verbose
  	Enables verbose logging of the XMPP connection

When no command is specified, clix will print a list of the names
and descriptions of all built-in commands.

## Configuration
Clix looks for its config file at $HOME/.clix - it is a simple 'ini'
format, which looks like this:

	[default]
	jid=user@example.com
	password=mypassword
	
	[otheraccount]
	jid=otheruser@example.org
	password=theirpassword

and so on. You can define as many accounts as you want, if no account
is called 'default' then the first account is the default. If there is
no [] header at the start of the file it is assumed to be [default].

## Building and installing
Building clix is (by no accident) quite simple. It depends on Verse,
an XMPP client library for Lua. Verse in turn depends on several 
libraries, all dependencies are listed here.

  Verse 2.0+: http://matthewwild.co.uk/projects/verse
  	At the time of writing Verse 2.x has not been released yet and
  	is available only from: http://code.matthewwild.co.uk/verse/
  
  LuaExpat: http://www.keplerproject.org/luaexpat/
  	Lua XML parser. Available in Debian as liblua5.1-expat0
  	
  LuaSocket: http://www.tecgraf.puc-rio.br/~diego/professional/luasocket/
  	Lua networking library. Available in Debian as liblua5.1-socket2
  	
Clix can be run directly from source if the above dependencies are
installed. To make life easier it can be installed to standard directories,
on most systems this means to copy clix.lua to /usr/bin/clix and the clix
directory to /usr/lib/lua/5.1/clix (on some non-Debian systems the 5.1 
directory isn't needed).

Alternatively you can use Squish to compress all Clix's files into a single
executable. If you have Squish installed then simply type 'squish' in 
clix's source directory to generate the compacted 'clix.bin' file. Squish 
can be found at http://matthewwild.co.uk/projects/squish .