pidgin(1)

💖 pidgin(1) 💖

General Commands Manual — the iconic one, the blueprint, the moment

okay bestie, sit down, hydrate, because we're about to go through the whole pidgin manual together and it's a lot but I got you 💅

---

🎀 NAME 🎀

pidgin — it's an Instant Messaging client. that's it, that's the whole name section, she's concise ✨

---

🦋 SYNOPSIS 🦋

pidgin [options]

---

🌸 DESCRIPTION 🌸

okay so pidgin is a graphical modular messaging client built on top of libpurple, and the way it just... connects to XMPP, IRC, SILC, Novell GroupWise, Lotus Sametime, Zephyr, Gadu-Gadu, and QQ all at once?? main character energy fr fr 👑

It's got so many of the common features you'd find in other clients, plus a whole bunch of unique features that are just hers. no cap.

And she's extensible — Pidgin can be extended by plugins written in multiple programming languages, and she can be controlled through DBus or purple-remote. slay.

---

👑 OPTIONS 👑

The following options are provided by Pidgin using the standard GNU command line syntax — so yes bestie, the classics, we love consistency 💖

• -c, --config=DIR — use DIR as the directory for config files instead of ~/.purple. relocating your whole setup, iconic.
• -d, --debug — prints debugging messages to stdout. and ngl these are literally the same debugging messages that show up in the Debug Window, so you're not missing anything.
• -f, --force-online — tries to be online even if the network is reported (by Windows, or by NetworkManager on Linux) to be unavailable. manifesting connectivity ✨
• -h, --help — prints a summary of command line options and exits. the "help me bestie" flag 🫶
• -m, --multiple — allows multiple instances of Pidgin to run. chaos permitted, multiple Pidgins, multiple vibes.
• -n, --nologin — doesn't automatically login when Pidgin starts, and sets the global status to Offline. quiet mode. introvert mode. valid.
• -l, --login[=NAME,NAME,...] — enables the comma-separated list of accounts you give it, and disables all the other accounts. if you don't give a comma-separated list, the first account in accounts.xml will be enabled. choose wisely 💀
• -v, --version — prints the current version and exits. quick lil vibe check.

---

💜 TERMS 💜

Pidgin uses a few terms differently from other applications. for convenience, they're defined right here, so you're never lost in the group chat:

• Buddy List — the list of other users who the user wants to see status information for and have quick access to for messaging.
• Buddy — a user who has been added to the Buddy List.
• Contact — a grouping of more than one buddy who are all the same person. a contact may contain buddies from any protocol and may contain as many buddies as the user desires. contact arrangements are stored locally only.
• Alias — a private "nickname" that may be set for Buddies or the user himself. on some protocols, aliases are saved on the server but not visible to other users. on other protocols, aliases are saved only locally.
• Protocol — a messaging service. XMPP, Zephyr, etc. are protocols. others may call these "service types," "account types," "services," and so on.

---

🐝 BUDDY LIST 🐝

The Buddy List window is Pidgin's main interface window — she's the home screen, the hub, the whole personality. Using this window a user can see which of his/her buddies is online, away, idle, etc. The user can also add buddies to and remove buddies from the buddy list. managing your social ecosystem, we love to see it 🌈

The Buddy List window contains a list of the user's buddies who are online and have allowed the user to be notified of their presence. the icon to the left of each buddy indicates the buddy's current status. double clicking a buddy will open a new Conversation window. right clicking will pop up a menu:

• Get Info — retrieves and displays information about the buddy. this information is also known as a Profile.
• IM — opens a new Conversation window to the selected buddy.
• Send File — sends a file to the selected buddy (only available on protocols that support file transfer).
• Add Buddy Pounce — a Buddy Pounce is a configurable automated action to be performed when the buddy's state changes. this will open the Buddy Pounce dialog, which will be discussed later.
• View Log — Pidgin is capable of automatically logging messages. these logs are either plain text files (with a .txt extension) or html files (with a .html extension) located under the ~/.purple/logs directory. this menu command will display Pidgin's log viewer with logs loaded for that buddy or chat.
• Alias — create an alias for this buddy. this will show an editable text field where the buddy's name was displayed. in this field one can give this buddy an alternate, more friendly name to appear on the buddy list and in conversations.

for example, if a buddy's name was jsmith1281xx and his real name was 'John Q. Smith,' one could create an alias as to identify the buddy by his common name.

The remainder of the menu will consist of protocol specific commands. these commands vary depending on the protocol.

