1pidgin(1)                   General Commands Manual                  pidgin(1)
2
3
4
5Ri.
6

NAME

8       pidgin - Instant Messaging client
9

SYNOPSIS

11       pidgin [options]
12
13

DESCRIPTION

15       pidgin is a graphical modular messaging client based on libpurple which
16       is capable of connecting to XMPP, IRC, SILC,  Novell  GroupWise,  Lotus
17       Sametime,  Zephyr,  Gadu-Gadu,  and  QQ all at once. It has many common
18       features found in other clients, as well as many unique features.
19
20       Pidgin can be extended by plugins written in multiple programming  lan‐
21       guages and controlled through DBus or purple-remote.
22
23

OPTIONS

25       The  following  options  are  provided by Pidgin using the standard GNU
26       command line syntax:
27
28       -c, --config=DIR
29              Use DIR as the directory for config files instead of ~/.purple.
30
31       -d, --debug
32              Print debugging messages to stdout.  These are the  same  debug‐
33              ging messages that are displayed in the Debug Window.
34
35       -f, --force-online
36              Try to be online even if the network is reported (by Windows, or
37              NetworkManager on Linux) to be unavailable.
38
39       -h, --help
40              Print a summary of command line options and exit.
41
42       -m, --multiple
43              Allow multiple instances of Pidgin to run.
44
45       -n, --nologin
46              Don't automatically login when Pidgin starts.  Sets  the  global
47              status to Offline.
48
49       -l, --login[=NAME,NAME,...]
50              Enable  the comma-separated list of accounts provided, disabling
51              all other accounts.  If the user does not specify such a  comma-
52              separated  list,  the  first account in accounts.xml will be en‐
53              abled.
54
55       -v, --version
56              Print the current version and exit.
57
58

TERMS

60       Pidgin uses a few terms differently from other applications.  For  con‐
61       venience they are defined here:
62
63       Buddy List
64              The  list of other users who the user wants to see status infor‐
65              mation for and have quick access to for messaging.
66
67       Buddy  A user who has been added to the Buddy List.
68
69       Contact
70              A grouping of more than one buddy who are all the  same  person.
71              A  contact may contain buddies from any protocol and may contain
72              as many buddies as the user desires.  Contact  arrangements  are
73              stored locally only.
74
75       Alias  A  private  "nickname"  that  may be set for Buddies or the user
76              himself.  On some protocols, aliases are saved on the server but
77              not  visible  to  other  users.  On other protocols, aliases are
78              saved only locally.
79
80       Protocol
81              A messaging service.  XMPP, Zephyr, etc. are protocols.   Others
82              may call these "service types," "account types," "services," and
83              so on.
84
85

BUDDY LIST

87       The Buddy List window is Pidgin's main interface  window.   Using  this
88       window  a  user can see which of his/her buddies is online, away, idle,
89       etc.  The user can also add buddies to  and  remove  buddies  from  the
90       buddy list.
91
92       The Buddy List window contains a list of the user's buddies who are on‐
93       line and have allowed the user to be notified of their  presence.   The
94       icon  to  the  left of each buddy indicates the buddy's current status.
95       Double clicking a buddy will open a  new  Conversation  window.   Right
96       clicking will pop up a menu:
97
98       Get Info
99              Retrieves and displays information about the buddy.  This infor‐
100              mation is also known as a Profile.
101
102       IM     Opens a new Conversation window to the selected buddy.
103
104       Send File
105              Sends a file to the selected buddy (only available on  protocols
106              that support file transfer).
107
108       Add Buddy Pounce
109              A  Buddy  Pounce  is  a configurable automated action to be per‐
110              formed when the buddy's state changes.  This will open the Buddy
111              Pounce dialog, which will be discussed later.
112
113       View Log
114              Pidgin is capable of automatically logging messages.  These logs
115              are either plain text files (with  a  .txt  extension)  or  html
116              files  (with a .html extension) located under the ~/.purple/logs
117              directory.  This menu command will display Pidgin's  log  viewer
118              with logs loaded for that buddy or chat.
119
120       Alias  Create an alias for this buddy.  This will show an editable text
121              field where the buddy's name was displayed.  In this  field  one
122              can  give  this buddy an alternate, more friendly name to appear
123              on the buddy list and in conversations.
124
125              For example, if a buddy's name was  jsmith1281xx  and  his  real
126              name  was 'John Q. Smith,' one could create an alias as to iden‐
127              tify the buddy by his common name.
128
129       The remainder of the menu will consist of protocol  specific  commands.
130       These commands vary depending on the protocol.
131
132       Status Selector
133              At  the  bottom of the Buddy List is a status selector which al‐
134              lows one to change his/her status.  This will be discussed  fur‐
135              ther in the STATUS MESSAGES section below.
136
137

