Clisk 2.5.1 User's Guide

General Information

This page is laid out for easy navigation via JAWS:

Other screen readers should provide similar navigation commands.

This document explains how to install and use Clisk, the Skype Command-Line Interface for Skype, on Windows and MacOS platforms. The document is laid out such that major sections are level 2 headings and subsections are level 3 or higher headings. JAWS users can thus navigate quickly among sections with the h command and by typing heading level numbers. Other screen readers should provide similar shortcuts.

This utility was named Skctl, the Skype Controller, before version 2.0.0.

Table of Contents

What Is Clisk?

Clisk, which stands for Command-Line Interface for Skype, is a command-line-based tool for working with Skype. Its initial goal was to provide person-specific AutoAnswer functionality, but it has since grown far beyond this initial purpose. It now provides

System Requirements

Clisk is designed to work under any operating system that can run both Skype and Python 2.5, 2.6, or 2.7. To date, only Windows and MacOS platforms have been tested, though Clisk should also work on Linux at least.

System requirements for Windows:

System requirements for MacOS:

Installing Clisk

To install Clisk on Windows or Mac platforms:

Clisk Usage

To launch Clisk on Windows, simply run A console (text) screen will appear. The first time you run Clisk, you will see a "pending authorization" message. Skype should ask you to authorize Clisk. Do so in order to make Skype allow Clisk to work properly.

If you are running Cygwin on Windows and want to run Clisk inside a Cygwin shell without having it create a separate window, launch Clisk by running clisk_cygwin. Beware, however, that doing this will cause Clisk to run without readline support, meaning that you won't be able to use Up and Down arrows to scroll through previously typed commands.

On a Mac, launch Clisk by running clisk_mac. This will make sure to run Clisk in 32-bit Python and will force use of the Python that comes with MacOS even if there is also a Python port present (unless the port has been set up to replace the built-in Python). Clisk_mac can be launched either from Terminal or from the Finder, in which case a Terminal window will open with Clisk running in it.

To run Clisk on Linux or any other similar variant, run clisk_linux. Note that the Clisk author has not managed to test this configuration but expects it to work.

When Clisk launches, a series of messages will appear, followed by a "Clisk>" prompt. Events such as reattachment, incoming text chats and calls, etc., will sometimes move the cursor off of the line containing the "Clisk>" prompt. To get a new "Clisk>" prompt at any time, just press Enter in the Clisk window.

Clisk may be closed at any time by typing q and pressing Enter at a "Clisk>" prompt. This is the preferred method of closing Clisk, rather than using OS-specific methods like Alt+F4 on Windows, so that Clisk can properly shut down its Skype connection and clean up its workspace.

To get a brief synopsis of what can be done at the "Clisk>" prompt, type help or just ? and press Enter. To get help on a specific Clisk command, type help or ? followed by the command. The built-in help is sometimes rather terse in order to fit information about Clisk or a command onto a single screen. The following subsections of this document provide detailed information on how to use each feature of Clisk.

Basic Command Syntax

Most Clisk commands consist of a command keyword and sometimes one or more parameters, separated by spaces. The parameters vary from one command keyword to another. Each full command is entered on a single line and followed by Enter.

Many Clisk commands require you to specify one or more users to which the command should refer. In many cases, you can indicate a user by typing any of the following:

If Clisk is uncertain which user you want, it will prompt you with a list of possibilities and let you choose the right user. See The User Selection System section for details on the user selection system. Similar rules apply for names of chats and even the commands themselves. For example, if you type
ca ec,bill
Clisk will first ask you to indicate whether you wanted the call command or the calls command, then depending on what users are available, it may ask you to clarify which user matching "ec" you want, and finally which user matching "bill" you want. For commands like hangup, hold, and resume that work only with existing calls, similar rules apply, but only the Skype IDs and names of call participants are considered. User name matching, chat name matching, etc., will only work on commands that are part of Clisk itself though, not on raw Skype API commands. Raw Skype API commands will be indicated as such in this Guide.

Clisk command lines fall into the following categories:

Clisk commands
Commands implemented directly by Clisk itself; for example, aa for AutoActions and transfer for transferring calls. Commands in this category may be abbreviated as long as the abbreviation remains unambiguous. For example, ha and ho work for hangup and hold, respectively, but h is invalid because it could mean either of those. (As mentioned earlier though, Clisk will help you in this case by prompting you to pick the command you meant.)
Skype API commands
Raw Skype API text commands that are sent by Clisk directly to Skype for processing. An example is
set mute on
which mutes the microphone if a call is active. The Skype API documentation can be found on the Skype Developer Zone web site and is kept up to date with changes in the API as they happen. Most any Skype API command can be sent directly through Clisk just by typing it and pressing Enter. Some of the Clisk commands are in fact mere shortcuts or convenience wrappers for longer raw Skype API commands.
Skype4Py object references (advanced)
Any property or method of the Main Skype4Py Skype object may be referenced by placing a dot (.) in front of it. An example line of this sort is
which will start playing the most recent unplayed voicemail. (If you have no unplayed voicemails, the above command will produce an error message like, "IndexError: list index out of range.") (See the vmPlay command though for a more friendly way of playing voicemails.) Use of this Clisk feature requires knowledge of the Skype4Py object structure as well as some knowledge of Python syntax. Skype4Py documentation can be found on the Skype Developer Zone web site.
Direct Python statement and expression evaluation (advanced)
Any valid Python statement or expression may be entered into Clisk for immediate execution by preceding it with an exclamation mark (!). For example,
will show the number of unplayed voicemails you have. In a Python entry of this sort, the main Skype4Py object is called skype (all in lower case). You can create variables, structures, functions, etc. using this feature, and they will remain available until you close and restart Clisk. Use of this direct Python entry feature of course requires knowledge of the Python programming language as well as knowledge of the Skype4Py object structure in most cases.

This document will describe the available Clisk commands (the first category above) in detail but will provide only limited information on the capabilities unleashed by the other command categories, as these require knowledge of environments not managed by Clisk. The following subsections cover specific commands in detail.