• Status Selector — at the bottom of the Buddy List is a status selector which allows one to change his/her status. this will be discussed further in the STATUS MESSAGES section below.

---

💅 ACCOUNT EDITOR 💅

The account editor consists of a list of accounts and information about them. it can be accessed by selecting Manage from the Accounts menu. clicking Delete will delete the currently selected account. clicking Add or Modify will invoke a Modify Account window. here, the user can add or alter account information. when creating a new account, the user will submit a username and password. the user will also choose the protocol for the account.

If Remember Password is chosen, the password will be saved in Pidgin's ~/.purple/accounts.xml configuration file.

If Enabled is checked in the accounts dialog, this account will follow the status currently selected in the status selector. if it is not checked, the account will always be offline. (yes bestie, always. permanent ghost mode 👻)

Each protocol has its own specific options that can be found in the modify screen.

---

🌈 PREFERENCES 🌈

All options take effect immediately. no save button, no confirm dialog, just vibes in real time ✨

Interface

• Show system tray icon — specifies when to show a Pidgin icon in the notification area of the user's panel (commonly referred to as the System Tray).
• Hide new IM conversations — specifies when to hide new IM messages. messages will queue under the specified condition until shown. clicking the Pidgin icon in the notification area or system tray will display the queued messages. an icon also appears in the buddy list's menu bar; this icon may also be used to display queued messages.
• Show IMs and chats in tabbed windows — when checked, this option will cause IM and chat sessions to appear in windows with multiple tabs. one tab will represent one conversation or chat. where tabs are placed will be dictated by the preferences below.
• Show close buttons on tabs — when checked, this option will cause a clickable U+2715 MULTIPLICATION X unicode character to appear at the right edge of each tab. clicking this will cause the tab to be closed.
• Placement — specifies where to place tabs in the window. some tab orientations may allow some users to fit more tabs into a single window comfortably.
• New conversations — specifies under which conditions tabs are placed into existing windows or into new windows. for a single window, select Last created window here.

Conversations

• Enable buddy icon animation — if a buddy's icon happens to be animated, this option will enable the animation, otherwise only the first frame will be displayed.
• Notify buddies that you are typing to them — some protocols allow clients to tell their buddies when they are typing. this option enables this feature for protocols that supports it.
• Default Formatting — allows specifying the default formatting to apply to all outgoing messages (only applicable to protocols that support formatting in messages).

Smiley Themes

Allows the user to choose between different smiley themes. the "none" theme will disable graphical emoticons — they will be displayed as text instead. the Add and Remove buttons may be used to install or uninstall smiley themes. themes may also be installed by dragging and dropping them onto the list of themes. so satisfying honestly 🍓

Sounds

• Method — lets the user choose between different playback methods. the user can also manually enter a command to be executed when a sound is to be played (%s expands to the full path to the file name).
• Sounds when conversation has focus — when checked, sounds will play for events in the active conversation if the window is focused. when unchecked, sounds will not play for the active conversation when the window is focused.
• Enable Sounds — determines when to play sounds.
• Sound Events — lets the user choose when and what sounds are to be played.

Network

• STUN server — this allows specifying a server which uses the STUN protocol to determine a host's public IP address. this can be particularly useful for some protocols.
• Autodetect IP address — when checked, causes Pidgin to attempt to determine the public IP address of the host on which Pidgin is running and disables the Public IP text field listed below.
• Public IP — if Autodetect IP address is disabled, this field allows manually specifying the public IP address for the host on which Pidgin is running. this is mainly useful for users with multiple network interfaces or behind NATs.
• Manually specify range of ports to listen on — specify a range ports to listen on, overriding any defaults. this is sometimes useful for file transfers and Direct IM.
• Proxy Server — the configuration section to enable Pidgin to operate through a proxy server. Pidgin currently supports SOCKS 4/5 and HTTP proxies.

Browser

• Browser — allows the user to select Pidgin's default web browser. Firefox, Galeon, Konqueror, Mozilla, Netscape and Opera are supported natively. the user can also manually enter a command to be executed when a link is clicked (%s expands to the URL). for example, xterm -e lynx "%s" will open the link with lynx.
• Open link in — allows the user to specify whether to use an existing window, a new tab, a new window, or to let the browser to decide what to do when calling the browser to open a link. which options are available will depend on which browser is selected.

---

and that's part one bestie, don't go anywhere, there's more coming 💖

Logging 💾