ACCOUNT EDITOR

139       The account editor consists of a list of accounts and information about
140       them.  It can be accessed by selecting Manage from the  Accounts  menu.
141       Clicking  Delete  will delete the currently selected account.  Clicking
142       Add or Modify will invoke a Modify Account window.  Here, the user  can
143       add  or  alter  account  information.  When creating a new account, the
144       user will submit a username and password.  The user  will  also  choose
145       the protocol for the account.
146
147       If  Remember Password is chosen, the password will be saved in Pidgin's
148       ~/.purple/accounts.xml configuration file.
149
150       If Enabled is checked in the accounts dialog, this account will  follow
151       the  status  currently  selected  in the status selector.  If it is not
152       checked, the account will always be offline.
153
154       Each protocol has its own specific options that can  be  found  in  the
155       modify screen.
156
157

PREFERENCES

159       All options take effect immediately.
160
161

Interface

163       Show system tray icon
164              Specifies when to show a Pidgin icon in the notification area of
165              the user's panel (commonly referred to as the System Tray).
166
167
168       Hide new IM conversations
169              Specifies when to hide new IM messages.  Messages will queue un‐
170              der  the  specified  condition until shown.  Clicking the Pidgin
171              icon in the notification area or system tray  will  display  the
172              queued  messages.  An icon also appears in the buddy list's menu
173              bar; this icon may also be used to display queued messages.
174
175
176       Show IMs and chats in tabbed windows
177              When checked, this option will cause IM and chat sessions to ap‐
178              pear  in windows with multiple tabs.  One tab will represent one
179              conversation or chat.  Where tabs are placed will be dictated by
180              the preferences below.
181
182
183       Show close buttons on tabs
184              When  checked, this option will cause a clickable "U+2715 MULTI‐
185              PLICATION X" unicode character to appear at the  right  edge  of
186              each tab.  Clicking this will cause the tab to be closed.
187
188
189       Placement
190              Specifies  where to place tabs in the window.  Some tab orienta‐
191              tions may allow some users to fit more tabs into a single window
192              comfortably.
193
194
195       New conversations
196              Specifies  under  which conditions tabs are placed into existing
197              windows or into new windows.  For a single window,  select  Last
198              created window here.
199
200

Conversations

202       Enable buddy icon animation
203              If  a  buddy's icon happens to be animated, this option will en‐
204              able the animation, otherwise only the first frame will be  dis‐
205              played.
206
207
208       Notify buddies that you are typing to them
209              Some protocols allow clients to tell their buddies when they are
210              typing.  This option enables this  feature  for  protocols  that
211              supports it.
212
213
214       Default Formatting
215              Allows  specifying the default formatting to apply to all outgo‐
216              ing messages (only applicable to protocols that support  format‐
217              ting in messages).
218
219

Smiley Themes

221       Allows  the  user to choose between different smiley themes. The "none"
222       theme will disable graphical emoticons - they will be displayed as text
223       instead.   The  Add  and Remove buttons may be used to install or unin‐
224       stall smiley themes.  Themes may also  be  installed  by  dragging  and
225       dropping them onto the list of themes.
226
227

Sounds

229       Method Lets  the  user  choose  between different playback methods. The
230              user can also manually enter a command to  be  executed  when  a
231              sound  is  to  be played(%s expands to the full path to the file
232              name).
233
234
235       Sounds when conversation has focus
236              When checked, sounds will play for events in the active  conver‐
237              sation  if  the  window is focused.  When unchecked, sounds will
238              not play for the active conversation when the window is focused.
239
240
241       Enable Sounds
242              Determines when to play sounds.
243
244
245       Sound Events
246              Lets the user choose when and what sounds are to be played.
247
248

