# Console Jabber Client manual

### Jacek Konieczny

### Marcin Chojnowski

List of Tables

B.1. Global commands:
B.2. Screen commands:

## Introduction

Console Jabber Client (CJC) is simple Jabber client to run on a text terminal. It is far from being finished now, but it already has all basic functionality and is quite usable.

## Chapter 1. User interface

## Basic layout

When CJC is started the first time its screen consists of:

- Top status bar

- Main window with its status bar

- Bottom status bar

- Command line

This is the "plain" layout. Other layouts may be chosen by modifying the "layout" setting. Exact content of status bars is controlled by a theme.

## Windows and buffers

The part of the screen where most information is displayed is a window. One of windows is the active window. By default there is only one window so it is the active window. When multiple windows are available, the active one may be changed using Alt+Tab key or /next, /prev commands.

The content of a window is a buffer. Usually there are many buffers in CJC, but only one may be displayed in a window. Buffer may contain: status messages, a chat session, the roster, etc. Buffers may be switched using Alt+number key (or Esc number on terminals where Alt/Meta is not available or not working) or /nextbuf, /prevbuf commands. A list of buffers containing anything new is displayed in the bottom status bar.

## Commands

CJC is driven by commands. Commands are entered preceded with slash ('/'). There are global commands, like /quit, /connect, etc. and commands local to current buffer - e.g. /me is valid only in a chat window.

Command may require some arguments. Parameters may be optional (like reason for /quit), other are required (like user for /chat). Usually arguments must be quoted when they contain spaces or quotes, but some arguments don't need quoting and in fact cannot be quoted. Such argument is always the last argument for command and usually is some kind of message or description - like quit reason or chat message.

Examples of valid commands:

- `/quit`

- `/quit I must go`

- `/chat someone`

- `/chat user@domain anything`

- `/chat @domain`

Username arguments (like the first argument of /chat command) may be roster names or JIDs. Usernames which don't contain '@' are always searched in roster, so to use JID which doesn't contain node part one must precede it with '@'.

Custom commands may be defined as aliases for other commands using /alias. There are some built-in aliases for some commands - these cannot be changed with /alias and /unalias commands.

There is an online help available for CJC commands. /help without arguments displays all available commands and built-in aliases. When given a command name as argument /help displays its description.

## Settings

CJC is very customizable. Its behaviour is controlled by various settings, which may be modified with /set and /unset commands. /set without arguments displays all available settings with their values. /set with one argument displays value and description of named setting. /set with two arguments changes value of a setting.

Only two settings must be set to use CJC, these are: `jid` and `password`.

Examples of variable setting:

- `/set jid username@jabber.domain/CJC`

- `/set away_priority 0`

- `/set presence.auto_away_msg "I am gone"`

Please note, that values containing spaces or quotes must be quoted.

## Chapter 2. Using CJC

## Starting and exiting

### Starting

CJC may be started by entering just `cjc` on shell command line, but it can be given some arguments:

`cjc` [-c `file` ] [-t `file` ] [-l `file` ] [-L `file` ] [-P `file` ]

[-c `file` ] argument selects configuration file to use. If `file` contains slashes ('/') it is assumed to be in ~/.cjc/ directory. If you use default as config file name default.conf file will be searched by CJC.

[-t `file` ] selects theme to use (themes are searched in ~/.cjc/themes by default).

[-l `file` ] makes CJC write some debug logs to the file.

[-L `file` ] makes CJC append some debug logs to the file.

[-P `file` ] makes CJC write profiling statistics.

### Exiting

CJC may be left using /quit. The command will accept an optional `reason` argument, which will be sent to the server if connected.

Examples:

`/quit`

`/quit I must go`

## Connection

### Configuration

To connect to a jabber server you must first set the `jid` and the `password` settings. If your server differs from your JID's domain you should also set the `server` setting. When your server listens on nonstandard port number (other than 5222) you should set the `port` setting.

Example:

`/set jid me@my.server/Home`

`/set password "very secret"`

### Connecting

After configuring your account as described above you may connect to the server using /connect. After connection is established the presence is to "online" and the roster roster is retrieved.

Example:

`/connect`

### Disconnecting

To disconnect use the /disconnect command. Also the /quit command disconnect current connection. Both commands accept optional `reason` argument which will be sent to the server. Disconnection is not instant - it must take a while so the connection is closed cleanly and the reason is properly received by the server.

Example:

`/disconnect`

`/disconnect I must go`

## Roster

Roster is a list of contacts. It is stored on the server and received just after connecting.

### Roster buffer

Roster view is kept in a separate buffer - it is usually the buffer number 2, so you can look at it using Alt+2. Contacts in roster are divided into groups. Additionally to the groups defined in the roster CJC may display three special groups in its roster buffer:

- `me` - this group contains all active sessions of the current user including current CJC connection.
- `unknown` - this group contains users which presence is known although they are not in the roster.
- `unfiled` - this group contains users which doesn't belong to any roster group.

