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, XMPP, ICQ, IRC,  SILC,  Novell  Group‐
17       Wise,  Lotus  Sametime,  Zephyr,  Gadu-Gadu, and QQ all at once. It has
18       many common features found in other clients, as  well  as  many  unique
19       features.  Pidgin is not endorsed by or affiliated with America Online,
20       ICQ, or Microsoft.
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,  Zephyr,  etc.  are  protocols.
84              Others  may  call  these "service types," "account types," "ser‐
85              vices," 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.
214
215
216       Default Formatting
217              Allows  specifying the default formatting to apply to all outgo‐
218              ing messages (only applicable to protocols that support  format‐
219              ting in messages).
220
221

Smiley Themes

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

Sounds

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

Network

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

Browser

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

Logging

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

Status / Idle

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

CONVERSATIONS

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

CHATS

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

STATUS MESSAGES

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

BUDDY POUNCE

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

CUSTOM SMILIES

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

PLUGINS

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

PERL

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

TCL

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

D-Bus

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

FILES

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

DIRECTORIES

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

BUGS

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

PATCHES

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

SEE ALSO

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

LICENSE

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

AUTHORS

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