1pidgin(1) General Commands Manual pidgin(1)
2Ri.
6
8 pidgin - Instant Messaging client
9
11 pidgin [options]
12
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 Pidgin can be extended by plugins written in multiple programming lan‐
23 guages and controlled through DBus or purple-remote.
24
27 The following options are provided by Pidgin using the standard GNU
28 command line syntax:
29 -c, --config=DIR
31 Use DIR as the directory for config files instead of ~/.purple.
32 -d, --debug
34 Print debugging messages to stdout. These are the same debug‐
35 ging messages that are displayed in the Debug Window.
36 -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 -h, --help
42 Print a summary of command line options and exit.
43 -m, --multiple
45 Allow multiple instances of Pidgin to run.
46 -n, --nologin
48 Don't automatically login when Pidgin starts. Sets the global
49 status to Offline.
50 -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 -v, --version
58 Print the current version and exit.
59
62 Pidgin uses a few terms differently from other applications. For con‐
63 venience they are defined here:
64 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 Buddy A user who has been added to the Buddy List.
70 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 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 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
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 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 Get Info
101 Retrieves and displays information about the buddy. This infor‐
102 mation is also known as a Profile.
103 IM Opens a new Conversation window to the selected buddy.
105 Send File
107 Sends a file to the selected buddy (only available on protocols
108 that support file transfer).
109 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 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 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 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 The remainder of the menu will consist of protocol specific commands.
132 These commands vary depending on the protocol.
133 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
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 If Remember Password is chosen, the password will be saved in Pidgin's
150 ~/.purple/accounts.xml configuration file.
151 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 Each protocol has its own specific options that can be found in the
157 modify screen.
158
161 All options take effect immediately.
162
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 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 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 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 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 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
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 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 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
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
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 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 Enable Sounds
245 Determines when to play sounds.
246 Sound Events
249 Lets the user choose when and what sounds are to be played.
250
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 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 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 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 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
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 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
300 Log format
301 Specifies how to log. Pidgin supports HTML and plain text, but
302 plugins can provide other logging methods.
303 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 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 Log all status changes to system log
318 When enabled, status changes are logged.
319
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 Auto-reply
331 Determines when to send an auto-reply on protocols which support
332 it (currently only AIM).
333 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 Minutes before becoming idle
342 Specifies how many minutes of inactivity are required before
343 considering the user to be idle.
344 Change status to
347 Specifies which "primitive" or "saved" status to use when set‐
348 ting status on idle.
349 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 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
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 Font This menu provides font control options for the current conver‐
372 sation. Size, style, and face may be configured here.
373 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 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
384 For protocols that allow it, Chats can be entered through the Buddies
385 menu.
386 Additional features available in chat, depending on the protocol are:
388 Whisper
390 The text will appear in the chat conversation, but it will only
391 be visible to the sender and the receiver.
392 Invite Invite other people to join the chat room.
394 Ignore Ignore anything said by the chosen person
396 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 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
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 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 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 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 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 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 Status - The type of status being created, such as Available,
461 Away, etc.
462 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 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 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
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
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 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
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 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
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
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
544 Pidgin allows for interaction via D-Bus. Currently very little docu‐
545 mentation about this interaction exists.
546
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
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
567 The bug tracker can be reached by visiting http://developer.pid‐
568 gin.im/query
569 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
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 You are also encouraged to drop by at #pidgin on irc.freenode.net to
582 discuss development.
583
587 http://pidgin.im/
588 http://developer.pidgin.im/
589 purple-remote(1)
590 finch(1)
591
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 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 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
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 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 Our artists are:
650 Hylke Bons <h.bons@student.rug.nl>
651 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 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 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>.
678Pidgin v2.10.0 pidgin(1)