• Log format — tells Pidgin how to log. Pidgin itself does HTML and plain text, but bestie, plugins can absolutely come through with other logging methods. options on options ✨
• Log all instant messages — turn this on and every single IM convo gets logged. You can override it per-conversation in the conversation window, so no, you're not trapped. 🫶
• Log all chats — same deal but for chats: flip it on and all chat conversations are logged. Also overridable on a per-conversation basis in the conversation window. 💅
• Log all status changes to system log — when enabled, status changes get logged. That's it, that's the whole thing. 👑

---

Status / Idle 😴

• Report idle time — decides when idle time gets reported, like under which conditions. Three flavors:
  • Based on keyboard and mouse use — uses your keyboard and mouse activity to figure out idle time. Classic.
  • From last sent message — uses the time at which you last sent a message in Pidgin to determine idle. So if you're lurking, it knows. 🙈
  • Never — disables idle reporting. completely. no idle era. 💀
• Change status when idle — enable this and it uses the Minutes before becoming idle and Change status to preferences (described right below, iykyk) to set your status on idle.
• Minutes before becoming idle — how many minutes of inactivity before Pidgin considers you idle. Pick your number, bestie.
• Change status to — which "primitive" or "saved" status to use when setting status on idle.
• Use status from last exit at startup — if this is checked, Pidgin remembers what status was active when you closed Pidgin and restores it on the next run. When it's disabled, Pidgin will always set the status selected in Status to apply at startup at startup. memory loss era vs. consistency era 🌸
• Status to apply at startup — when Use status from last exit at startup is disabled, this is the one that specifies which "primitive" or "saved" status to use at startup. 🎀

---

CONVERSATIONS 💬

When you start a new conversation, boom, you get the Conversation window. The conversation itself shows up in the upper text box, and you type your message in the lower text box. Between the two there's a whole row of options represented by icons. Heads up though: some or all of these buttons may not be active if the protocol doesn't support that specific formatting. Not everything is for everyone, and that's fine. 🦋

From left to right:

• Font — this menu gives you font control options for the current conversation. Size, style, and face all get configured right here. aesthetic customization ✨
• Insert — this menu lets you insert images, horizontal rules, and links, wherever the protocol supports each of those features. Keyword: where it supports it. 👀
• Smile! — lets you insert graphical smileys via the mouse. Clicking it shows you a dialog with all the available smileys for the current conversation. smiley selection slay 😭💖

---

CHATS 🫂

For protocols that allow it, Chats can be entered through the Buddies menu. Periodt.

Extra features available in chat, depending on the protocol, are:

• Whisper — the text will appear in the chat conversation, but it will only be visible to the sender and the receiver. Sneaky little side-chat energy. 🤫
• Invite — invite other people to join the chat room. Pull up, bestie. 🫶
• Ignore — ignore anything said by the chosen person. Not me silencing the chaos. 💀
• Set Topic — set the topic of the chat room. This is usually a brief sentence describing the nature of the chat — basically an explanation of the chat room's name.
• Private Message (IM) — send a message to a specific person in the chat. Messages sent this way will not appear in the chat window; instead they open a new IM conversation. separate chat, separate vibe 🦋

---

STATUS MESSAGES 📢

Most protocols allow for status messages, and by using them you can leave an informative message for others to see. Status and status messages are configured via the status selector at the bottom of the Buddy List window. By default the menu shown here is divided into sections:

1. Sections for "primitive" status types, such as Available, Away, etc.
2. A few "popular" statuses (including "transient" statuses) which have been recently used.
3. A section which shows New Status... and Saved Statuses... options for more advanced status manipulation. advanced girlies, this one's for you ✨

---

Primitive Statuses 🧱

A primitive status is a basic status supported by the protocol. Examples of primitive statuses would be Available, Away, Invisible, etc. A primitive status can be used to create a Transient Status or a Saved Status, both explained below. Essentially, primitive statuses are the building blocks of more complicated statuses. lego but for vibes 🎀

Transient Statuses 🌈

When one of the statuses from the topmost section of the status selector's menu is selected, this creates a transient, or temporary, status. The status will show in the "popular statuses" section in the menu until it has not been used for a sufficiently long time. A transient status may also be created by selecting New Status... from the status selector's menu, then clicking Use once the user has entered the message. Temporary but iconic. 💅

Saved Statuses 💾

Saved statuses are permanent — once created, they will exist until deleted. Saved statuses are useful for statuses and status messages that will be used on a regular basis. They are also useful for creating complex statuses in which some accounts should always have a different status from others. For example, one might wish to create a status called "Sleeping" that has all accounts set to "Away", then create another status called "Working" that has three accounts set to "Away" and another account set to "Available." multi-account main character energy 👑

