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 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 Pidgin can be extended by plugins written in multiple programming lan‐
21 guages and controlled through DBus or purple-remote.
22
25 The following options are provided by Pidgin using the standard GNU
26 command line syntax:
27 -c, --config=DIR
29 Use DIR as the directory for config files instead of ~/.purple.
30 -d, --debug
32 Print debugging messages to stdout. These are the same debug‐
33 ging messages that are displayed in the Debug Window.
34 -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 -h, --help
40 Print a summary of command line options and exit.
41 -m, --multiple
43 Allow multiple instances of Pidgin to run.
44 -n, --nologin
46 Don't automatically login when Pidgin starts. Sets the global
47 status to Offline.
48 -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 -v, --version
56 Print the current version and exit.
57
60 Pidgin uses a few terms differently from other applications. For con‐
61 venience they are defined here:
62 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 Buddy A user who has been added to the Buddy List.
68 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 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 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
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 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 Get Info
99 Retrieves and displays information about the buddy. This infor‐
100 mation is also known as a Profile.
101 IM Opens a new Conversation window to the selected buddy.
103 Send File
105 Sends a file to the selected buddy (only available on protocols
106 that support file transfer).
107 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 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 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 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 The remainder of the menu will consist of protocol specific commands.
130 These commands vary depending on the protocol.
131 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
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 If Remember Password is chosen, the password will be saved in Pidgin's
148 ~/.purple/accounts.xml configuration file.
149 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 Each protocol has its own specific options that can be found in the
155 modify screen.
156
159 All options take effect immediately.
160
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 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 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 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 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 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
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 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 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
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
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 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 Enable Sounds
242 Determines when to play sounds.
243 Sound Events
246 Lets the user choose when and what sounds are to be played.
247
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 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 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 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 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
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 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
297 Log format
298 Specifies how to log. Pidgin supports HTML and plain text, but
299 plugins can provide other logging methods.
300 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 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 Log all status changes to system log
315 When enabled, status changes are logged.
316
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 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 Minutes before becoming idle
334 Specifies how many minutes of inactivity are required before
335 considering the user to be idle.
336 Change status to
339 Specifies which "primitive" or "saved" status to use when set‐
340 ting status on idle.
341 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 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
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 Font This menu provides font control options for the current conver‐
364 sation. Size, style, and face may be configured here.
365 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 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
376 For protocols that allow it, Chats can be entered through the Buddies
377 menu.
378 Additional features available in chat, depending on the protocol are:
380 Whisper
382 The text will appear in the chat conversation, but it will only
383 be visible to the sender and the receiver.
384 Invite Invite other people to join the chat room.
386 Ignore Ignore anything said by the chosen person
388 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 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
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 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 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 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 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 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 Status - The type of status being created, such as Available,
453 Away, etc.
454 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 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 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
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
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 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
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 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
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
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
536 Pidgin allows for interaction via D-Bus. Currently very little docu‐
537 mentation about this interaction exists.
538
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
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
559 The bug tracker can be reached by visiting http://developer.pid‐
560 gin.im/query
561 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
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 You are also encouraged to drop by at #pidgin on irc.libera.chat to
574 discuss development.
575
579 http://pidgin.im/
580 http://developer.pidgin.im/
581 purple-remote(1)
582 finch(1)
583
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 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 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
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 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 Our artists are:
642 Hylke Bons <h.bons@student.rug.nl>
643 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 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 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>.
670Pidgin v2.14.6 pidgin(1)