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, 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 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, Zephyr, etc. are protocols.
84 Others may call these "service types," "account types," "ser‐
85 vices," 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.
214 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
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
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 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 Enable Sounds
244 Determines when to play sounds.
245 Sound Events
248 Lets the user choose when and what sounds are to be played.
249
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 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 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 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 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
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 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
299 Log format
300 Specifies how to log. Pidgin supports HTML and plain text, but
301 plugins can provide other logging methods.
302 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 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 Log all status changes to system log
317 When enabled, status changes are logged.
318
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 Auto-reply
330 Determines when to send an auto-reply on protocols which support
331 it (currently only AIM).
332 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 Minutes before becoming idle
341 Specifies how many minutes of inactivity are required before
342 considering the user to be idle.
343 Change status to
346 Specifies which "primitive" or "saved" status to use when set‐
347 ting status on idle.
348 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 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
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 Font This menu provides font control options for the current conver‐
371 sation. Size, style, and face may be configured here.
372 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 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
383 For protocols that allow it, Chats can be entered through the Buddies
384 menu.
385 Additional features available in chat, depending on the protocol are:
387 Whisper
389 The text will appear in the chat conversation, but it will only
390 be visible to the sender and the receiver.
391 Invite Invite other people to join the chat room.
393 Ignore Ignore anything said by the chosen person
395 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 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
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 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 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 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 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 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 Status - The type of status being created, such as Available,
460 Away, etc.
461 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 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 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
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
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 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
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 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
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
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
543 Pidgin allows for interaction via D-Bus. Currently very little docu‐
544 mentation about this interaction exists.
545
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
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
566 The bug tracker can be reached by visiting http://developer.pid‐
567 gin.im/query
568 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
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 You are also encouraged to drop by at #pidgin on irc.freenode.net to
581 discuss development.
582
586 http://pidgin.im/
587 http://developer.pidgin.im/
588 purple-remote(1)
589 finch(1)
590
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 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 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
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 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 Our artists are:
649 Hylke Bons <h.bons@student.rug.nl>
650 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 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 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>.
677Pidgin v2.14.1 pidgin(1)