New Status Window 🪟

When the user selects New Status... from the status selector menu, Pidgin presents the user with a dialog asking for status-related information. That information is discussed below:

• Title — the name of the status that will appear in the status selctor's menu. If the user clicks the Save or Save & Use button, this name will also be shown in the Saved Status Window. The title should be a short description of the status.
• Status — the type of status being created, such as Available, Away, etc.
• Message — the content of the status message. This is what is visible to other users. Some protocols will allow formatting in some status messages; where formatting is not supported it will be stripped to the bare text entered.
• Use a different status for some accounts — this allows the creation of complex statuses in which some accounts' status differs from that of other accounts. To use this, the user will click the expander to the left of the text, then select individual accounts which will have a different status and/or status message. When the user selects an account, Pidgin will present another status dialog asking for a status and a message just for the selected account. per-account customization, obsessed 🦋

Saved Status Window 🗂️

When the user selects Saved Statuses... from the status selector's menu, Pidgin presents a dialog that lists all saved statuses. "Transient" statuses, discussed above, are NOT shown here. This window provides the ability to manage saved statuses by allowing the creation, modification, and deletion of saved statuses. The Use, Modify, and Delete buttons here allow operation on the status selected from the list; the dd button allows creation of a new saved status, and the Close button closes the window.

---

BUDDY POUNCE 🐾

A Buddy Pounce is an automated trigger that occurs when a buddy returns to a normal state from an away state. The Buddy Pounce dialog box can be activated by selecting the Buddy Pounce option from the Tools menu.

From this dialog, new pounces can be created with the Add button and existing pounces can be removed with the Delete button. A pounce can be set to occur on any combination of the events listed, and any combination of actions can result. combinatorial chaos, we love her ✨

If Pounce only when my status is not Available is checked, the pounce will occur only if the user is set to a non-available status, such as invisible, do not disturb, away, etc. If Recurring is checked, the pounce will remain until removed by the Delete button. It's giving "it's not a phase, it's recurring." 💀

---

CUSTOM SMILIES 😍

Pidgin 2.5.0 introduced support for custom smilies on those protocols for which interested contributors have developed support. The custom smiley manager can be accessed by selecting Smiley from the Tools menu. From here, custom smilies may be added, edited, or deleted by clicking the Add, Edit, or Delete buttons, respectively. smiley manager era 🎀

During a conversation with another user, that user's custom smileys may be added to the user's own custom smiley list directly from the conversation window by right-clicking the new custom smiley and selecting Add Custom Smiley... Steal their smileys, legally, right-click style. 🫶

---

PLUGINS 🧩

Pidgin allows for dynamic loading of plugins to add extra functionality to Pidgin. See plugins/HOWTO or http://developer.pidgin.im/wiki/CHowTo for information on writing plugins.

The plugins dialog can be accessed by selecting Plugins from the Tools menu. Each plugin available appears in this dialog with its name, version, and a short summary of its functionality. Plugins can be enabled with the checkbox beside the name and short description. More information on the currently selected plugin is available by clicking the expander beside the text Plugin Details. If the selected plugin has preferences or configuration options, the Configure Plugin button will present the plugin's preferences dialog. plugin ecosystem slay 💅

---

PERL 🐪

Pidgin allows for plugins to be written in the perl scripting language. See Perl Scripting HOWTO in the Pidgin documentation for more information about perl scripting.

---

TCL 🧚

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

---

D-Bus 🚌

Pidgin allows for interaction via D-Bus. Currently very little documentation about this interaction exists. mysterious, undocumented, lowkey iconic 👀

---

FILES 📁

/usr/bin/pidgin: Pidgin's location.
~/.purple/blist.xml: the buddy list.
~/.purple/accounts.xml: information about the user's accounts.
~/.purple/pounces.xml: stores the user's buddy pounces.
~/.purple/prefs.xml: Pidgin's configuration file.
~/.purple/status.xml: stores the user's away messages.
~/.purple/logs/PROTOCOL/ACCOUNT/BUDDYNAME/DATE.{html,txt}:
conversation logs.

---

DIRECTORIES 🗄️

/usr/lib/pidgin/: Pidgin's plugins directory.
/usr/lib/purple-2/: libpurple's plugins directory.
~/.purple: users' local settings
~/.purple/plugins/: users' local plugins

🐛 BUGS 🐛

okay so if you found a bug (rip 💀) the bug tracker lives at http://developer.pidgin.im/query — go yell there, it's the whole point of it.