Using AutoActions (Including AutoAnswer)

AutoActions are actions assigned to happen as automatic responses for specific Skype contacts. The most common example is an AutoAnswer, which makes Skype automatically answer an incoming call from a particular contact. AutoActions are managed by assigning special action flags to specific Skype contacts.

Note that AutoActions are stored in a file specific to the active Skype account, which means that each Skype account has its own AutoAction list. See the Clisk Option Storage section for details.

The command keyword for AutoAction management is aa. Typing aa by itself and pressing Enter will list the AutoAction assignments currently in effect. If you have not made any such assignments yet, you will just get another "Clisk>" prompt. If you type aa, a space, and a Skype ID and then press Enter, you will see the AutoAction flags assigned to that contact. You don't have to use actual Skype IDs in current versions of Clisk; see the User Selection System section for details. Using a dot (.) in place of an ID will show the flags assigned to the currently selected contact in Skype itself.

To check or modify the set of AutoAction flags assigned to a contact, enter a command like one of the following examples:

aa bob a or aa bob +a
Grant the a flag to the user matching "bob." This will make Clisk auto-answer calls from Bob. As of Clisk 2.2.0, this will not clear any other flags assigned to Bob, even if you do not include the plus sign.
aa bob =a (version 2.2.0 and later)
Set the contact's AutoAction flags to exactly those specified. This syntax is new in Clisk 2.2.0 and works like the first example above, without the plus sign, in older Clisk versions.
aa bob -as
Remove specific flags while leaving any others unchanged. This example removes Bob's AutoAnswer and ?stat permissions.
aa Bob - (version 1.2.6 and later)
Remove all AutoAction flags for this contact.
aa Bob
Just verify which flags are assigned to a contact. Whereas aa by itself lists all AutoAction assignments for all contacts with any, this example would list the flags for just Bob. No changes to flags are made by this command, but it is a good way to verify that what you intend is in fact correctly set up for this contact.
aa . a
Assign the AutoAnswer flag to the contact last selected in Skype itself. Warning: The last selected contact in Windows Skype 4 is the last one displayed, not necessarily the last one focused with arrow keys.

There is support starting in version 1.2.6 for a set of default flags granted to all users. To set this up, use an asterisk (*) in place of the Skype user ID:

aa * s
grants the "s" flag (see below) to all contacts, regardless of whether they are in your contact list. When you request to see a specific user's AutoAction flags and the default flags add permissions to that user, the added default flags will be separated in the output from the flags specifically granted to that user by a plus sign (+). For example, if you type "aa bob" and get an answer of "a+s," that means Bob only has an "a" flag but gets an "s" flag as well because "*" has an "s" flag.

For Clisk users that assign many autoAction flags, there is an AASum command that prints assignments organized by flag rather than by user. This tends to produce a more compact listing of assignments, and one much better suited to answering questions like, "Who did I give J flags to?"

The following AutoAction flags are currently available:

a, for AutoAnswer
Answer a call from this contact immediately and automatically when the contact calls. The call will be answered regardless of your current online status. In particular, it will be answered if you are online, away, not available, in Do Not Disturb, or invisible. (If you are actually offline, the contact will be unable to call you in the first place.) Only assign this flag to contacts whom you don't mind answering at any possible time they may call. Callers with this flag will not be answered if you are in a call or have a call on hold.
j, for AutoJoin (version 1.2.5 and later)
Similar to a, but if there is already an active call, an incoming call from this contact will automatically be joined to the active call to create a conference. Starting in version 1.2.7, the call will be answered even if there is not an active call but a call is on hold. The AutoAnswer flag will only answer calls if no calls already exist at all.

The AutoJoin feature is intended for the creation of small Skype-based conference bridges, where people may call one Skype account to hook up with others as a group. Warning: Misuse of this flag could have a number of unpleasant social and/or legal consequences, for which the Skctl/Clisk author will not be held responsible. If you use this flag, be sure that not only the people with the flag but also anyone else that might call this Skype account are ok with conferences being formed without warning. See also the Advanced AutoAction Flags section for ways to control autoJoin and autoAnswer behavior more precisely starting in Clisk 2.2.0.

c, for AutoCallback
Automatically redial this contact on call termination.

Warning: This flag should only be assigned to contacts that are ok with you redialing them persistently. It should also only be used by one participant in the call, not both, or strange results may occur. Misuse of this flag may be regarded legally as harassment and may subject the abuser to civil and/or criminal penalties. The Skctl/Clisk author will not be held responsible for how this flag is used.

If you assign the AutoCall flag to a contact, your Skype will redial that contact 10 seconds (or 30 seconds before Clisk 2.0.0) after

  • The call drops, either from Internet connectivity problems at either end or by one of you hanging up, or
  • A redial attempt results in a Call Forward attempt or a transfer to voicemail. In this case, the call will not actually forward or go to voicemail. Instead, the current call will be dropped, and a new call will be attempted.
  • A call that is actually rejected or refused by the contact should not be redialed, but it still may happen.
  • Unfortunately, due to the way the Skype protocol works, calls that ring for a while but do not attempt to forward or go to voicemail may also not be redialed at this time. In effect, this means that AutoCall is not useful for redialing contacts that did not purchase voicemail and can't forward calls to a phone line.
  • There is currently no guarantee that calls hung up deliberately by the receiving party will not be redialed if this flag is in effect.