Network

250       STUN server
251              This allows specifying a server which uses the STUN protocol  to
252              determine  a host's public IP address.  This can be particularly
253              useful for some protocols.
254
255
256       Autodetect IP address
257              When checked, causes Pidign to attempt to determine  the  public
258              IP  address  of the host on which Pidgin is running and disables
259              the Public IP text field listed below.
260
261
262       Public IP
263              If Autodetect IP address is disabled, this field allows manually
264              specifying the public IP address for the host on which Pidgin is
265              running.  This is mainly useful for users with multiple  network
266              interfaces or behind NATs.
267
268
269       Manually specify range of ports to listen on
270              Specify  a  range  ports  to listen on, overriding any defaults.
271              This is sometimes useful for file transfers and Direct IM.
272
273
274       Proxy Server
275              The configuration section to enable Pidgin to operate through  a
276              proxy  server.   Pidgin  currently  supports  SOCKS 4/5 and HTTP
277              proxies.
278
279

Browser

281       Browser
282              Allows the user to select Pidgin's default web  browser.   Fire‐
283              fox,  Galeon,  Konqueror,  Mozilla,  Netscape and Opera are sup‐
284              ported natively.  The user can also manually enter a command  to
285              be executed when a link is clicked (%s expands to the URL).  For
286              example, xterm -e lynx "%s" will open the link with lynx.
287
288
289       Open link in
290              Allows the user to specify whether to use an existing window,  a
291              new  tab,  a new window, or to let the browser to decide what to
292              do when calling the browser to open a link.  Which  options  are
293              available will depend on which browser is selected.
294
295

Logging

297       Log format
298              Specifies  how to log.  Pidgin supports HTML and plain text, but
299              plugins can provide other logging methods.
300
301
302       Log all instant messages
303              When enabled, all IM conversations  are  logged.   This  can  be
304              overridden  on a per-conversation basis in the conversation win‐
305              dow.
306
307
308       Log all chats
309              When enabled, all chat conversations are logged.   This  can  be
310              overridden  on a per-conversation basis in the conversation win‐
311              dow.
312
313
314       Log all status changes to system log
315              When enabled, status changes are logged.
316
317

Status / Idle

319       Report idle time
320              Determines under which conditions to report idle time.  Based on
321              keyboard  and  mouse use uses keyboard and mouse activity to de‐
322              termine idle time.  From last sent  message  uses  the  time  at
323              which  the user last sent a message in Pidgin to determine idle.
324              Never disables idle reporting.
325
326
327       Change status when idle
328              When enabled, this uses the Minutes  before  becoming  idle  and
329              Change  status  to  preferences described below to set status on
330              idle.
331
332
333       Minutes before becoming idle
334              Specifies how many minutes of  inactivity  are  required  before
335              considering the user to be idle.
336
337
338       Change status to
339              Specifies  which  "primitive" or "saved" status to use when set‐
340              ting status on idle.
341
342
343       Use status from last exit at startup
344              If this is checked, Pidgin will remember what status was  active
345              when  the  user  closed  Pidgin  and restore it at the next run.
346              When disabled, Pidgin will always set  the  status  selected  in
347              Status to apply at startup at startup.
348
349
350       Status to apply at startup
351              When  Use  status  from  last  exit at startup is disabled, this
352              specifies which "primitive" or "saved" status to use at startup.
353
354

CONVERSATIONS

356       When starting a new conversation, the user is presented with  the  Con‐
357       versation  window.   The conversation appears in the upper text box and
358       the user types his/her message in the lower text box.  Between the  two
359       is a row of options, represented by icons.  Some or all buttons may not
360       be active if the protocol does not  support  the  specific  formatting.
361       From left to right:
362
363       Font   This  menu provides font control options for the current conver‐
364              sation.  Size, style, and face may be configured here.
365
366       Insert This menu provides the  ability  to  insert  images,  horizontal
367              rules,  and links where the protocol supports each of these fea‐
368              tures.
369
370       Smile! Allows the insertion of graphical smileys via the  mouse.   This
371              button  shows  the  user a dialog with the available smileys for
372              the current conversation.
373
374