But bestie, please, before you send that bug report, make sure you're actually on the latest version of Pidgin. fr fr. So many bugs — the big dramatic ones and the tiny annoying ones — get fixed every single release, and if your copy is out of date, the thing you're mad about might already be solved. check first, then complain. it's giving responsible 💅

---

🩹 PATCHES 🩹

Oh you fixed something?? Not me being proud of you 🥹 If you fix a bug in Pidgin (or you know, just make it better in general), submit a patch at http://developer.pidgin.im/simpleticket. And listen, make that patch with:

mtn diff > my.diff

against the latest version from the Monotone repository. yes, Monotone. iconic of them.

You're also so encouraged to come hang out in #pidgin on irc.libera.chat to talk development. we're friendly, come thru 🫶

---

👀 SEE ALSO 👀

• http://pidgin.im/
• http://developer.pidgin.im/
• purple-remote(1)
• finch(1)

---

📜 LICENSE 📜

kay so legally speaking, here's the whole vibe:

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

okay that part is not a joke, that's the actual legal text and it means what it says — no warranty, none, zero 🙈

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA

---

👑 AUTHORS 👑

Not me about to list every single legend who made this happen. the roster is long and every one of them ate 💖

✨ Pidgin's active developers are:

• Daniel 'datallah' Atallah (developer)
• Paul 'darkrain42' Aurich (developer)
• John 'rekkanoryo' Bailey (developer and bugmaster)
• Ethan 'Paco-Paco' Blanton (developer)
• Thomas Butter (developer)
• Ka-Hing Cheung (developer)
• Sadrul Habib Chowdhury (developer)
• Mark 'KingAnt' Doliner (developer) <thekingant@users.sourceforge.net>
• Sean Egan (developer) <seanegan@gmail.com>
• Casey Harkins (developer)
• Ivan Komarov
• Gary 'grim' Kramlich (developer)
• Richard 'rlaager' Laager (developer) <rlaager@pidgin.im>
• Sulabh 'sulabh_m' Mahajan (developer)
• Richard 'wabz' Nelson (developer)
• Christopher 'siege' O'Brien (developer)
• Bartosz Oler (developer)
• Etan 'deryni' Reisner (developer)
• Tim 'marv' Ringenbach (developer) <marv_sf@users.sf.net>
• Michael 'Maiku' Ruprecht (developer, voice and video)
• Elliott 'QuLogic' Sales de Andrade (developer)
• Luke 'LSchiere' Schierer (support)
• Megan 'Cae' Schneider (support/QA)
• Evan Schoenberg (developer)
• Kevin 'SimGuy' Stange (developer and webmaster)
• Will 'resiak' Thompson (developer)
• Stu 'nosnilmot' Tomlinson (developer)
• Nathan 'faceprint' Walp (developer)

🌸 Our crazy patch writers include:

• Marcus 'malu' Lundblad
• Dennis 'EvilDennisR' Ristuccia
• Peter 'fmoo' Ruibal
• Gabriel 'Nix' Schulhof
• Jorge 'Masca' Villaseñor

🎨 Our artists are:

• Hylke Bons <h.bons@student.rug.nl>

🫡 Our retired developers are:

• Herman Bloggs (win32 port) <herman@bluedigits.com>
• Jim Duchek <jim@linuxpimps.com> (maintainer)
• Rob Flynn <gaim@robflynn.com> (maintainer)
• Adam Fritzler (libfaim maintainer)
• Christian 'ChipX86' Hammond (developer & webmaster) <chipx86@chipx86.com>
• Syd Logan (hacker and designated driver [lazy bum])
• Jim Seymour (XMPP developer)
• Mark Spencer (original author) <markster@marko.net>
• Eric Warmenhoven (former lead developer) <eric@warmenhoven.org>

💜 Our retired crazy patch writers include:

• Felipe 'shx' Contreras
• Decklin Foster
• Peter 'Bleeter' Lawler
• Robert 'Robot101' McQueen
• Benjamin Miller

✍️ This manpage...

This manpage was originally written by Dennis Ristuccia <dennis@dennisr.net>. It has been updated and largely rewritten by Sean Egan <seanegan@gmail.com>, Ben Tegarden <tegarden@uclink.berkeley.edu>, and John Bailey <rekkanoryo@pidgin.im>.

---

and that's the whole page, bestie 🎀💖✨

This is pidgin(1) from Pidgin v2.14.14 — that's the version stamped on this page, so if your pidgin isn't saying that, go update and come back. love u, go fix a bug and submit a patch 💅🦋