Because of the above issues, testing prior to regular use of this flag is strongly encouraged, as is careful agreement with the receiving party.
m, for AutoMute
Automatically mutes the call on outbound connect. This is probably only useful if, for example, you are using Skype as a remote baby monitor, where the monitor machine grants an a flag for your calling machine. In this case, when you call the monitor machine, your machine's mic could produce noise in the baby's room. Setting an AutoMute flag on the calling machine for the monitor machine's Skype ID would prevent this by muting the calling machine's mic immediately so as not to wake the baby. Another example use of this arrangement is a poor-man's security system, wherein you have your home Skype auto-answer calls from where you are but without making noise in the house, so you can hear if all is well.
r, for reverse call
Similar to a, but instead of automatically answering a call, Clisk will ignore the call and call the caller back a few seconds later. This is intended for situations where a friend is calling your Skype from a telephone but does not wish to incur charges. The user would dial your SkypeIn number, let it ring once or twice, then hang up and wait for the callback. The r flag combines meaningfully with j and numeric autoAnswer priority codes (see Priority AutoAnswer Flags) as well. For example, setting both r and 1 on a user will cause the call return to occur even if this requires a current call to be put on hold first. Assigning both r and j to a user will cause the callback to join the user to any current call, similar to what a plain j would do to an incoming call. This is an experimental feature and is subject to removal if it causes problems.
s, for stat
Allow the contact to send you a special chat line consisting of just the word "stat" preceded by a question mark and no spaces ("?stat") to find out
  • How many active (in progress) calls you have,
  • How many inactive (generally held) calls you have, and
  • What this contact's AutoAction flags are.
