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 AIM, MSN, Yahoo!,  XMPP,  ICQ,  IRC,  SILC,
17       Novell  GroupWise,  Lotus  Sametime,  Zephyr,  Gadu-Gadu, and QQ all at
18       once. It has many common features found in other clients,  as  well  as
19       many  unique  features.   Pidgin  is not endorsed by or affiliated with
20       America Online, ICQ, Microsoft, or Yahoo.
21
22       Pidgin can be extended by plugins written in multiple programming  lan‐
23       guages and controlled through DBus or purple-remote.
24
25

OPTIONS

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

TERMS

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

BUDDY LIST

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

ACCOUNT EDITOR

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

PREFERENCES

161       All options take effect immediately.
162
163

Interface

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

Conversations

204       Enable buddy icon animation
205              If  a  buddy's  icon  happens  to  be animated, this option will
206              enable the animation, otherwise only the  first  frame  will  be
207              displayed.
208
209
210       Notify buddies that you are typing to them
211              Some protocols allow clients to tell their buddies when they are
212              typing.  This option enables this  feature  for  protocols  that
213              supports  it.  For XMPP, this also enables sending the "User has
214              left the conversation" message when ending the conversation.
215
216
217       Default Formatting
218              Allows specifying the default formatting to apply to all  outgo‐
219              ing  messages (only applicable to protocols that support format‐
220              ting in messages).
221
222

Smiley Themes

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

Sounds

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

Network

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

Browser

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

Logging

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

Status / Idle

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

CONVERSATIONS

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

CHATS

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

STATUS MESSAGES

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

BUDDY POUNCE

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

CUSTOM SMILIES

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

PLUGINS

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

PERL

533       Pidgin allows for plugins to be written in the perl scripting language.
534       See  Perl Scripting HOWTO in the Pidgin documentation for more informa‐
535       tion about perl scripting.
536
537

TCL

539       Pidgin allows for plugins to be written in the Tcl scripting  language.
540       See plugins/tcl/TCL-HOWTO for more information about Tcl scripting.
541
542

D-Bus

544       Pidgin  allows  for interaction via D-Bus.  Currently very little docu‐
545       mentation about this interaction exists.
546
547

FILES

549         /usr/bin/pidgin: Pidgin's location.
550         ~/.purple/blist.xml: the buddy list.
551         ~/.purple/accounts.xml: information about the user's accounts.
552         ~/.purple/pounces.xml: stores the user's buddy pounces.
553         ~/.purple/prefs.xml: Pidgin's configuration file.
554         ~/.purple/status.xml: stores the user's away messages.
555         ~/.purple/logs/PROTOCOL/ACCOUNT/BUDDYNAME/DATE.{html,txt}:  conversa‐
556       tion logs.
557
558

DIRECTORIES

560         /usr/lib/pidgin/: Pidgin's plugins directory.
561         /usr/lib/purple-2/: libpurple's plugins directory.
562         ~/.purple: users' local settings
563         ~/.purple/plugins/: users' local plugins
564
565

BUGS

567       The  bug  tracker  can  be  reached  by  visiting http://developer.pid
568       gin.im/query
569
570       Before sending a bug report, please verify that  you  have  the  latest
571       version  of  Pidgin.   Many  bugs  (major  and minor) are fixed at each
572       release, and if yours is out of date, the problem may already have been
573       solved.
574
575

PATCHES

577       If  you  fix a bug in Pidgin (or otherwise enhance it), please submit a
578       patch (using mtn diff > my.diff against the  latest  version  from  the
579       Monotone repository) at http://developer.pidgin.im/simpleticket
580
581       You  are  also  encouraged to drop by at #pidgin on irc.freenode.net to
582       discuss development.
583
584
585

SEE ALSO

587       http://pidgin.im/
588       http://developer.pidgin.im/
589       purple-remote(1)
590       finch(1)
591
592

LICENSE

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

AUTHORS

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