CHATS

376       For protocols that allow it, Chats can be entered through  the  Buddies
377       menu.
378
379       Additional features available in chat, depending on the protocol are:
380
381       Whisper
382              The  text will appear in the chat conversation, but it will only
383              be visible to the sender and the receiver.
384
385       Invite Invite other people to join the chat room.
386
387       Ignore Ignore anything said by the chosen person
388
389       Set Topic
390              Set the topic of the chat room.  This is usually  a  brief  sen‐
391              tence  describing  the nature of the chat--an explanation of the
392              chat room's name.
393
394       Private Message (IM)
395              Send a message to a specific person in the chat.  Messages  sent
396              this  way will not appear in the chat window, but instead open a
397              new IM conversation.
398
399

STATUS MESSAGES

401       Most protocols allow for status messages.  By using status messages,  a
402       user  can  leave  an informative message for others to see.  Status and
403       status messages are configured via the status selector at the bottom of
404       the  Buddy List window.  By default the menu shown here is divided into
405       sections for "primitive" status types, such as Available, Away, etc.; a
406       few  "popular"  statuses  (including  "transient" statuses)  which have
407       been recently used, and a section which shows New Status...  and  Saved
408       Statuses... options for more advanced status manipulation.
409
410
411       Primitive Statuses
412              A  primitive status is a basic status supported by the protocol.
413              Examples of primitive statuses would be Available, Away, Invisi‐
414              ble,  etc.  A primitive status can be used to create a Transient
415              Status or a Saved Status, both  explained  below.   Essentially,
416              primitive  statuses are building blocks of more complicated sta‐
417              tuses.
418
419
420       Transient Statuses
421              When one of the statuses from the topmost section of the  status
422              selector's menu is selected, this creates a transient, or tempo‐
423              rary, status.  The status will show in  the  "popular  statuses"
424              section  in  the  menu  until  it has not been used for a suffi‐
425              ciently long time.  A transient status may also  be  created  by
426              selecting  New  Status...  from the status selector's menu, then
427              clicking Use once the user has entered the message.
428
429
430       Saved Statuses
431              Saved statuses are permanent--once created, they will exist  un‐
432              til  deleted.  Saved statuses are useful for statuses and status
433              messages that will be used on a regular basis.   They  are  also
434              useful  for  creating  complex  statuses  in which some accounts
435              should always have a different status from others.  For example,
436              one might wish to create a status called "Sleeping" that has all
437              accounts set to "Away", then create another status called "Work‐
438              ing"  that  has three accounts set to "Away" and another account
439              set to "Available."
440
441
442       New Status Window
443              When the user selects New Status...  from  the  status  selector
444              menu,  Pidgin presents the user with a dialog asking for status-
445              related information.  That information is discussed below:
446
447              Title - The name of the status that will appear  in  the  status
448              selctor's  menu.  If the user clicks the Save or Save & Use but‐
449              ton, this name will also be shown in the  Saved  Status  Window.
450              The title should be a short description of the status.
451
452              Status  -  The  type of status being created, such as Available,
453              Away, etc.
454
455              Message - The content of the status message.  This  is  what  is
456              visible to other users.  Some protocols will allow formatting in
457              some status messages; where formatting is not supported it  will
458              be stripped to the bare text entered.
459
460              Use  a different status for some accounts - This allows the cre‐
461              ation of complex statuses in which some accounts' status differs
462              from  that  of other accounts.  To use this, the user will click
463              the expander to the left of the text, then select individual ac‐
464              counts which will have a different status and/or status message.
465              When the user selects an account, Pidgin  will  present  another
466              status dialog asking for a status and a message just for the se‐
467              lected account.
468
469
470       Saved Status Window
471              When the user selects Saved Statuses... from the  status  selec‐
472              tor's  menu,  Pidgin presents a dialog that lists all saved sta‐
473              tuses.  "Transient" statuses, discussed  above,  are  NOT  shown
474              here.  This window provides the ability to manage saved statuses
475              by allowing the creation, modification, and  deletion  of  saved
476              statuses.  The Use, Modify, and Delete buttons here allow opera‐
477              tion on the status selected from the list; the dd button  allows
478              creation  of a new saved status, and the Close button closes the
479              window.
480
481