The ?stat command will not reveal the identities of any parties connected to you; it will just provide the numbers of active and held calls. (See the l flag below for a way to get a list of calls.. An example response is
Calls on MOPED: 1 in progress, 1 locally held. Your AutoAction flags are "as."
where "MOPED" would actually be replaced with your machine name. The above example output would inform the contact that you are currently talking to one person or conference and have one call on hold. "as" means this contact is allowed to send ?stat commands and be automatically answered on calling you. (Trivia side note: "MOPED," which stands for "My Own Portable Electronic Device," was the machine name of the Clisk author's laptop at the time this section was written, the name having been prompted by all his flying from site to site and hearing the flight attendants say, "Please turn off all portable electronic devices," more often than he heard himself called to dinner.)
l, for long stat, or list of calls
Similar to s but makes the user's ?stat command return a full list of calls, rather than the briefer output just described for s. The output for ?stat for a user with the l flag is mostly the same as the output for the local calls command, but with the following exceptions:
  • Phone numbers in a conference are not shown, so the ?stat command will not reveal phone numbers without their owners' permission. The actual phone number is replaced by the words "phone number."
  • Skype IDs are shown unconditionally, unlike for the local calls command, which only shows Skype IDs when their name association has changed since last display. This also helps when the user answering the ?stat command has renamed a user in Skype.
  • The ?stat command adds a line identifying the asking user's AutoAction flags on the responding system. The w flag is not shown however.
w, for watch
Watch for and report changes in this user's online status and profile. Normally, Clisk reports only authorization requests and authorization status changes for users. This flag makes Clisk report online status changes and changes in profile fields. Thus, you can monitor specific users to see when they go offline, away, out of Do Not Disturb, etc., and to catch when they change mood text, full name, About box contents, etc. Note that
aa * w
is permitted and will cause all such changes for all users to be reported. Depending on the number and habits of people in your contact list, this could generate quite a lot of output. Also note that the w flag is not reported to users who send the ?stat command. This is by design, since the w flag does not actually change anything for a user to whom it is assigned.

There are more autoAction flags available than described here; specifically, 1 through 9 for autoAnswer priorities, and x for exclusive calls that may not be joined by people with a j flag. See the Advanced AutoAction Flags section for further details on these.

Making and Listing Calls

Clisk includes commands for making and listing calls:

Call a contact or phone number.
call echo123
would call the Echo123 testing service.
call .
would call the last-selected contact in Skype.
Call +17035551212
would call a phone number in the US (Virginia, to be more precise).
Call (703) 555-1212
calls the same number, because Clisk reformats the given number into the form given in the previous example. This makes it easier to paste phone numbers into the Clisk window for dialing.

You can also create a conference with this command by including multiple contact names and/or phone numbers on the command line, separated by commas (,):

call echo123, +17035551212
would conference the above two contacts into one call.
List active calls. Calls are shown in a table with columns for Skype ID(s) of call participants, call direction (in or out) and status, video status, duration, and call ID (for use in raw Skype API commands). In Clisk/Skctl versions prior to 1.2.4, video status is shown as part of the Status column rather than in its own column. For conferences, the call ID is prefixed with "C" and the conference ID for the call starting in version 1.2.4. The Duration shown is in mm:ss format, that is, minutes and seconds; so, for example, a call lasting for three hours 15 minutes 20 seconds will show a duration of 195:20. Starting in version 1.2.4, the Skype IDs column will show who the call was transferred by and/or to if applicable. Starting in Clisk 2.0.0, a conference hosted by someone else will show as a line for the conference itself plus a line for each member in the conference. These secondary lines are indented under the conference header and show each user's name and call direction and status. Call direction in this case is from the perspective of the conference host; that is, a call showing "out" under a conference was formed by the conference host calling that person, and a call showing "in" was received by the conference host from that person.
Allows sending of voicemail without actually calling a contact's Skype first. Specify the Skype contact name or partial name after the command. This command may not work on all Skype versions and operating systems.
mc and mcc
Show missed calls and, for mcc, clear them from the missed call list at the same time. Calls are shown most recent first. You can add a number to these commands to limit the display and clearing to that many calls; for example, mcc10 will show and clear the latest 10 missed calls. If no number is given, 20 is assumed. Calls are shown with callee name and start time.

Warning: This command may not work as expected on Windows, where some Skype versions always return an empty list of missed calls.

Dial touch tone (DTMF) digits into the current call. This can be useful for controlling answering machines, voicemail systems, and automated call attendants.
dial 1234#
will dial the digits 1, 2, 3, 4, and the number sign key.

Managing Existing Calls

Besides the above commands for creating calls, Clisk includes the following support for managing existing calls. Most of these commands will operate by default on the currently active call but can be made to act on a different call by specifying the appropriate Skype ID or partial Skype ID associated with that call. Starting in Clisk 2.2.0, you can select a call just by typing something that uniquely matches within a call participant's Skype ID or name. If Clisk finds multiple matches, you will be asked to select which call you meant.

hangup or ha
Hang up the active call or another call.
ha echo
will hang up on Echo123, assuming there are no other calls with participants whose Skype ID or name contains "echo." Warning: If you are in one call and another call is ringing, hangup will hang up the active call, not the incoming call. To reject the incoming call, use the reject command described below.
hold or ho
Put the current call or another call on hold. If there is no active call or you need to hold a specific call, include a Skype ID or partial name after the command to indicate which call to place on hold.
resume or res
Resume a call. If there are no active calls but one is on hold, this command will resume that call. If there is one active call and one held call, this command will toggle between the two calls. To handle more complex situations, include a Skype ID or partial name after the command to indicate which call is to be resumed. In any case, if there is an active call and you request to resume a different one, the active call will first be placed on hold so the requested call can be resumed.
answer or ans, and reject or rej
Answer or reject an incoming call. In complex situations such as when multiple calls are ringing at once, specify a Skype ID or partial name after the command to indicate which call to answer or reject. If there is an active call when you issue the answer command, it will be placed on hold so the new call can be answered. For how to add an incoming call to another call to create or enhance a conference, see the join command.
join or jo (version 1.2.4 and later)
Join an incoming call to the currently active call to create a conference. In complex situations such as when multiple calls are ringing at once, specify a Skype ID or partial name after the command before the recipient or recipients to indicate which call to pick up and join into the current call.

Note: In the current Clisk implementation, at least under Windows, a Missed Call notification for the incoming call, and a corresponding Hangup sound, may be falsely generated when this command is used to pick up and join a call. This may be fixed in a future Clisk release but is caused by apparent limitations in the Skype API. Also, conferences formed via the Clisk join command will have the look and feel of Windows Skype 3.x conferences even under Windows Skype 4.x. See the Clisk Conference Structure section for details.

addCall (version 1.2.7 and later)
Make an outgoing call and add it to the current call or conference. Specify one or more user IDs or partial names, separated by commas, after this command to indicate who to call. If you have purchased the ability to dial phone numbers (SkypeOut), you may call phone numbers into a conference with this command as well. If you specify a user or number that is already connected but not in the current call or conference, that call will simply be joined to the current call or conference, and unheld if it is on hold locally.. Conferences formed via the Clisk addCall command will have the look and feel of Windows Skype 3.x conferences even under Windows Skype 4.x. See the Clisk Conference Structure section for details.
transfer or tr (version 1.2.4 and later)
Transfer a call to another party. Specify one or more user IDs, separated by commas, after this command to indicate where to send the call. If more than one recipient is given, the call will transfer to the first recipient that answers. Note that this will not create a conference; this is just a way to allow any one of several people to take the call.

By default, the call to be transferred is the incoming call if there is exactly one call ringing. This is true even if there is also an active call (one that is in progress, not held). Starting in version 1.2.7, if there are no incoming calls but there is an active (not held) call, the active call is transferred. In complex situations such as when multiple calls are ringing at once, specify a Skype ID or partial name after the command before the recipient or recipients to indicate which call to transfer. Note that there is not a comma between this optional call identifier and the recipient or recipients of the transfer.

tr echo123
will transfer the currently incoming call (assuming there is one) to echo123. In version 1.2.7 and later, if there is an active call and no ringing calls, the current call would be transferred to echo123 here.
tr bob echo123
will transfer the incoming call from the user matching "bob" to echo123.
tr bob, echo123
will transfer the currently incoming call to Bob or echo123, whichever answers first. Note that the comma makes "Bob" refer to a destination here rather than a source call.
vidSend and vidRec
Start, stop, or check status of video send/receive in the current or a specified call. Specify "on," "off," or "check" after the command. If no arguments are included after the command, "check" is assumed. If you wish to apply the command to a non-current call, specify a Skype ID or partial name after on/off/check to indicate which call to use. Warning: The "check" version of this command is known not to work on some Mac Skype versions.
Indicate, for Skype-to-phone calls, when the call might be forced to end by Skype. Skype cuts off outbound Skype-to-phone calls after a four-hour duration. This does not apply to Skype-to-Skype calls or to calls from a phone into Skype; the cutoff only applies to calls made from Skype to a telephone number.

Managing Voicemails

Clisk 2.2.0 and later provides several commands for handling voicemail messages. vmPlay plays the voicemail to the current Skype output sound device. vmToCall plays the voicemail into the currently active call while also playing it locally. This provides a means of checking voicemail for one Skype account remotely from another. vmStop stops playing the currently playing voicemail, assuming Clisk was used to start playing it. vmDelete deletes the currently playing or last-played voicemail if Clisk was used to play it. vmCount shows the number of voicemails on your system and the number of them that remain unplayed. vmGreeting plays your outgoing voicemail greeting or, if a contact is indicated on the command line, the outgoing greeting for that contact. If the person has no greeting (even if the person is you), the default Skype outgoing voicemail greeting plays.

Warning: If you use vmDelete during or after the playing of your own outbound voicemail greeting, you will delete your greeting. This could be cool or annoying depending on what you had in mind at the time.

Note: Clisk versions older than 2.2.0 used different names for these commands and did not include a command for counting voicemails. The following list of aliases shows the old command and the new replacement and doubles as a block of text that users may paste once into current Clisk versions to re-enable the old commands if desired:

alias pvm vmPlay
alias pvmc vmToCall
alias svm vmStop
alias dvm vmDelete

If given without parameters, vmPlay and vmToCall play the oldest unplayed voicemail and mark it as played. Repeating one of these commands until Clisk says "No missed voicemails" is a quick way to catch up on voicemails and mark them all as played. The voicemail's duration in mm:ss format, sending Skype user ID, send time, and ID (for use with raw Skype API commands) are shown on screen as the voicemail begins playing.

You can play a specific voicemail by typing -1 after the command for the most recently received voicemail, -2 for the next most recent, etc. You can also play a specific voicemail by its ID by typing vmPlay followed by the ID of the voicemail. The command vmPlay 0 repeats the last-played voicemail, restarting it first if it is playing already.

Managing Contacts

Clisk provides several commands for managing Skype contacts:

List contacts by status. With no arguments, this command lists separately the contacts that are online, in Skype Me mode, away, not available, and in do-not-disturb mode - in short, all statuses that represent actually being logged into Skype. To get a list of contacts with only a particular status, specify the status (or part of it) after the command. For example,
co a
lists the contacts that are away, while
co off
lists the contacts that are offline. At this writing, the following statuses are available:
The contact is online and likely active.
The contact is in Skype but has not been active for a while.
Not Available or NA
The contact has not been active for a long time. This status is not shown in Windows Skype 4.x but can still be seen in Clisk on Windows.
Do Not Disturb or DND)
The contact is online but has disabled sounds and popup windows and may not observe any incoming calls or messages.
Skype Me
The contact is inviting calls and will receive calls and chat messages regardless of his or her normal privacy settings. This status is not shown or available in Windows Skype 4.x but can still be seen in Clisk under Windows.
The contact is offline or invisible. Note that there is no way to distinguish between an offline contact and an invisible contact without sending a message or attempting a call. This is by Skype design and is not a bug.
The contact is actually a phone number, not a Skype account.
Lists the members of a chat or call. With no arguments, this command lists the members of the active call if there is one. To get the members of a specific call, indicate which call by specifying on the command line all or part of the callee's name or Skype ID. If the call is a conference or part of one, all participants in the conference will be listed. To get a list of members in a chat, specify all or part of the chat's name preceded by an at sign (@). For example,
mem @misc
will list the members in the chat whose name contains the string "misc." You can also specify a particular chat by its blob; see the msg command for more on chat blobs. Most users will probably not use blobs however.
Add a Skype user or SkypeOut phone number to your contact list. Adding SkypeOut numbers in this way is only properly supported starting in Clisk 2.2.0. For a Skype user, specify the user's Skype ID after the command. If this is a new user that has not asked for your contact details already, you will be prompted for a message to send that will introduce you to the contact you are adding. As in Skype itself, this message will be sent to the user with a request for contact details. Starting in Clisk 2.2.0, you can avoid this prompt if you like by including your introductory message after the ID you are adding on the command line. If the user already sent you a request for contact details, the prompt for introductory text will not appear; the addition will just be made immediately.

Starting in Clisk 2.2.0, you can also use the addUser command to add SkypeOut phone numbers to your contact list. To do this, specify the full phone number to add on the command line. Include the country code prefix, such as "+1" for US numbers. You can also include a name by which Skype should identify the number in your contact list. You can specify this on the command line after the phone number or just let Clisk ask you for it.

delUser Delete a Skype user or SkypeOut phone number from your contact list. Specify the user's Skype ID or the SkypeOut number after the command. The user or phone number will be removed from your contact list. If you are deleting a Skype user, the user will see that you are no longer sharing contact details.
block Block a user. Specify the user's Skype ID after the command. When you block a user, the user will see you as permanently offline but will not see you as not sharing contact details. Note that blocking a user in Clisk does not automatically delete the user as well. To do both, use both the block and delUser commands. This command can also block phone numbers.
Unblock a user. Specify the user's Skype ID after the command. Unblocking a user will again allow contact (text and voice) between you and the user and will let the user see your online status. Note that unblocking a user does not also re-add the user to your contact list if you deleted the user at some point. To add the user to your contact list, use the addUser command. This command can also unblock phone numbers.
List blocked users.
Handle incoming authorization requests from users who want you to share contact details with them. This command has several subcommands:
  • Type auth l to list all pending authorization requests, one per line.
  • Type auth by itself to handle the first pending authorization request.
  • Type auth followed by a number to handle a particular request; for example, auth 3 will handle the third request in the queue.
  • Type auth c to see how many authorization requests are pending, without actually retrieving the list of requests.

When you ask to handle an authorization request, using auth with or without a number after it, you will be shown the user's profile information (see the whoIs command below) and given a choice of whether to add the user, delete the request without adding the user, or skip the request so it will remain for later handling.

whoIs or profile
Show a user's profile information. Specify a string by which to identify the user of interest on the command line after this command. This command may also be used to perform searches for users not in your contact list. To search for a user in this way, include a slash (/) just before the user ID or search string, without any spaces between the two. The rules for Skype user searching are the same as within the Skype interface:
  • If the string contains an at (@) sign, it will match an email address, but only if the match is exact.
  • Otherwise, the Skype ID and Full Name fields of users are searched for the string.
There is no way to search for users by state, city, About text, or by other fields, because Skype itself does not provide this ability.

You can also retrieve profile information for a specific user, whether or not that user is in your contact list, by placing an exclamation point (!) immediately (with no intervening spaces) before the full exact Skype ID of the contact. Though likely not especially useful, specifying two exclamation points instead of one will cause Clisk to attempt a lookup of contact information without even first retrieveing it via a behind-the-scenes search. This effectively just reports what is in the local Skype's information cache for the contact.

Finally, you can use a plain period or dot (.) in place of a name to look up profile information for the contact that is currently highlighted in Skype itself. This may not work on all Skype versions and operating systems.

You can also set your online status and fields in your profile from Clisk using raw Skype API commands. Examples:

set userstatus away
set profile mood_text happy
set profile city Arlington
set profile state
The last example above sets the state field in your profile to be blank.

Miscellaneous Commands

Clisk provides the following additional commands that don't fall into any particular category. Some of these commands are actually not provided by Clisk but by Skype's API language; these are mentioned here because they are particularly useful.

Print the Clisk version number, Skype version number, Skype API protocol version number, and Skype API wrapper version number in effect. This information also prints automatically once when Clisk starts. If you include a person's id or partial name after this command, Clisk will attempt to contact that person's machine (or machines) and print the same information for that person's Clisk rather than for your own. This requires the other person to be running a new enough Clisk at the time you invoke the command. When used in this way, the version command will also indicate if the other person has granted you any autoAction flags on that machine/Skype account.

Warning: Some Mac Skype versions do not properly handle Skype version number requests through the Skype API, which in turn prevents Clisk from obtaining this number accurately. In such a case, Clisk returns a default version number for the Skype version.

Change the Clisk prompt. This can be useful for people who control multiple Skypes on different machines using Clisk and something like ssh, so each Clisk can report a different name; for example, "Laptop Clisk." prompt with no parameters clears the prompt back to the Clisk default. Any text after the prompt becomes the new prompt. The trailing ">" symbol is included after the prompt you specify, so there is no need to include it yourself.
Get a quick indication of the events pending in Skype, much like was possible in Windows Skype 3.x. The result of this command currently indicates which of the following types of events exist:
  • Missed calls.
  • Unplayed voicemails.
  • Unread chat messages.
  • Unread SMS messages. (Skype currently can not accept incoming SMS messages though.)
  • Users waiting to be added to your contact list (authorization requests).
For each event type shown, the command or commands for working with that event type are also shown. This makes the events (or just ev) command a nice way to manage missed events of most types.
clear or cls
Clear the screen. This does not work on all operating systems.
message or msg
Send a message to a Skype contact. Message is actually a raw Skype API command. Current versions of the Skype API advise against use of this command, but it is very convenient for sending quick text messages to contacts from Clisk. Msg is an internal alias for message but with several enhancements that do not apply to message:
  • You can message a multi-person chat by typing part of the chat's name prefixed with an at sign (@):
    msg @hangout Hey everybody in here!
    will send "Hey everybody in here!" to the chat whose name contains "hangout."
  • You can also send a message to a chat by using its so-called "blob," which is a string starting with a number sign (#) that uniquely identifies the chat. Blobs can be obtained by typing search activechats (a raw Skype API command). This method of messaging is far less convenient than the at-sign method, but it is still useful when messaging a chat whose topic, and thus name, keeps changing, since the blob will not change. A useful trick is to form a temporary alias to send to a chat by its blob, so you have a short command to send messages to that chat that does not change when the chat topic changes.
  • You can send some Skype slash commands using msg and get the results, whereas message tends not to return the results of these commands:
    msg bob /help
    will run the /help command just as if you had typed it in the Skype chat window for Bob. Clisk will print the help text to the screen, though if you had typed
    message bob /help
    the help text would not appear in the Clisk window.
  • You can send a multiline message by leaving out the text to send after the recipient on the msg command line. In this case, you will then be prompted to enter each line of text to send, and to end the message with a line containing only a period (.). This is very handy for pasting multiline messages to people through Clisk.

To use this command, specify the Skype ID of the intended recipient after the command, followed by the text of what you want to send.

msg echo123 Hi, this is me!
would send "Hi, this is me!" to the echo123 test service.
msg . Hi, this is me!
would do the same but send to the contact last selected in Skype itself.
nc, for next chat message
Read and/or mark as read any or all unread chat messages. nc by itself shows and marks as read the oldest unread message. nc followed by a number shows and marks that many messages at once. nc 0 or nc all shows and marks all remaining unread messages at once. nc clear clears the list, marking all as read without showing the messages. nc count or just nc c shows how many unread messages remain without changing anything.

Starting in Clisk 2.2.0, you can add a chat name or partial name, prefixed with an at sign (@), to limit the nc command to a specific conversation. For example,

nc clear @eileen
will mark as read all unread messages in the chat whose name includes "Eileen." Clisk 2.2.0 and later also includes in the response to nc count the number of conversations with unread content, and a new nc list command lists them by name. Beware though that "unread content" can include calls and other non-text-chat material, so a result like "1 missed chat messages in 5 conversations" is possible.
List active file transfers. File transfers are shown in a table with columns for Type (incoming or outgoing), Skype ID of other end of transfer, Status/Progress including percent complete, estimated transfer speed in KBPS, and name of transferring file. Note that the Skype API does not allow other programs like Clisk to control file transfers (start or stop them, etc.), so this is all Clisk can do with them. Well, almost...
fsend (Clisk 2.2.0 and later).
Open a "Send File" dialog in Skype, prepopulating it with the user or users to send to, and possibly setting the folder from which to select a file to send. To specify users to send to, list them separated by commas (,). If you want to specify the folder to start in, rather than letting Skype choose this, follow the user list with a space and the folder name, such as (in MacOS) /Users/Bob/Downloads. This command will not start a file transfer but may make it easier or quicker for you to start one. This command may not work at all on Skype 5.0 and later.
Show the current online status of a contact (online, offline, DND, etc.). Also shows, for offline contacts, whether calling the contact would forward elsewhere or go to voicemail. Also shows the last online time for the contact. For an offline contact, this is the last time the contact was seen to be in Skype. For a contact who is currently in Skype, this should be the last time the contact's status was verified by your Skype. The last online time is shown relative to current time, e.g., "00:07:45 ago" (which means 0 hours, 7 minutes, 45 seconds ago). If the contact has posted a mood message, it is shown as well.
Show a contact's last online time. See the os command for a better description of what the time means. The time is shown in the localized long date/time format, which is generally set in the operating system.
lo bob
would show when the user matching "bob" was last known to be in Skype.
lo .
would show the last online time for the contact last selected in Skype.
mute, m, and get mute
Turn mic mute on/off if there is an active call, toggle mute status, or check mute status without changing it. mute and get mute are raw Skype API commands; m is provided by Clisk.
mute on
mute off
get mute
will, respectively, turn mute on, turn it off, toggle its current state reporting the result, and report the current state without changing it.
www and home
Go to any of several web pages related to Clisk and/or Skype. These commands work on Windows and MacOS. www with no arguments opens the Clisk home page in the default browser. Home does the same. The URL opened includes version information about the Skype, Skype4Py, Clisk, and OS versions running on the system so the Clisk author can keep track of what configurations to support. Other pages can be opened instead of the home page by including a key word after "www." on the line. Examples include the Clisk online manual (users guide), the Skype home page, and various Skype and Python pages. Type "help www" in Clisk for details.
Rebuild or clear the internal cache that is responsible for deciding when to show Skype IDs along with contact names. This command is never required but can be useful. Examples:
  • To get a quick list of connected contacts without the list being lengthened by Skype IDs on some lines:
    (As of Clisk 2.2.0 though, the contacts (coP) command will never show Skype IDs along with names.)
  • To get a list of active calls while making sure that all contact names show with their respective Skype IDS:
    cache clear
For Python users: A version of dir() that is more concise: Only spaces separate entries in the list of attributes, and attributes whose names begin with an underscore (_) are omitted. This command is meant only for advanced and exploratory users who want to learn more about Python and/or the Skype4Py object model.
log, log on, and log off (version 1.2.5 and later)
Check or change whether Skype activity logging is enabled. When enabled, the Skype activity log records in text form most of the activity in Clisk, including Skype events and typed Clisk commands and their responses.
sklog, sklog on, and sklog off (currently Mac only)
Check or change whether Skype debug logging is enabled. Debug logging is used to create log files for Skype bug reports. After sklog on or sklog off, Skype may have to be restarted for the change to take effect. Starting in version 1.2.6, Clisk will print a notification of this.
errtrace (version 1.2.6 and later)
Print a brief trace for the most recent error if there was one. The trace only includes file names (no paths) and line numbers. The last file name and line number indicates where the error occurred, and entries before that indicate the chain of calls that led to the error.

Creating and Managing Command Aliases

Starting in version 1.2.5, Clisk provides a command for creating and managing aliases. An alias is a word that translates into all or the first part of a command. The following examples show how this works.

alias cl clear
Makes cl do the same as clear from now on.
clears the screen.
alias mse message echo123
Makes mse an easy way to send echo123 a message. Aliases of this sort can be created as needed to speed writing to specific people.
mse Hello!
sends echo123 a "Hello!" message.
lists all aliases defined with their definitions. The list appears in alphabetical order starting in version 1.2.7.
alias cl
shows that alias and its definition.
alias -cl mse
removes the aliases listed.

Some uses for aliases include

Once an alias has been created, it remains available until removed, even if Clisk is restarted or the machine or Skype restarts. Aliases are stored in the same file that contains AutoActions. This has a few implications; see the Clisk Option Storage section for details.

Starting in Clisk 2.1.1, aliases can include directions on where to put parameters from the user's command line. To demonstrate by example:

alias olstat get user %1 onlinestatus
Makes olstat do what the built-in os command does; namely, indicate the online status of a user.
olstat bob
Get the online status of the user matching "bob." Here, %1 becomes "bob."
alias topic msg %1 /topic %2-
Make a quick way to change the topic of a chat.
topic @mychat This chat is my chat, this chat is your chat ...
Set the topic for the chat whose name matches "mychat" to the indicated value. Here, %1 becomes "@mychat" and %2- (the dash meaning we want this parameter and the rest of the command line after it) becomes "This chat is my chat, this chat is your chat ..."
Note that when you include any %1, %2, etc. items in your alias definition, the rest of the command line after the alias is no longer tacked onto the end of the command, unless you specifically request this with something like %2- as in the above example. Also, if an alias contains (for example) %2, an error will be raised if the user tries to invoke the alias without passing that many parameters:
Generates an error because there is no value for %1.
But a "this parameter and all thereafter" item like %2- does not cause an error if that many parameters are not given:
topic @mychat
Sets the mychat topic to an empty value. Here, %1 becomes "@mychat," and %2- becomes the null string, without generating an error.

Skype Event Reporting In Clisk

Besides allowing commands to be executed against Skype, Clisk reports asynchronously on various Skype events as they happen. When something of interest happens in Skype, Clisk will produce one or more lines of output explaining what happened. Examples include incoming calls, call status changes, text chat messages, connection status changes, and responses to the commands you type when those commands also generate Skype events.

When Clisk reports an event, the "Clisk>" prompt may get left behind on the screen. Press Enter at any time to get a fresh "Clisk>" prompt. You do not need a prompt before typing a command however; Clisk will honor a command typed on a blank line.

If a Skype event causes output while you are typing a line, the cursor will move to a new line. Beware, however, that Clisk will think you are still right where you left off in the line you were typing. If you are unsure where you are in a command and want to restart it, clear the line and then retype the command from scratch. On MacOS and Linux, Ctrl+U usually clears the current line. On Windows, use Esc.

Clisk reports the following events as they happen in Skype:

The User Selection System

Many commands allow partial user IDs or names to be typed in place of full Skype IDs. This eases user selection while also protecting against typos and major accidents resulting from them. Only Clisk-implemented commands support this user selection system. Raw Skype API commands still require exact user IDs to be typed.

For commands supporting the new user selection system, anything you type for a user name will be handled thus:

Some examples:

msg . Hello there!
Sends "Hello there!" to the user currently selected in the Skype interface.
call !echo123
Calls echo123 without a search for that ID, which means it works whether echo123 is in your contact list or not.
call doug
Call the user whose ID or full name contains "doug." If no such user is found, you will be asked whether to call the user with an actual Skype ID of "doug" or just cancel the call. If more than one "doug" is found, you will be shown a list and allowed to select the one to call.

Advanced Clisk Usage

Some Clisk features are considered by the Clisk author to be useful only to advanced users or in unique situations. These are described here.

Advanced AutoAction Flags

Clisk 2.2.0 and later offer special autoAction flags for prioritizing and controlling autoAnswer and autoJoin behavior. These are in addition to a and j and can change how those flags work for other users. Clisk users are urged to read and understand this section carefully before attempting to use these flags, as some interesting social surprises may otherwise result.

Priority AutoAnswer Flags

Instead of a or j, you can grant a user any single digit between 1 and 9, inclusive, as a flag. These act as AutoAnswer priorities, and they work as follows:

For example, if a caller has a 5 flag and calls while you are in a conference, hosted locally or remotely, containing four participants with flags 6, a, j, and 5, the incoming call will not be answered because there is one conference participant with priority 5, and the incoming call's priority is not higher than 5. If the conference participant with a 5 flag drops and the same caller calls again though, the call will be answered and the entire conference put on hold, because 5 now beats all priorities in the conference.

Exclusive Call Flag

The autoJoin (j) flag can, as mentioned earlier, cause interesting social situations if used carelessly. Some Skypers categorically object to having unexpected guests drop into their calls. Some Skypers have certain people with whom they prefer to maintain private conversations even though they have granted j flags to some of their friends. Whatever the reason for use, there is as of Clisk 2.2.0 an "exclusive call" (x) flag to help govern the effects of j flags.

If you grant user Bob an x flag, no user with a j flag may join a one-on-one call you have with Bob. Users with priority autoAnswer flags may still cause your call with Bob to be put on hold, unless of course you also grant Bob a high enough priority to prevent this.

If you are hosting a conference and someone with a j flag calls you, the caller will be joined into the conference if any one or more current participants do not have x flags. This policy deserves some discussion:

Combining this feature with the default "*" pseudo-user has an interesting effect: If you type

aa * x
you will effectively disable autoJoins completely until you reverse the action with
aa * -x
This works because granting "*" an x flag will cause everyone that could possibly be in a call or conference with you to have an x flag. This makes it impossible for anyone to autoJoin a call, because there will never be someone in the call without an x flag to let a new caller in.. This is therefore a very handy way to shut down autoJoins temporarily.

Redirecting Sound

Clisk includes commands for redirecting sound in an active Skype call. These allow you to

Warning: These commands are primarily for Skype API testing. There are far better alternatives for recording Skype calls and redirecting sound. The following caveats apply:

The Clisk commands for sound redirection follow:

Record or stream the other end of a call. The local microphone input will not appear in the recording or stream.
Record the local microphone input into a file or stream.
snd Play a sound file into the call. The file will not be heard locally while playing. From the time this command is issued until the next snd off command, the person at the other end of your call will not hear you, as sound will have been redirected from the file instead of from your mic. This is true even if the file fails to play, and it remains true after the file finishes playing. You must therefore have some way to know when to issue the snd off command to cut sound back from the file to your mic.
All of these commands accept a single parameter indicating what source or destination to use:


rec out1
Starts recording the current call (remote end only) into out1.wav in your home directory.
rec /users/Joe/out1.wav
Does the same thing if your home folder is /users/Joe. This example explicitly includes the .wav extension that the first example allowed Clisk to add implicitly. This path format is valid on MacOS.
rec c:\mycall.wav
Record into mycall.wav at the root of the C drive on a Windows machine.
rec 23456
Send sound from the other end of the active call to TCP port 23456 (Clisk 2.2.0 and later). You need to have set up a program to listen on that port first, or this command will silently fail.
rec off
Stops recording the current call. If the redirection of sound had cut off sound to your sound card, it will now be restored.
mic me
Starts recording you into me.wav in your home directory.
mic off
Stops recording you into a file (assuming the OS allows the compensation explained above to work).
snd explosion
Wakes up whoever you are talking to with a loud boom, assuming that your home directory contains a file called explosion.wav in the format expected by Skype as explained above, and that this file is indeed a loud boom.
snd off
Stops redirecting sound into the call from a file, reactivating sound from your microphone. Don't forget to do this when done playing a file, or your callee will wonder where you went.

Very advanced users may enjoy the following special uses of the rec command with a port number:

Watching Skype Events By Name

Clisk 2.2.0 and later includes a watchEvent command that can be used to make Clisk report when various Skype API events occur and what information is sent with them. Type help watchEvent to get a list of the events that can be watched. The event list is actually constructed at run time from Skype4Py, the interface Clisk uses to communicate with Skype's API. As such, the event list may change in future Clisk versions in response to Skype4Py updates.

Warning: This system is not at all polished and will often print raw Skype4Py objects, which will look rather cryptic to those who don't program in Python. The watchEvent command is primarily intended for use in detecting formats of event data for future Clisk development.

Adding Clisk Commands

The alias command is powerful enough for most new command requirements but may not suffice for all such occasions. Starting in Clisk 2.3.0, users who know how to program in Python and who wish to add local commands that are not part of Clisk itself may do so by creating files of the form clisk_*.py in the same folder as itself (or actually anywhere on the program path). They will be loaded along with and can even override functions in it. To create a command called blah, the following approach is recommended:

Warning: This support is experimental and subject to change. In particular, it should be safe to assume that functions named do_*() will continue to work as they do now, but at some point all other functions, classes, etc., will probably be moved into their own namespace, as with most Python modules.

Special Considerations

The following subsections address special concerns that may apply to some users of Clisk.

Clisk Conference Structure

At this writing, conferences created by Clisk will have the look and feel in the Skype user interface of Windows Skype 3.x conferences, or Mac Skype 2.x conferences. They will not act like Windows Skype 4.x conferences, which include text chatting and voice calls in a combined structure. To the author's knowledge, the Skype API does not support management of this newer conference type. Reports and specifics to the contrary are most welcome. In the mean time, using Clisk conferences from Skype 4.x may have any of the following effects:

Despite these shortcomings, Clisk conferences do support the same level of voice quality and the same number of participants as Skype itself allows.

Clisk Option Storage

Clisk maintains an ini-style file to hold AutoAction settings and command aliases. The file is stored in a location specific to the active Skype account. Users, particularly users who reinstall Skype often or use multiple accounts, should keep the following points in mind:

Translating Clisk Into Another Language

The Clisk author must here apologize for the following state of affairs.

At present, there is no easy support for translating Clisk into another language. The primary reason is that much of Clisk's command structure consists of Skype API commands, which are in English by definition and can not be translated because Skype would then not understand them. As this utility was first born as a utility for the author to use in testing Skype API functionality, the author did not include support, such as a gettext environment, for translating even those text strings that could be translated. Finally, though Skype4Py (on which Clisk relies) does include support for translating some of the Skype API's output into other languages, attempting to use Clisk in another language environment may break some Clisk functionality as currently implemented, in places where Clisk scans Skype4Py output for specific text strings that could, in such a case, be localized and thus no longer match as expected.

All that said, the author's best advice to anyone wishing to translate Clisk is