If you want to use PluralKit on a Discord server, you must first *add* it to the server in question. For this, you'll need the *Manage Server* permission on there.
Once you go through the wizard, the bot account will automatically join the server you've chosen. Please ensure the bot has the *Read Messages*, *Send Messages*, *Send Messages in Threads*, *Manage Messages*, *Attach Files*, and *Manage Webhooks* permission in the channels you want it to work in.
In order to do most things with the PluralKit bot, you'll need to have a system registered with it. A *system* is a collection of *system members* that may be used by one or more *Discord accounts*.
### Creating a system
If you do not already have a system registered, use the following command to create one:
pk;system new
Optionally, you can attach a *system name*, which will be displayed in various information cards, like so:
pk;system new My System Name
### Viewing information about a system
To view information about your own system, simply type:
pk;system
To view information about *a different* system, there are a number of ways to do so. You can either look up a system by @mention, by account ID, or by system ID. For example:
If you want to change the name of your system, you can use the `pk;system rename` command, like so:
pk;system rename New System Name
### System server names
If you'd like to set a name for your system, but only for a specific server, you can set the system's *server display name*. This shows up in replacement of the server name in the server you set it in. For example:
pk;system servername Name For This Server
To clear your system servername for a server, simply run `pk;system servername clear` in in the server in question. The servername cannot be run in DMs, it only applies to servers.
If you'd like to add a small blurb to your system information card, you can add a *system description*. To do so, use the `pk;system description` command, as follows:
pk;system description This is my system description. Hello. Lorem ipsum dolor sit amet.
There's a 1000 character length limit on your system description - which is quite a lot!
If you'd like to remove your system description, just type `pk;system description` without any further parameters.
If you'd like your system to have an associated "system avatar", displayed on your system information card, you can add a system avatar. Your system avatar will also show up as the avatar on members who do not have their own when proxying. To do so, use the `pk;system avatar` command. You can either supply it with an direct URL to an image, or attach an image directly. For example.
If you'd like your system to have an avatar (as above), but only for a specific server, you can set the *system server avatar*. This will override the global system avatar, but only in the server you set it in. For example:
To clear your system serveravatar for a server, simply type `pk;system serveravatar clear` with no attachment or link in the server in question. The serveravatar command cannot be run in DMs, it only functions in servers.
If you'd like to set a system tag (as above), but only for a specific server, you can set the *system server tag*. This will override the global system tag, but only in the server you set it in. For example:
### Adding or removing Discord accounts to the system
If you have multiple Discord accounts you want to use the same system on, you don't need to create multiple systems.
Instead, you can *link* the same system to multiple accounts.
Let's assume the account you want to link to is called @Craig#5432. You'd link it to your *current* system by running this command from an account that already has access to the system:
pk;link @Craig#5432
PluralKit will require you to confirm the link by clicking on a reaction *from the other account*.
If you now want to unlink that account, use the following command:
pk;unlink @Craig#5432
You may not remove the only account linked to a system, as that would leave the system inaccessible. Both the `pk;link` and `pk;unlink` commands work with account IDs instead of @mentions, too.
### Setting a system time zone
PluralKit defaults to showing dates and times in [UTC](https://en.wikipedia.org/wiki/Coordinated_Universal_Time).
If you'd like, you can set a *system time zone*, and as such every date and time displayed in PluralKit
You can also search by country code, either by giving the two-character [*ISO-3166-1 alpha-2* country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) (e.g. `GB` or `DE`), or just by a country flag emoji (e.g. `:flag_gb:` 🇬🇧 or `:flag_de:` 🇩🇪).
Most member commands follow the format of `pk;member MemberName verb Parameter`. Note that if a member's name has multiple words, you'll need to enclose it in "double quotes" throughout the commands below (_except_ for `pk;member new`).
::: tip
For all member commands, you can use either the member name, the member display name, or the member ID to refer to the member.
You can't do much with PluralKit without having registered members with your system, but doing so is quite simple - just use the `pk;member new` command followed by the member's name, like so:
To view information about a member, there are a couple ways to do it. Either you can address a member by their name (if they're in your own system), by their 5 or 6 letter *member ID*, or by their *display name*, like so:
Member IDs are the only way to address a member in another system, and you can find it in various places - for example the system's member list, or on a message info card gotten by reacting to messages with a question mark.
### Listing system members
To list all the members in a system, use the `pk;system list` command. This will show a paginated list of all member names in the system. You can either run it on your own system, or another - like so:
pk;system list
pk;system @Craig#5432 list
pk;system qazws list
If you want a more detailed list, with fields such as pronouns and description, add the word `full` to the end of the command, like so:
pk;system list full
pk;system @Craig#5432 list full
pk;system qazws list full
### Member renaming
If you want to change the name of a member, you can use the `pk;member rename` command, like so:
you may want to display a different name. For example, you may want to include a member's pronouns inside the proxied name,
indicate a subsystem, include emojis or symbols that don't play nice with the command syntax, or just in general show a different name from the member's "canonical" name.
In such cases you can set the member's *display name*. Which will, well, display that name instead. You can set
a display name using the `pk;member displayname` command, like so:
pk;member John displayname Jonathan
pk;member Robert displayname Bob (he/him)
To remove a display name, just use the same command with no last parameter, eg:
pk;member John displayname
This will remove the display name, and thus the member will be proxied with their canonical name.
If you want your member to have an associated avatar to display on the member information card and on proxied messages, you can set the member avatar. To do so, use the `pk;member avatar` command. You can either supply it with an direct URL to an image, or attach an image directly. For example.
pk;member John avatar http://placebeard.it/512.jpg
If you want your member to have a different avatar for proxies messages than the one displayed on the member card, you can set a proxy avatar. To do so, use the `pk;member proxyavatar` command, in the same way as the normal avatar command above:
pk;member John avatar
pk;member John proxyavatar http://placebeard.it/512.jpg
pk;member "Craig Johnson" proxyavatar (with an attached image)
You can also set an avatar for a specific server. This will "override" the normal avatar, and will be used when proxying messages and looking up member cards in that server. To do so, use the `pk;member serveravatar` command, in the same way as the normal avatar command above:
pk;member John serveravatar
pk;member John serveravatar http://placebeard.it/512.jpg
pk;member "Craig Johnson" serveravatar (with an attached image)
If you want to list a member's preferred pronouns, you can use the pronouns field on a member profile. This is a free text field, so you can put whatever you'd like in there (with a 100 character limit), like so:
If you want to list a member's birthdate on their information card, you can set their birthdate through PluralKit using the `pk;member birthdate` command. Please use [ISO-8601 format](https://xkcd.com/1179/) (`YYYY-MM-DD`) for best results, like so:
pk;member John birthdate 1996-07-24
pk;member "Craig Johnson" birthdate 2004-02-28
You can also set a birthdate without a year, either in `MM-DD` format or `Month Day` format, like so:
If you want to delete a member, use the `pk;member delete` command, like so:
pk;member John delete
You'll need to confirm the deletion by replying with the member's ID when the bot asks you to - this is to avoid accidental deletion.
## Proxying
Proxying is probably the most important part of PluralKit. This allows you to essentially speak "as" the member,
with the proper name and avatar displayed on the message. To do so, you must at least [have created a member](#creating-a-system).
### Setting up proxy tags
You'll need to register a set of *proxy tags*, which are prefixes and/or suffixes you "enclose" the real message in, as a signal to PluralKit to indicate
which member to proxy as. Common proxy tags include `[square brackets]`, `{curly braces}` or `A:letter prefixes`.
To set a proxy tag, use the `pk;member proxy` command on the member in question. You'll need to provide a "proxy example", containing the word `text`.
For example, if you want square brackets, the proxy example must be `[text]`. If you want a letter or emoji prefix, make it something like `A:text` or `🏳️🌈:text`. For example:
You can now type a message enclosed in / prefixed by your proxy tags, and it'll be deleted by PluralKit and reposted with the appropriate member name and avatar (if set).
Prefix tags don't have to use `:`. You can have suffix-only tags if you want. `Unknown` in this example uses both. <br>
Just make sure the tag isn't something you'll use in regular messages without intending to proxy as that member, like how `Unknown` uses a double shrug emoji rather than a single shrug that someone else might type.
If you'd like to proxy a member in multiple ways (for example, a name or a nickname, uppercase and lowercase variants, etc.), you can add multiple tags.
Using the `pk;member proxy` command without `add` will **replace** the proxy tag(s) for that member. PluralKit will respond with a warning about this, and won't do it unless you click the `Replace` button on that message.
If you'd like your proxied messages to be sent as text-to-speech messages (read off out loud to anyone who has the channel focused) you can enable the text-to-speech option for a given member, like so:
pk;member John text-to-speech on
Turning the option off is similar - replace "on" with "off" in the command. The default value for every member is off. If you are not allowed to send text-to-speech messages in a server, this feature will not work.
Since the messages will be posted by PluralKit's webhook, it's not possible to edit, delete, or change the message as you would a normal user message. However, PluralKit has commands for that.
#### Editing messages
To edit a PluralKit-proxied message, reply to it with the command `pk;edit` with the replacement text.
If you want to edit your last message in this channel, you can leave out the reply.
For example:
Helo, friends!
pk;e Hello, friends!
#### Reproxying messages
If you accidentally used the wrong proxy tag, or are using [autoproxy](#autoproxy) and forgot about your latch/switch status, reply to it with the command `pk;reproxy <member name>`.
If you want to reproxy your last message in this channel, you can leave out the reply.
For example:
a: Hi, this is Sky.
pk;rp Skyler
will change the first message from:
Alice: Hi, this is Sky.
to:
Sky (he/him): Hi, this is Sky.
::: warning
- You must use the full member name, *not* their proxy tags.
- This only works on the last message in the channel, or a message sent within the last 1 minute.
- This does not work on a message you sent as your actual user account (i.e. one you didn't proxy).
:::
#### Deleting messages
To delete a PluralKit-proxied message, react to it with the `:x:` :x: emoji, or use the `pk;message -delete` command.
### Anyone's messages
#### Querying message information
If you want information about a proxied message (e.g. for moderation reasons), you can query the message for its sender account, system, member, etc.
You can
* react to the message itself with the `:question:` :question: or `:grey_question:` :grey_question: or emoji, which will DM you information about the message in question,
* reply to the mssage with `pk;message`, or
* use the `pk;message` command followed by [the message's ID](https://support.discord.com/hc/en-us/articles/206346498-Where-can-I-find-my-User-Server-Message-ID-).
#### Pinging the user who sent it
If you'd like to "ping" the account behind a proxied message without having to query the message and ping them yourself,
you can react to the message with the `:bell:` :bell: emoji (or `:bellhop:` :bellhop:, `:exclamation:` :exclamation:, or even `:ping_pong:` :ping_pong:), and PluralKit will ping the relevant member and account in the same channel on your behalf with a link to the message you reacted to.
The bot's *autoproxy* feature allows you to have messages be proxied without directly including the proxy tags. Autoproxy can be set up in various ways. There are three autoproxy modes currently implemented:
To see your system's current autoproxy settings, simply use the command:
This autoproxy mode will proxy messages as the current *first* fronter of the system. If you register a switch with `Alice` and `Bob`, messages without proxy tags will be autoproxied as `Alice`.
To enable front-mode autoproxying for a given server, use the following command:
pk;autoproxy front
#### Latch mode
This autoproxy mode will essentially "continue" previous proxy tags. If you proxy a message with `Alice`'s proxy tags, messages posted afterwards will be proxied as Alice. Proxying again with someone else's proxy tags, say, `Bob`, will cause messages *from then on* to be proxied as Bob.
In other words, it means proxy tags become "sticky". This will carry over across all channels in the same server.
To enable latch-mode autoproxying for a given server, use the following command:
To enable member-mode autoproxying for a given server, use the following command, where `<member>` is a member name (in "quotes" if multiple words), or 5 or 6 character ID:
### Disabling front/latch autoproxy on a per-member basis
If a system uses front or latch mode autoproxy, but one member prefers to send messages through the account (and not proxy), you can disable the front and latch modes for that specific member.
pk;member <name> autoproxy off
To re-enable front / latch modes for that member, use the following command:
pk;member <name> autoproxy on
This will *not* disable member mode autoproxy. If you do not wish to autoproxy, please turn off autoproxy instead of setting autoproxy to a specific member.
It is possible to fully disable autoproxy for a certain account linked to your system. For example, you might want to do this if a specific member's name is shown on the account.
To disable autoproxy for the current account, use the following command:
If you want to log a switch with *no* members, you can log a switch-out as follows:
pk;switch out
### Moving switches
If you want to log a switch that happened further back in time, you can log a switch and then *move* it back in time, using the `pk;switch move` command.
You can either specify a time either in relative terms (X days/hours/minutes/seconds ago) or in absolute terms (this date, at this time).
Absolute times will be interpreted in the [system time zone](#setting-a-system-time-zone). For example:
To see the current fronter in a system, use the `pk;system fronter` command. You can use this on your current system, or on other systems. For example:
pk;system fronter
pk;system @Craig#5432 fronter
pk;system qazws fronter
### Querying front history
To look at the front history of a system (currently limited to the last 10 switches). use the `pk;system fronthistory` command, for example:
pk;system fronthistory
pk;system @Craig#5432 fronthistory
pk;system qazws fronthistory
### Querying front percentage
To look at the per-member breakdown of the front over a given time period, use the `pk;system frontpercent` command. If you don't provide a time period, it'll default to 30 days. For example:
pk;system frontpercent
pk;system @Craig#5432 frontpercent 7d
pk;system qazws frontpercent 100d12h
Note that in cases of switches with multiple members, each involved member will have the full length of the switch counted towards it. This means that the percentages may add up to over 100%.
<br> It is possible to disable this with the `-flat` flag; percentages will then add up to 100%.
::: tip
If you use the `switch-out` function, the time when no-one was fronting will show up in front history as "no fronter". To disable this, use the `-fronters-only`, or `-fo` flag:
There are various reasons you may not want information about your system or your members to be public. As such, there are a few controls to manage which information is publicly accessible or not.
Each of these can be set to **public** or **private**. When set to **public**, anyone who queries your system (by account or system ID, or through the API), will see this information. When set to **private**, the information will only be shown when *you yourself* query the information. The cards will still be displayed in the channel the commands are run in, so it's still your responsibility not to pull up information in servers where you don't want it displayed.
To update your system privacy settings, use the following commands:
When the **member list** is **private**, other users will not be able to view the full member list of your system, but they can still query individual members given their 5-letter ID. If **current fronter** is private, but **front history** isn't, someone can still see the current fronter by looking at the history (this combination doesn't make much sense).
As with system privacy, each can be set to **public** or **private**. The same rules apply for how they are shown, too. When set to **public**, anyone who queries your system (by account or system ID, or through the API), will see this information. When set to **private**, the information will only be shown when *you yourself* query the information. The cards will still be displayed in the channel the commands are run in, so it's still your responsibility not to pull up information in servers where you don't want it displayed.
- When the **name** is set to private, it will be replaced by the member's **display name**, but only if they have one! If the member has no display name, **name privacy will not do anything**. PluralKit still needs some way to refer to a member by name :)
- When **visibility** is set to private, the member will not show up in member lists unless `-all` is used in the command (and you are part of the system).
- Visibility *(whether the group shows up on member cards)*
As with system and member privacy, each can be set to **public** or **private**. The same rules apply for how they are shown, too. When set to **public**, anyone who queries your system (by account or system ID, or through the API), will see this information. When set to **private**, the information will only be shown when *you yourself* query the information. The cards will still be displayed in the channel the commands are run in, so it's still your responsibility not to pull up information in servers where you don't want it displayed.
As with member privacy, there are two catches:
- When the **name** is set to private, it will be replaced by the group's **display name**, but only if they have one! If the group has no display name, **name privacy will not do anything**. PluralKit still needs some way to refer to a group by name :)
- When **visibility** is set to private, the group will not show up in group lists unless `-all` is used in the command (and you are part of the system).
To update a group's privacy, you can use the command:
If you're a user of another proxy bot (e.g. Tupperbox), or you want to import a saved system backup, you can use the importing and exporting commands. Note, if you are on a mobile device, using the links is recommended - using the .json file from either bot may not work as Discord tends to break the file on download/upload.
Note that while Tupperbox supports features such as per-member system tags, PluralKit does not. PluralKit also does not currently support importing or exporting member groups.
To export all the data associated with your system, run the `pk;export` command. This will send you a JSON file containing your system, member, and switch information.