BUDDY POUNCE

483       A Buddy Pounce is an automated trigger that occurs when a buddy returns
484       to  a normal state from an away state.  The Buddy Pounce dialog box can
485       be activated by selecting the Buddy Pounce option from the Tools  menu.
486       From  this  dialog,  new pounces can be created with the Add button and
487       existing pounces can be removed with the Delete button.  A  pounce  can
488       be set to occur on any combination of the events listed, and any combi‐
489       nation of actions can result.  If Pounce only when  my  status  is  not
490       Available  is checked, the pounce will occur only if the user is set to
491       a non-available status, such as invisible, do not disturb,  away,  etc.
492       If  Recurring  is  checked, the pounce will remain until removed by the
493       Delete button.
494
495

CUSTOM SMILIES

497       Pidgin 2.5.0 introduced support for custom smilies on  those  protocols
498       for  which  interested contributors have developed support.  The custom
499       smiley manager can be accessed by selecting Smiley from the Tools menu.
500       From  here, custom smilies may be added, edited, or deleted by clicking
501       the Add, Edit, or Delete buttons, respectively.
502
503       During a conversation with another user, that user's custom smileys may
504       be added to the user's own custom smiley list directly from the conver‐
505       sation window by right-clicking the new custom smiley and selecting Add
506       Custom Smiley...
507
508

PLUGINS

510       Pidgin allows for dynamic loading of plugins to add extra functionality
511       to Pidgin.  See plugins/HOWTO or http://developer.pidgin.im/wiki/CHowTo
512       for information on writing plugins.
513
514       The  plugins dialog can be accessed by selecting Plugins from the Tools
515       menu. Each plugin available appears in this dialog with its name,  ver‐
516       sion,  and a short summary of its functionality. Plugins can be enabled
517       with the checkbox beside the name and short description.  More informa‐
518       tion  on the currently selected plugin is available by clicking the ex‐
519       pander beside the text Plugin Details.   If  the  selected  plugin  has
520       preferences  or configuration options, the Configure Plugin button will
521       present the plugin's preferences dialog.
522
523

PERL

525       Pidgin allows for plugins to be written in the perl scripting language.
526       See  Perl Scripting HOWTO in the Pidgin documentation for more informa‐
527       tion about perl scripting.
528
529

TCL

531       Pidgin allows for plugins to be written in the Tcl scripting  language.
532       See plugins/tcl/TCL-HOWTO for more information about Tcl scripting.
533
534

D-Bus

536       Pidgin  allows  for interaction via D-Bus.  Currently very little docu‐
537       mentation about this interaction exists.
538
539

FILES

541         /usr/bin/pidgin: Pidgin's location.
542         ~/.purple/blist.xml: the buddy list.
543         ~/.purple/accounts.xml: information about the user's accounts.
544         ~/.purple/pounces.xml: stores the user's buddy pounces.
545         ~/.purple/prefs.xml: Pidgin's configuration file.
546         ~/.purple/status.xml: stores the user's away messages.
547         ~/.purple/logs/PROTOCOL/ACCOUNT/BUDDYNAME/DATE.{html,txt}:  conversa‐
548       tion logs.
549
550

DIRECTORIES

552         /usr/lib/pidgin/: Pidgin's plugins directory.
553         /usr/lib/purple-2/: libpurple's plugins directory.
554         ~/.purple: users' local settings
555         ~/.purple/plugins/: users' local plugins
556
557

BUGS

559       The  bug  tracker  can  be  reached  by  visiting http://developer.pid
560       gin.im/query
561
562       Before sending a bug report, please verify that  you  have  the  latest
563       version  of  Pidgin.  Many bugs (major and minor) are fixed at each re‐
564       lease, and if yours is out of date, the problem may already  have  been
565       solved.
566
567

PATCHES

569       If  you  fix a bug in Pidgin (or otherwise enhance it), please submit a
570       patch (using mtn diff > my.diff against the  latest  version  from  the
571       Monotone repository) at http://developer.pidgin.im/simpleticket
572
573       You  are  also  encouraged  to drop by at #pidgin on irc.libera.chat to
574       discuss development.
575
576
577