Each contact in roster buffer is displayed along with his presence information. Also the color of the entry depends of its presence.

By default all contacts are displayed, but this behaviour may be modified by changing the `roster.show` setting. Its value is one of the following: "all" (which is default and means all contacts), "available" (only those, who are currently available), "unavailable" (only those who are currently unavailable), "chat", "online", "away", "xa" (only those with named presence mode). Multiple values may also be given - separated by commas.

### Modifying roster

Users may be added to the roster using /add. The only required argument is user's JID. Group may be defined using [-group `group`] argument. The name of the new contact is defined by the last argument (not quoted).

Example - adds "friend@friendly.server" contact named "My Friend" to group "friends":

`/add -group friends friend@friendly.server My Friend`

Please note, that adding a contact to the roster doesn't mean subscription to its presence. Presence of the contact will not be known unless it is subscribed using /subscribe command.

Contacts may be removed using /remove command. The only (quoted) argument is user name or JID.

Example - both of the following commands remove contact added in the previous example:

`/remove friend@friendly.server`

`/remove "My Friend"`

Contact name may be changed using /rename command. The first argument is contact name or JID, the second (not quoted) is the new name.

Example - the friend is not a friend anymore:

`/rename "My Friend" My Enemy`

The list of groups user belongs to may also be changed - using /group command. This commands has two forms. The first argument is always a contact name or JID. In the first form the second argument is a new list of groups. In the second form it is list of group changes. Each of change is identified by group name preceded with "+" or "-" sign.

Example - the friend is not a friend anymore (cont). Both commands do the same:

`/group "My Enemy" enemies`

`/group "My Enemy" -friends +enemies`

## Presence

Presence is information about your current status for example: you're busy and don't want to be disturbed anymore, you're able to set your custom presence information that will be visible to the other users (as mentioned before). With presence change you can also give reason why you're for example busy.

### Changing presence information

Presence can be changed using commands: /away, /dnd or /busy, /xa, /chatready, . All of them take one argument and it's a reason of presence change. Getting back to online presence is possible with /back or /online

Usage examples:

You are smoking cigarette:

`/away I'm smoking ;)`

You're busy with your friend:

`/dnd My friend is here`

You've gone for longer period of time:

`/xa I've gone swimming`

After you're ready to chat again you can type:

`/online I'm ready to chat` . /back also gives ability to go online.

### Presence information control

There are also commands that allows supervise our and others presence information. It is:

/sunscribe, /unsubscribe, /cancel

As described before /subscribe is needed to get users in roster presence information and vice versa /unsubscribe removes such information. Another important command /cancel removes authorization for users.

### Auto-away

It's very nice feature that sets predefined presence mode and reason information after some period of idle time. It can be defined directly in cjc or or manualy by editing configuration file. Defaults are: AWAY after 5 minutes and Extended Away after 15 minutes of user inactivity.

It easy to change this defaults using /set command.

For example:

`/set presence.auto_away 3`

will set our presence to away after 3 minutes of inactivity. It is also possible to set reason of our automatic away. It can be done like that:

`/set presence.auto_away_msg "Walking around"`

This will set 'Walking around' description and it should be quoted as this command will take only one argument.

The same goes for eXtended Away. It's done by litte bit diffrent command:

`/set presence.auto_xa 10`

and changing description:

`/set presence.auto_xa.msg "I've gone for longer time"`

### Additional useful features

It's easy now to keep predefined presence description. It will be set if no description will be passed manualy or automatically to the options described above. It can be set with following command:

`/set presence.keep_description "Important exam tommorow!"`

This will cause that 'Important exam tomorrow!' will be set everytime we change presence without our own description.

## Chat

Just like in most other Instant Messaging systems there are two ways of contacting other users. The first one is chat mode. Chat is used to carry conversation for a while and after is started new windows will be created for each chat with new user. It allows instant communication between users.

It's easy to start chat:

/chat JID or /chat roster_nickname

For example:

`/chat friend@friend.org How are you?`

This will start new chat window and send How are you? message to user. More messages can be input in this newly created window. Our friends messages will apear in that window too.

## Messages

Using message mode is good idea for sending quick message to someone. It's not intended to make long conversation with messaging people.

It's also easy to send message:

/msg JID or /msg roster_nickname

For example:

`/msg friend@friend.org Call me at 8 p.m.`

This will send message asking for a call. New window will open with some information regarding our newly sent message.

## Appendix A. Keyboard reference

Windows switching:

Alt-TAB

Alt-*window_number*

## Appendix B. Command reference

Table B.1. Global commands:

Command | Description
--- | ---
/alias name command [arg...] | Defines an aliases for command. When the alias is used $1, $2, etc. are replaced with alias arguments.
/bind [function [[table] keyname]] | Without arguments - shows current keybindings otherwise binds given function to a key.

Table B.2. Screen commands:

Command | Description
--- | ---
/beep | Makes the terminal 'beep'
/move [oldnumber] number | Change buffer order
/next | Change active window to the next one

## Appendix C. Settings reference

(...)