.\"     $Id$ -*- nroff -*-
.\" EN: $Id$
.TH MICQ 7 mICQ
.SH NAME
mICQ - interactive commands
.SH DESCRIPTION
This manual page describes the commands that can be used within micq.  This
page holds the same information as the online help, but more precise and longer.
.SH COMMANDS CONCERNING THE MICQ CLIENT
.TP
.BI verbose \ [verb]
Set verbosity of mICQ to
.IR verb ,
or show the current verbosity. The verbosity level is a set of flags:
.RS
.TP
.B 8
Show protocol errors.
.TP
.B 16
Show creation and deletion of packets.
.TP
.B 32
Show added and removed queue events.
.TP
.B 64
Show created and deleted connections.
.TP
.B 256
Show v6 packets and their data.
.TP
.B 4096
Show v7/v8 packets.
.TP
.B 8192
Show the hexdump of v7/v8 packets.
.TP
.B 16284
Save those packets to disc.
.TP
.B 65536
Show peer-to-peer packets.
.TP
.B 131072
Show the hexdump of peer-to-peer packets.
.TP
.B 262144
Save those packets to disc.
.TP
.B 2097152
Show peer-to-peer handshake.
.TP
.B 4194304
Show I/O connection setup.
.PP
However, any non-zero verbose level will cause more information to be printed,
and any level greater than 1 even more.
.RE
.TP
.B clear
Clear the screen.
.TP
.BI sound\ [on|off|event]
Toggle sound
.B on
or
.BR off ,
or call the
.B event
script for beeps. New syntax for 0.4.10.
.TP
.BI autoaway \ [timeout|on|off]
Set the timeout to
.IR timeout ,
or switch auto away
.I on
using the last used or default auto away time, or switch auto away
.I off
saving the current used auto away time. A timeout of 0 is equivalent to
.IR off .
If no argument is given, the current setting is displayed.
.TP
.BI auto \ [on|off]
Turn auto reply messages on or off. If neither on or off is given
the auto reply messages are displayed.
.TP
.BI auto \ status\ message
Change auto reply message for status
.I status
to
.IR message .
.TP
.BI alias \ [alias\ expansion]
Make a new alias named
.I alias
which is substituted with
.IR expansion .
If no arguments are given, all current aliases are listed. If the
string %s is present in
.IR expansion ,
it is replaced with the given arguments when the alias is invoked,
otherwise they will be appended. 
New for 0.4.10.
.TP
.BI unalias \ alias
Delete the alias named
.IR alias .
New for 0.4.10.
.TP
.BI alter \ command\ new
Make command initially or previously known as
.I command
from now on known as
.IR new .
This command is obsoleted by the
.B alias
command as of mICQ 0.4.10.
.TP
.BI trans \ [lang|nr]\ ...
Switch to the language 
.IR lang ,
given by iso code, or output translation string number
.IR nr .
To select the default language given by the environment
variables
.BR LANG ,
.B LC_ALL
and
.BR LC_MESSAGES ,
use
.BR ! ,
.B auto
or
.BR default .
To select no translation at all, use
.BR . ,
.B none
or
.BR unload .
To get debugging information, prefix it with
.BR debug .
To get funny messages, postfix it with
.BR @fun .
.sp
The files from ~/.micq/i18n/*.i18n take precedence over the global
ones, while the "funny" ones take precedence over the standard ones.
.sp
Actually you may specify as many arguments as you wish, e.g. to print
string number 117 in German and then switch back to default language,
use "trans de 117 default".
.TP
.B uptime
Show the time mICQ has been running, plus some statistics.
.TP
.BI set \ option\ value
Set option
.I option
to either
.I on
or
.IR off ,
or an
.I option
specific set of
.IR value s.
.I option
can be:
.RS
.TP
.BR hermit :
ignore all non-contacts,
.TP
.BR delbs :
interpret delete characters as backspace,
.TP
.BR funny :
use funny messages,
.TP
.BR log :
do logging,
.TP
.BR logonoff :
also log status changes,
.TP
.BR auto :
send auto-replies when you're e.g. away,
.TP
.BR uinprompt :
have the last nick in the prompt,
.TP
.BR autosave :
automatically save the micqrc,
.TP
.BR autofinger :
automatically finger new UINs,
.TP
.BR linebreak :
set the style for line-breaking messages to
.BR simple ,
to simply print the message after the nick and wrap,
.BR break ,
to add a line break before printing each incoming message,
.BR indent ,
to indent all lines of a message to the level after the nick, or
.BR smart ,
to add a line break only if the message wouldn't fit on the line;
.TP
.BR tabs :
set the style for tab-handling to
.BR simple ,
to tab through a list of last nick sent to and received from,
.BR cycle ,
to cycle through all online contacts, doing auto-completion,
or
.BR cycleall ,
to cycle through all (even offline) contacts, doing auto-completion;
.TP
.BR silent :
suppress some output :
.BR off ,
.BR on ,
to suppress status changes, or
.BR complete ,
to suppress status changes, logins and logoffs.
.PP
New options for 0.4.10.
.RE
.TP
.B save
Saves current settings in the configuration file, which is
.IR ~/.micq/micqrc ,
unless specified otherwise.
Beware, it will clobber any comments in this file.
.TP
.B q[uit]
.TP
.B exit
Quit mICQ.
Aliases quit and exit new for 0.4.10.
.SH COMMANDS CONCERNING MESSAGE SENDING
A
.I <contacts>
argument denotes a comma separated list of contacts, that is, of UINs and
nick names. If it is the last argument, the contacts may also be separated by spaces.
.TP
.BI msg \ <contacts>\ [message]
Send a message to all
.IR contacts .
Without
.I message
multi-line message mode is enabled.  To send the multi-line message, put
a period
.RB ( . )
on a line of its own.  To cancel the message, put a hash sign
.RB ( # )
on a line of its own.
.br
Outgoing and incoming messages are marked differently depending of the transport
used.
.B \(Fo\(Fo\(Fo
and
.B \(Fc\(Fc\(Fc
mark messages sent via a direct connection. If the SSL extension has been
compiled in and this direct connection has SSL established,
.B \(Fo%\(Fo
and
.B \(Fc%\(Fc
is used instead. If an outgoing message is not
acknowledged by the peer for some time, it is printed marked
.BR === .
.B \(Fo<<
and
.B >>\(Fc
mark icq8 (also called type-2) messages; if an outgoing message is not
acknowledged by the peer for some time, it is printed marked
.BR --= .
Lastly,
.B <<<
and
.B >>>
mark icq5 messages, which can be so called type-1, type-4 or offline
message. These kind of messages are not acknowledged.
Note that in locales that do not have the \(Fo and \(Fc characters,
{ and } are used instead)
.br
A message is first tried to be sent via a pre-existing direct connection; if
none is established, one is initiated in the background for further
messages. If no direct connection is open, or if the message is not
acknowledged after some time, the connection will be failed and the next
transport tried: sending as type-2 message. This step will be skipped if the
peer does not set the required capabilities to signal its ability to receive
them. If this is skipped, times out or returns an error, e.g. the peer has
gone offline in the time between, the message is sent as an ordinary type-4
message.
.br
If the peer signals its ability to accept them and support for them has not
been disabled at compile time, messages are sent UTF-8 encoded and
appropriately tagged. Otherwise, the message is sent encoded in the peer's
configured encoding, or, if unset, the default assumed remote encoding.
type-1, type-4 and offline messages can not be tagged with their encoding,
so successful transmission of 8bit characters relies on correct
configuration.
.TP
.BI a \ [message]
Send a message to the last person you sent a message to.  See
.B msg
for more details.
.TP
.BI r \ [message]
Reply to last message received. See
.B msg
for more details.
.TP
.BI url \ <contacts>\ url\ message
Send a
.I message
regarding an
.I url
to all
.IR contacts .
.TP
.BI sms \ [nick]\ [cell]\ message
Send an SMS message
.I message
to cell phone number
.IR cell ,
which looks like +<country code><number>,
or to the cell phone number of
.IR nick ,
which will be set to
.IR cell
if unset. You may not specify
.IR cell
if
.IR nick
already has a cell phone number given. Invalid cell phone numbers
will be removed from the
.IR nick 's
meta data.
.TP
.BI getauto \ [auto|away|na|dnd|occ|ffc]\ [contacts]
Requests auto message from
.IR contacts
for given status, where
.B away
is for away,
.B na
for not available,
.B dnd
for do not disturb,
.B occ
for occupied and
.B ffc
for free for chat. If
.B auto
or nothing is given, the auto message for the contacts
is fetched for their respective status. Contacts not in any of those
status will be skipped.
New for 0.4.10.
.TP
.BI auth \ [req|grant|deny|add]\ <contacts>
Grant or deny all
.I contacts
to add you to their list, request from all
.I contacts
to allow you to add them to your contact list, or tell
.I contacts
that you added them to your contact list.
.TP
.BI resend \ <contacts>
Resend the last message to more
.IR contacts .
.TP
.BI last \ [<contacts>]
Show the last message 
received from
.IR contact ,
or from everyone who already sent a message.
.TP
.B tabs 
Shows of a list of users you can tab through. This list is only used
in the
.B simple
tab style. See the
.I tabs
option of the
.B set
command.
.SH COMMANDS CONCERNING FINDING AND SEEING OTHER USERS
.TP
.BI rand \ number
Find a random user in interest group
.IR number .
.TP
.B s \ [<contacts>]
Show your current status, or of all given
.I contacts 
in detail, including all aliases.
.TP
.BR e ,\  w ,\  ee ,\  ww ,\  eg ,\  wg ,\  eeg ,\  wwg
List parts of your contact list. The following flags are displayed in the first column:
.RS
.TP
.B +
This entry is actually no real contact, but an alias of the preceding one. Only with
.BR ww .
.TP
.B #
This entry is not on your contact list, but the UIN was used at some time. Only with
.B w
and
.BR ww .
.TP
.B *
This contact will see your status even if you're invisible.
.TP
.B -
This contact won't see you at all.
.TP
.B ^
This contact is ignored: no messages, no status changes.
.PP
The
.B ww
and
.B ee
display another column for direct connection flags. If the first column would be empty,
it will be displayed in the first contact for all of those commands unless it's
.BR ^ .
.TP
.B %
The SSL extension is compiled in, and a direct connection using SSL to this
contact is established.
.B &
A direct connection to this contact is established.
.TP
.B \(ba
A direct connection to this contact has failed.
.TP
.B :
A direct connection is currently tried to be established.
.TP
.B ^
No direct connection opened, but IP address and port number are known.
.TP
.RE
.TP
.B e
List all people who are online in your contact list.
.TP
.B w
List all people in your contact list.
.TP
.B ee
List all people who are online in your contact list with more details.
.TP
.B ww
List all people in your contact list with more details. Also shows all aliases.
.TP
.B eg
List all people who are online in your contact list, sorted by contact groups. New for 0.4.10.
.TP
.B wg
List all people in your contact list, sorted by contact groups. New for 0.4.10.
.TP
.B eeg
List all people who are online in your contact list with more details, sorted by contact groups. New for 0.4.10.
.TP
.B wwg
List all people in your contact list with more details. Also shows all aliases, sorted by contact groups. New for 0.4.10.
.TP
.B ewide
List all people who are online in your contact list in a screen wide format.
.TP
.B wide
List all people who are in your contact list in a screen wide format.
.TP
.BI status \ [nickname]
Show the status of
.IR nickname .
This includes IP address, ICQ protocol version and connection type,
or list shortly UIN, nick, status and last online time for all contacts.
.sp
Note: This command is deprecated, use
.B s
or
.B ww
instead.
.TP
.BI f[inger] \ uin|nickname
.TP
.BI info \ uin|nickname
Show all white page info for
.IR uin|nickname .
.TP
.B i
List all the people on your ignore list.
.TP
.B search
.TP
.BI search \ em@il
.TP
.BI search \ nick
.TP
.BI search \ first\ last
Search for a user with
.I em@il
as their email address, with
.I nick
as their nick (which mustn't contain an @), or with
.I first
as their first and
.I last
as their last name. If no argument is given, ask for
nick name, first name, last name, email address and a whole bunch of other data
to search for.
.TP
.BI add[group] \ group\ [contacts]
Add all contacts in
.IR contacts
to the contact group
.IR group ,
which is created if it doesn't exist and the command is given as
.BI addgroup .
New for 0.4.10.
.br
Note: you need to
.B save
to make this persistent.
.TP
.BI add[alias] \ nickname\ alias
.TP
.BI add[alias] \ uin\ nickname
Add
.I uin
to your contact list as
.IR nickname ,
or add alias
.IR alias
for
.IR nickname .
New (addalias) for 0.4.10.
.br
Note: you need to
.B save
to make this persistent.
.TP
.BI rem[group] \ [all]\ group
.TP
.BI rem[group] \ group\ contacts
Remove all contacts in
.IR contacts
from the contact group
.IR group ,
or remove the contact group completely if
.B all
is given.
New for 0.4.10.
Note: you need to
.B save
to make this persistent.
.TP
.BI rem[alias] \ [all]\ contacts
Remove the aliases in
.IR contacts .
If any nick is the last alias for this contact, or if
.B all
is given, remove the contact completely.
.br
New (remalias) for 0.4.10.
Note: you need to
.B save
to make this persistent.
.TP
.BI togig \ contacts
Toggles whether
.IR contact 's
messages and status changes are ignored.
.TP
.BI toginv \ contacts
Toggles whether you will be hidden for
.IR contacts .
.TP
.BI togvis \ contacts
Toggles whether
.I contacts
can see you even if you are invisible.
.SH COMMANDS CONCERNING YOUR ICQ ACCOUNT
.TP
.BI reg \ password
Creates a new user account with password
.IR password .
.TP
.BI pass \ password
Changes your icq password to
.IR password . 
.br
Note: your password may not start with \('o (the byte 0xf3).
.br
Note: you need to
.B save
to make this persistent in case you save your password in your
.I ~/.micq/micqrc
file (see
.BR micqrc (7)),
or you will get a mismatched password
on your next login.
.TP
.BI change \ [number\ [message]]
Changes your status to
.IR number .
Without a number it lists some available modes. Optionally
set auto response for this status to
.IR message .
.TP
.B online
Change status to "online".
.TP
.BI away \ [message]
Change status to "away". Optionally set auto response for this status to
.IR message .
.TP
.BI na \ [message]
Change status to "not available". Optionally set auto response for this status to
.IR message .
.TP
.BI occ \ [message]
Change status to "occupied". Optionally set auto response for this status to
.IR message .
.TP
.BI dnd \ [message]
Change status to "do not disturb". Optionally set auto response for this status to
.IR message .
.TP
.BI ffc \ [message]
Change status to "free for chat". Optionally set auto response for this status to
.IR message .
.TP
.B inv
Change status to "invisible".
.TP
.B update
Updates your basic user information (email, nickname, etc.).
.TP
.B other
Updates other user information like age and sex.
.TP
.B about
Updates your about user information.
.TP
.BI setr \ [number]
Sets your random user group to
.IR number .
Without argument, lists possible interest groups.
.SH COMMANDS CONCERNING ADVANCED FEATURES
.TP
.BI meta \ [show|load|save|set|get|rget]\ <contacts>
Handle meta data of contacts. The following subcommands are known:
.RS
.TP
.B show
Shows the meta data of all
.I contacts
given.
.TP
.B load
Loads the meta data for all
.I contacts
given from disc and shows them.
.TP
.B save
Saves the meta data for all
.I contacts
given to disc.
.TP
.B set
Uploads your meta data to the server.
.TP
.B get
Gets the meta data for all
.I contacts
from the server and shows them.
.TP
.B getr
Gets the meta data for the contact the last message was received
from from the server and shows it.
.PP
New for 0.4.10.
.RE
.TP
.BI file \ [...]
Alias for
.BR peer\ file .
New for 0.4.10.
.TP
.BI accept \ [...]
Alias for
.BR peer\ accept .
New for 0.4.10.4.
.TP
.BI peer \ command\ arguments
Handle direct (peer to peer) connections.
.RS
.TP
.B open <contact>...
Open a peer to peer connection over TCP to these users.
.TP
.B close <contact>...
Close and reset a peer to peer connection to these users.
.TP
.B off <contact>...
Switch off trying to establish such a connection for sending
messages until it is explicitly opened or reset.
.TP
.BI file <contact> \ <file>\ <description>
Send file
.I file
with description
.IR description .
.TP
.BI files <contact> \ [<file>\ <as>]...\ [<description>]
Send arbitrarely many files to a contact. For each a pair of 
of the file's physical name
.I file
and the name
.IR as
to be presented to the peer needs to be given.
If
.IR as
is
.RB ' / ',
the file name without the path is sent, and if it is
.RB ' . '
the same name is sent.
.TP
.BR accept \ [<contact>]\ [<id>]
Accept an incoming file request from
.IR contact
with the given ID
.IR id .
If there is only one pending incoming file request, the
.IR contact \ and\  id
arguments may be omitted, otherwise it is undefined which file request
is answered when several match.
.TP
.BR deny \ [<contact>]\ [<id>]\ [<reason>]
Deny an incoming file request from
.IR contact
with the given ID
.IR id
with the reason
.IR reason .
.TP
.BR ssl \ <contact>...
Request SSL encryption from each
.IR contact .
.RE
.TP
.BI login \ [...]
Alias for
.BR conn\ login .
New for 0.4.10.4.
.TP
.BI conn \ [command\ nr]
List all connections, or operate
.I command
on connection
.IR nr .
.RS
.TP
.B open
Open the given, or the first server connection.
.TP
.B login
Open the given, or the first server connection.
.TP
.B close
Close the given connection. Temporary connections will get removed by this.
.TP
.B remove
Close and remove given (temporary) connection.
.TP
.B select
Select the given server connection as the current one.
.I nr
may be the connection number or the UIN used for the connection.
.RE
.TP
.BI contact \ [command]
Handle the server side contact list:
.RS
.TP
.B show
Download the server side contact list and just show it.
.TP
.B diff
Download the server side contact list and show only contacts (uin/nick pairs) that are not
in the local contact list.
.TP
.B import
Download the server side contact list and add all contacts to the local one.
.PP
There is no contact list upload yet.
.RE
.TP
.BI peek \ nick
Check whether
.I nick
is actually online or not. Abuses a bug in the ICQ protocol to figure this out;
no additional information except online or offline can be found out this way.
.SH COMMANDS CONCERNING TCL SCRIPTING
.TP
.BI tcl \ <command>
Run TCL command
.IR command .
Example: tcl puts "hello world"
.TP
.BI tclscript \ <file>
Run TCL script from file
.IR file .
.PP
The following TCL commands are introduced by mICQ that let you control mICQ
from within the TCL environment. To avoid namespace pollution with the
original TCL commands all mICQ TCL commands are a subcommand of the TCL
command 'micq'. This means for example 'micq receive R\(:udiger myproc' will
install a hook for message reception from R\(:udiger. All the following
commands must be preceded by 'micq'.
.TP
.BI receive \ <command>\ [<contact>]
Install hook for text message reception. 
.I command 
is the TCL command to be run upon message reception. 
.I contact
is an optional filter. If you don't specify a filter, the hook will catch
all incoming messages.  You can install as many reception hooks as you
want. If a hook exists for the given contact already, the existing hook is
updated and the procedure returns the former command.
.sp
Only simple text messages are processed. Use the event hook for reception
of other message types.
.sp
Whenever a message is received by mICQ, the given command will be run with
two arguments provided: the sender's UIN and the message text.
.sp
Note: This function is provided for convenience. Event hooks (described
below) can do the same job in a more generic way, but they have no filter
feature.
.TP
.BI unreceive \ [<contact>]
Remove installed hook with filter
.IR contact . 
If this hook existed it's command will be returned.
.TP
.BI event \ <command>
Install event hook. 
.I command
is the TCL command to be run upon events. If an event hook existed already
it's command will be returned.  In contrary to message hooks only a single
event hook can exist.  Consequent calls will override the old hook.
.sp
The command will be run with a variable number of arguments provided.  The
first argument always is the type of event encountered. The next arguments
depend on the event type. The following list explains all events. The bold
word is the event's type and the italics arguments describe the event's
details.
.RS
.TP
.BI status \ <uin>\ <status>
User changed status.
.TP
.BI message \ <uin>\ <text>
Message received.
.TP
.BI mail \ <uin>\ <content>
Incoming mail message.
.TP
.BI web \ <uin>\ <url>
URL message.
.TP
.BI file_request \ <uin>\ <filename>\ <size>\ sequence
Incoming file transmission request.
.TP
.BI contactlistadded \ <uin>
Someone added you to his contact list.
.TP
.BI authorization \ <uin>\  \fR{\fPrequest\fR,\fPrefused\fR,\fPgranted\fR}\fP
Authorization status.
.TP
.BI ssl \ <uin> \ <status> \ [<reason>]
SSL encryption established or failed with
.IR uin .
.I status
is
.B ok
or
.BR failed .
.I reason
can be:
.RS
.TP
.BI precondition 
SSL already failed formerly. So don't retry.
.TP
.BI init
SSL library init failure.
.TP
.BI key
SSL key setup failure.
.TP
.BI incapable
Peer sent "SSL not supported" resonse.
.TP
.BI handshake
SSL handshake failure.
.RE
.RE
.TP
.BI ssl \ <uin>\  \fR{\fPcandidate\fR,\fPno_candidate\fR}\fP
Indicates whether
.I uin
is a SSL capable candidate.
.TP
.BI unevent
Uninstall event hook. Returns command of former hook.
.TP
.BI hooks
Returns list of all installed hooks. Every list element is a hook and
consists of a list of two elements: the filter and the command.
.TP
.BI exec \ <command>
Run a mICQ command and returns its output as a single string. ANSI escape
sequences will be removed.
.TP
.BI nick \ <uin>
Lookup nick from given UIN if it is already known.
Hint: use 'exec finger' for UINs not in your contact list.
.TP
.BI help
Gives small summary of all available mICQ specific TCL commands.
.PP
These TCL variables are defined. You can overwrite them but you will lose the original values:
.TP
.BI micq_version
mICQ version string
.TP
.BI micq_basedir 
Base directory (same as mICQ's \-b switch)
.TP
.BI micq_uin
List of your own UINs
.PP
.nf
.ta 4n 19n 31n
Simple example of an event hook:

# start of tcl script
proc we_have_an_event {type args} {
    puts "type='$type' args=[join $args {,}]"
    # take further actions...
}
# install hook in main context
micq event we_have_an_event
# end of tcl script
.ta
.fi
.SH SEE ALSO
.BR micq (1),
.BR micqrc (5)
.SH AUTHOR
This man page was created by James Morrison
.I <ja2morrison@student.math.uwaterloo.ca>
for a reference to all interactive commands in 
.BR mICQ .