SEE ALSO

579       http://pidgin.im/
580       http://developer.pidgin.im/
581       purple-remote(1)
582       finch(1)
583
584

LICENSE

586       This program is free software; you can redistribute it and/or modify it
587       under  the  terms of the GNU General Public License as published by the
588       Free Software Foundation; either version 2 of the License, or (at  your
589       option) any later version.
590
591       This  program  is  distributed  in the hope that it will be useful, but
592       WITHOUT ANY  WARRANTY;  without  even  the  implied  warranty  of  MER‐
593       CHANTABILITY  or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
594       Public License for more details.
595
596       You should have received a copy of the GNU General Public License along
597       with this program; if not, write to the Free Software Foundation, Inc.,
598       51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
599
600

AUTHORS

602       Pidgin's active developers are:
603         Daniel 'datallah' Atallah (developer)
604         Paul 'darkrain42' Aurich (developer)
605         John 'rekkanoryo' Bailey (developer and bugmaster)
606         Ethan 'Paco-Paco' Blanton (developer)
607         Thomas Butter (developer)
608         Ka-Hing Cheung (developer)
609         Sadrul Habib Chowdhury (developer)
610         Mark 'KingAnt' Doliner (developer) <thekingant@users.sourceforge.net>
611         Sean Egan (developer) <seanegan@gmail.com>
612         Casey Harkins (developer)
613         Ivan Komarov
614         Gary 'grim' Kramlich (developer)
615         Richard 'rlaager' Laager (developer) <rlaager@pidgin.im>
616         Sulabh 'sulabh_m' Mahajan (developer)
617         Richard 'wabz' Nelson (developer)
618         Christopher 'siege' O'Brien (developer)
619         Bartosz Oler (developer)
620         Etan 'deryni' Reisner (developer)
621         Tim 'marv' Ringenbach (developer) <marv_sf@users.sf.net>
622         Michael 'Maiku' Ruprecht (developer, voice and video)
623         Elliott 'QuLogic' Sales de Andrade (developer)
624         Luke 'LSchiere' Schierer (support)
625         Megan 'Cae' Schneider (support/QA)
626         Evan Schoenberg (developer)
627         Kevin 'SimGuy' Stange (developer and webmaster)
628         Will 'resiak' Thompson (developer)
629         Stu 'nosnilmot' Tomlinson (developer)
630         Nathan 'faceprint' Walp (developer)
631
632
633       Our crazy patch writers include:
634         Marcus 'malu' Lundblad
635         Dennis 'EvilDennisR' Ristuccia
636         Peter 'fmoo' Ruibal
637         Gabriel 'Nix' Schulhof
638         Jorge 'Masca' Villaseñor
639
640
641       Our artists are:
642         Hylke Bons <h.bons@student.rug.nl>
643
644
645       Our retired developers are:
646         Herman Bloggs (win32 port) <herman@bluedigits.com>
647         Jim Duchek <jim@linuxpimps.com> (maintainer)
648         Rob Flynn <gaim@robflynn.com> (maintainer)
649         Adam Fritzler (libfaim maintainer)
650         Christian    'ChipX86'    Hammond     (developer     &     webmaster)
651       <chipx86@chipx86.com>
652         Syd Logan (hacker and designated driver [lazy bum])
653         Jim Seymour (XMPP developer)
654         Mark Spencer (original author) <markster@marko.net>
655         Eric Warmenhoven (former lead developer) <eric@warmenhoven.org>
656
657
658       Our retired crazy patch writers include:
659         Felipe 'shx' Contreras
660         Decklin Foster
661         Peter 'Bleeter' Lawler
662         Robert 'Robot101' McQueen
663         Benjamin Miller
664
665
666       This  manpage  was  originally written by Dennis Ristuccia <dennis@den‐
667       nisr.net>.  It has been updated and  largely  rewritten  by  Sean  Egan
668       <seanegan@gmail.com>,  Ben Tegarden <tegarden@uclink.berkeley.edu>, and
669       John Bailey <rekkanoryo@pidgin.im>.
670
671
672
673Pidgin v2.14.8                                                       pidgin(1)
Impressum