RPG Sage:
Command Guide

Quick Notes

Most are also NOT case sensitive.


Brackets {} are for emphasis, either showing you where to put information (such as a name) or listing values you can choose from ({GameAdmin|ServerAdmin|SageAdmin}). Don't use them in your commands.
    DO: sage! help dialog
    DON'T: sage! help {dialog}
Long replies (those that require more than 2 actual messages sent) often are sent by DM.
Commands that expect a boolean value (true or false) accept the following: true, t, 1 or false, f, 0
Many of the commands do not require spaces sage!dcsbylevel and sage! dcs by level should work the same.

1. Inviting RPG Sage

Sage asks for various permissions needed to function as expected:
some features are still in development

2. Command Types

The primary ways in which you will interact with Sage are through commands. Sage has four types of commands that it responds to:

Dialog and Dice commands will be discussed later.

    2a. Message Commands

Message Commands are commands given to Sage by posting a message into chat, either a channel where Sage has access or via a direct message to Sage.

To further understand a Message Command, think of them as having the following components: Prefix, Action, Command, SubCommands, and Arguments.

  • Prefix is there so that you can have multiple bots that know to ignore commands intended for other bots.
  • Action distinguishes between telling Sage to do something and asking Sage to find something.
  • Command is specifically what task you want Sage to do.
  • SubCommand break down commands further such as add/remove.
  • Arguments1,2 are any details you need to give Sage so that it can do the task for you.

1Arguments are sometimes given as one word (name), multiple words with quotes around them ("Vash the Stampede"), and other times key/value pairs (name="Vash the Stampede").
2If you see in these guides (or in the help) @UserMention, you need to ensure that Discord created a proper User Mention for Sage to be able to properly find the user. A "Proper User Mention" means that Discord recognized the user you were trying to mention and replaced your entered text with a link to the user. See image below.

sage!help dice is a simple command with a Prefix sage, Action !, Command help, and SubCommand dice
    2b. Slash Commands

Slash Commands are commands given to Sage by typing /sage and following the prompts Discord gives you to complete the command.

Note that Sage cannot respond to a DM from you unless you have opened a channel with it, which is done via the Slash Command: /sage dm.

    2c. Command Prefix

By default, Sage commands that start with ! or ? require a prefix.
    sage!help

This command has Prefix sage, Action !, and Command help.

You can change Sage's prefix with the prefix command:
    sage!prefix set newPrefix

This command has Prefix sage, Action !, Command prefix, SubCommand set and Argument newPrefix.

You can also remove Sage's prefix with the prefix command:
    sage!prefix unset

This command has Prefix sage, Action !, Command prefix, and SubCommand unset.

If you have unset the prefix, commands look like:
    !help

This command has no Prefix, Action !, and Command help.
    2d. Command Permissions

By default, Sage responds to all commands in any channel it has access to read and send messages. That said, "admin" commands (those that manipulate Sage, the Server, or Games, denoted by !!) require permissions with Sage. The Server Owner has full access and must give permission to others.

Sage Admin: Full access to Sage on the server, can assign Server Admin and Game Admin permissions and perform their actions.
    sage!!admin add @UserMention SageAdmin

This example has Prefix sage, Action !!, Command admin, SubCommand add, and Arguments @UserMention and SageAdmin.

Server Admin: Can configure channels to work with Sage, can assign Game Admin permissions and perform their actions.
    sage!!admin add @UserMention ServerAdmin

This example has Prefix sage, Action !!, Command admin, SubCommand add, and Arguments @UserMention and ServerAdmin.

Game Admin: Can configure Sage's game tables and channels, can assign Game Masters and perform their actions.
    sage!!admin add @UserMention GameAdmin

This example has Prefix sage, Action !!, Command admin, SubCommand add, and Arguments @UserMention and GameAdmin.

3. Sage Help

- sage! help
Lists the categories of help available.
- sage! help {category}
Lists the help commands available within the given category.
- sage! help {category} {subCategory}
Lists the help commands available within the given category and sub-category.

4. Admin (Administrative) Commands

sage! help admin

    4a. Sage Prefix Admin

sage! help admin prefix

These commands let you set or unset Sage command prefixes.
sage!! prefix get
sage!! prefix set {commandPrefix; ex: sage}
sage!! prefix sync
sage!! prefix unset

    4b. Game, Sage, Server Admin

sage! help admin admin

These commands are for server owners to configure admin access to Sage.
sage!! admin add @UserMention {GameAdmin|ServerAdmin|SageAdmin}
sage!! admin remove @UserMention
sage!! admin update @UserMention {GameAdmin|ServerAdmin|SageAdmin}
GameAdmin can only manage games.
Server Admin can manage games and server channels.
SageAdmin can manage all things Sage.

    4c. Color Admin

sage! help admin color

These commands are for managing the color that lines a post's embedded content.
sage!! color get {ColorType}
sage!! color get {server|game} {ColorType}
sage!! color list
sage!! color list {server|game}
sage!! color set {ColorType} {hexColorValue}
sage!! color set {server|game} {ColorType} {hexColorValue}
sage!! color sync
sage!! color sync {server|game}
sage!! color unset {ColorType}
sage!! color unset {server|game} {ColorType}
When choosing server or game you are deciding if you are working with Server colors or Game colors.
Use sage!! color list to see all of the acceptable values for ColorType.

    4d. Emoji Admin

sage! help admin emoji

These commands are for managing the emoji used for various parts of Sage.
sage!! emoji get {EmojiType}
sage!! emoji get {server|game} {EmojiType}
sage!! emoji list
sage!! emoji list {server|game}
sage!! emoji set {EmojiType} {emoji}
sage!! emoji set {server|game} {EmojiType} {emoji}
sage!! emoji sync
sage!! emoji sync {server|game}
sage!! emoji unset {EmojiType}
sage!! emoji unset {server|game} {EmojiType}
When choosing server or game you are deciding if you are working with Server emoji or Game emoji.
Use sage!! emoji list to see all of the acceptable values for EmojiType.

    4e. Server Role Admin Not Fully Functional

sage! help admin server

These commands are for manging the Roles used for admins of Sage.
sage!! server role list
sage!! server role remove {ServerRoleType}
sage!! server role set @RoleMention {ServerRoleType}
ServerRoleType values: SageAdmin, ServerAdmin, GameAdmin

5. Game Admin (Administrative) Commands

These commands are for configuring a "Game Table" (a game and group of channels that are all part of a game).

    5a. Game Admin

sage! help admin game

These commands are for managing games.
sage!! game archive
sage!! game archive list
sage!! game count
sage!! game create name="Dragon Saga: Questbound!"
sage!! game create name="Dragon Saga: Questbound!" game="PF2E|NONE"
sage!! game details
sage!! game list
sage!! game role remove {GameRoleType}
sage!! game role set @RoleMention {GameRoleType}
sage!! game set diceoutput="XXS|XS|S|M|L|XL|XXL|UNSET"
sage!! game set game="PF2E|NONE"
sage!! game set name="Dragon Saga: End Times ..."
sage!! role list
GameRoleTypes values: Spectator, Player, GameMaster, Cast, Table
- These roles are not fully implemented yet, but are meant to allow Sage to manage roles and permissions.

    5b. Channel Admin

sage! help admin channel

These commands are for managing what features are available on each channel.
sage!! channel add #ChannelReference {optionKey}="optionValue"
sage!! channel details
sage!! channel list {game|server}
sage!! channel remove #ChannelReference
sage!! channel set {optionKey}="optionValue"
Channel Options (can set multiple options at the same time):
.
- admin="true|false"
- commands="true|false" (also known as non-admin commands)
- dialog="true|false"
- dice="true|false"
- search="true|false"
- - This determines which types of commands (admin, non-admin, dialog, dice, search) are allowed.
.
- crit="timestwo|rolltwice|addmax|unset"
- - TIMESTWO rolls the dice and multiplies the results x2. (default)
- - ROLLTWICE rolls the damage twice and adds the results together.
- - ADDMAX rolls the dice once and then adds max damage to the result. (house rule)
- - UNSET uses the crit method inherited from either the game or the server.
.
- diceoutput="xxs|xs|s|m|l|xl|xxl|unset"
- - This determines how compact or expanded the dice results are displayed.
- - UNSET uses the diceoutput method inherited from either the game or the server.
.
- dicepost="post|embed|unset"
- - POST will output dice results in a simple post.
- - EMBED will output dice results in an embed in a post.
- - ~~REPLY will output dice results in a reply to the input.~~ (future feature)
- - UNSET uses the dicepost method inherited from either the game or the server.
.
- game="pf2e|none"
- - This determines which game is being played.
- - PF2E Currently Pathfinder Second Edition is the only game that Sage recognizes.
- - The primary place this is noticable is the dice engine: PF2E dice know about ACs, DCs, and how to calculate Critical Success and Failure.
.
- gamemaster="none|write"
- player="none|write"
- - NONE The user (gamemaster, player) should not have access to this channel.
- - WRITE The user (gamemaster, player) should have full access to this channel.
- - Note: A channel that is gamemaster=write and player=none is considered a GM only channel and is where secret dice rolls are sent!

    5c. GM (Game Master) Admin

sage! help admin gm

These commands are for managing Game Masters for games.
sage!! gm add @UserMention
sage!! gm list
sage!! gm remove @UserMention

    5d. NPC (Non Player Character) Admin

sage! help admin npc

These commands are for managing Non Player Characters for games.
sage!! npc create name="Farmer Bob" token="http://url_to_token_image" avatar="http://url_to_avatar_image"
sage!! npc delete name="Farmer Bob"
sage!! npc details name="Farmer Bob"
sage!! npc list "optionalFilter"
sage!! npc update name="Farmer Bob" avatar="http://url_to_avatar_image"
sage!! npc update oldname="Farmer Bob" newname="Blacksmith Bob"
Images can be urls or embedded images.

    5e. Player Admin

sage!help admin player

These commands are for managing Players for games.
sage!! player add @UserMention
sage!! player add @UserMention @UserMention
sage!! player list
sage!! player remove @UserMention {@OptionalPlayerMention}
The Optional Player Mentions are there to show you can add or remove multiples.

    5f. PC (Player Character) Admin

sage! help admin pc

These commands are for managing Player Characters.
sage!! pc create name="Bardok the Brave" token="http://url_to_token_image" avatar="http://url_to_avatar_image"
sage!! pc delete name="Bardok the Brave"
sage!! pc details name="Bardok the Brave"
sage!! pc list "optionalFilter"
sage!! pc update name="Bardok the Brave" avatar="http://url_to_avatar_image"
sage!! pc update oldname="Bardok the Brave" newname="Bardok the Cowardly"
Images can be urls or embedded images.

    5g. Companion (Companion, Familiar, Hireling, etc) Admin

sage! help admin companion

These commands are for managing companions for player characters.
sage!! companion create charname="Bardok the Brave" name="Ser Stallion" token="http://url_to_token_image" avatar="http://url_to_avatar_image"
sage!! companion delete charname="Bardok the Brave" name="Ser Stallion"
sage!! companion details name="Ser Stallion"
sage!! companion list "optionalFilter"
sage!! companion update charname="Bardok the Brave" name="Ser Stallion" avatar="http://url_to_avatar_image"
sage!! companion update charname="Bardok the Cowardly" oldname="Ser Stallion" newname="Ser Bolts'a'lot"
Images can be urls or embedded images.

6. Dialog Commands

sage! help dialog
These commands are how you interact with the dialog engine of Sage.
When posting dialog, you do not need to use a command prefix.
Each different dialog type can be configured to have its own default color.

    6a. Dialog Post Command

{type}::{name}(display name)::(title)::{color}::{avatar}::{content}
- {type}: gm, npc, enemy, ally, pc, alt, companion, hireling
- {name}: the name of the npc, pc, or companion to post as
- - optional for PCs in a game
- {display name}: the name to post as
- - optional: defaults to character name or 'Game Master' for GM
- {title}: a title or descripiton of the dialog optional
- {color}: a color to override the dialog color with
- - optional: expects hex value 0x000000 or #FFFFFF
- {avatar}: a url to override the avatar image
- - optional
- {content}: everything you want to post in your dialog
- - accepts normal discord/markup as well as custom Sage markup

    6b. Dialog Edit Command

sage! help dialog edit

This command lets you edit your last dialog post.
edit::{dialog content}

    6c. Dialog Alias Commands

sage! help dialog alias

These commands are for managing aliases for all your dialog needs.
sage!! alias delete {alias}
sage!! alias list
sage!! alias set {alias} {dialog prefix}
An alias is a simple word or name with no punctation.
A dialog prefix can include an alias and even some content.
Example: sage!! alias set gorm npc::Gorm Greathammer::

7. Dice Commands

sage! help dice
These commands are how you roll dice with Sage.

    7a. Simple Dice

[1d20]

    7b. Dice w/ description

[1d20 attack]
[1d6 damage]

    7c. Dice w/ modifier

[1d20 + 5 Description]
[1d20 + 5]
[1d8 + 2 + 1d6]
[1d8 sword + 2 strength + 1d6 holy]

    7d. Dice w/ tests

[1d100 < 25]
[1d20 + 5 >= 10 Description]
[1d20 >= 10]

    7e. Dice w/ multiple sets

[1d20 attack; 1d8 damage]
[1d20+5 attack; 1d8 + 2 slashing damage]
[1d20+2 attack; 1d4 dagger + 2d6 sneak damage]

    7f. Dice w/ multiple sets and tests

[1d20 > 10 attack; 1d8 damage]
[1d20 > 5 (miss chance); 1d20+5 >= 15 attack; 1d8 + 2 slashing damage]

    7g. Dice w/ target (pf2e only)

[1d20 + 5 ac 10 Description]
[1d20 ac 10]
[1d20 dc 10]
[1d20 vs 10]
Future releases will add this for other game systems.

    7h. Dice w/ output override

[XL 1d20 + 20 vs ac 10 greater striking rapier, fatal d8; 1d6 piercing + 4 dex + 2d6 holy + 4d6 sneak]
Output options: xxs, xs, s, m, l, xl, xxl

    7i. Dice w/ game override (pf2e)

[pf2e 1d20 vs ac 10 attack]
Used when a server or game defaults to a different mode than you want for your dice.
Future releases will add other game systems.

    7j. Dice Macros

sage! help dice macro

These commands are for managing macros to make complex dice rolls.
sage!! macro delete all
sage!! macro delete category="{category}"
sage!! macro delete name="{name}"
sage!! macro details name="{name}"
sage!! macro list
sage!! macro list category="{category}"
sage!! macro move name="{name}" category="{category}"
sage!! macro set name="{name}" [{dice}]
sage!! macro set name="{name}" category="{category}" [{dice}]
Example: sage!! macro set name="three daggers" category="daggers" [1d20+8;1d6][1d20+4;1d6][1d20;1d6]
Usage: [three daggers]
Example: sage!! macro set name="swords" [3MAP-4#1d20+8{ac};1d6]
Usage: [swords ac=10]

Macro Categories are helpful in grouping related macros together, but they also serve a special function for Pathfinder 2e players using imported characters. Macros with the same category name as an imported Pathfinder 2e character name will show up in the imported character's sheet so that you can select then and roll them with the click of a button. (Will provide link to importing documentation as it is finished.)

    7k. Dice Macro Arguments

Macros allow arguments, making them very flexible but also easy to overcomplicate.
Arguments are indicated with curly braces: { and }

The two primary types of arguments are: indexed and named.
Note: If you use an argument more than once in your macro, it will be replaced every time.

    Indexed arguments start with 0 go up: {0}, {1}, {2}, etc
        Example Macro: "attack" [1d20 {0} atk; 1d6 {1} dmg]
        Example Usage: [attack "+1" "+2"]
        Example Roll: [1d20 +1 atk; 1d6 +2 dmg]

    Named arguments should can only letters, numbers, and underscores: {bless_bonus}
        Example Macro: "attack" [1d20 {bless_bonus} atk; 1d6 {bless_bonus} dmg]
        Example Usage: [attack bless_bonus="+1"]
        Example Roll: [1d20 +1 atk; 1d6 +1 dmg]

    Arguments can have default values: {atk_bonus:+0}, {dmg_type:P}
    Note: A default value of 0 (or +0) will NOT be shown in the final dice roll
        Example Macro: "dagger" [1d20 {atk_bonus:+0} atk; 1d4 {dmg_type:P} dmg]
        Example Usage: [dagger]
        Example Roll: [1d20 atk; 1d4 P dmg]
        Example Usage: [dagger atk_bonus="+1"]
        Example Roll: [1d20 +1 atk; 1d4 P dmg]
        Example Usage: [dagger atk_bonus="+2" dmg_type="S"]
        Example Roll: [1d20 +2 atk; 1d4 S dmg]

Two special argument types are: "vs" {vs} and "remaining" {...}

    VS is a convenience for setting the roll's target success value in d20 style games; AC, DC, and VS are all acceptable as {ac}, {dc}, or {vs}
        Example Macro: "attack" [1d20 {ac} atk; 1d6 dmg]
        Example Usage: [attack ac=10]
        Example Roll: [1d20 ac 10 atk; 1d6 dmg]

    Remaining is more advanced- it takes every indexed argument that wasn't explicitly used in your macro and adds them all with spaces between them.
        Example Macro: "extras" [1d20 {0} atk; 1d6 {1} {...} dmg]
        Example Usage: [extras +1 +3 "+1d6 sneak" "+1d4 fire" "+1 holy"]
        Example Roll: [1d20 +1 atk; 1d6 +3 +1d6 sneak +1d4 fire +1 holy dmg]
    Note: If you have more than one "remaining" arg in your macro, they will all get the same set of values.

8. General Commands

sage! help command

    8a. Coin / Currency Calculator

sage! {1pp} {-2gp} {+3sp} {-4cp}
sage! {1pp} {2gp} {3sp} {4cp}

    8b. Weather Report Generator

sage! help command weather

This command creates a random weather report.
sage! weather {climate} {elevation} {season}
- Climate Options: Cold | Temperate | Tropical
- Elevation Options: SeaLevel | Lowland | Highland
- Season Options: Spring | Summer | Fall | Winter

9. Pathfinder 2e Commands

The following commands are specific to Pathfinder 2e.

    9a. Pathfinder / Golarion Info (days & months)

sage! help command golarion
These commands are for viewing the dates, days, and months of the Golarion (Pathfinder) calendar.
sage! date {yyyy-mm-dd}
- Displays the given date on Golarion and on Earth. Includes season.
sage! days
- Lists the days of the week on Golarion.
sage! months
- Lists the months of the Golarion year (along with how many days are in each).
sage! today
- Displays today's date on Golarion and on Earth. Includes season.

    9b. Pathfinder 2e DCs

sage! help command dcs

These commands are for viewing the various DCs used in Pathfinder 2e.
sage! dc by level {level}
sage! dc by spell level {level}
sage! dcs by level
sage! simple dc {proficiency}
sage! {proficiency} simple dc

    9c. Pathfinder 2e Lists

sage! list {deities|gods} by domain {domain}
sage! list {weapons|armor|spells} by trait {trait}
Future releases will expand on these lists.

    9d. Pathfinder 2e Content Search

These commands perform full text searches.
? {searchTerm}
? {searchTerm} -{categoryOrObjectType}
Category/ObjectType examples: Background, Feat, Spell, etc.
This isn't fully operational, nor is the data complete yet.

    9e. Pathfinder 2e Content Find

These commands perform searches only against names.
?! {searchTerm}
?! {searchTerm} -{categoryOrObjectType}
Category/ObjectType examples: Background, Feat, Spell, etc.
This isn't fully operational, nor is the data complete yet.

    9f. Pathfinder 2e Spell Lists

These commands allow you to view various types of spell lists
sage! spells {tradition} {level|Cantrips}
sage! spells {tradition} {level|Cantrips} by school
sage! {level} {tradition} spells
sage! {level} {tradition} spells by school
sage! {tradition} cantrips
sage! {tradition} cantrips by school
sage! {tradition} spells {level|Cantrips}
sage! {tradition} spells {level|Cantrips} by school
The following creates a specialized list of spells by merging or excluding traditions
sage! spells {level|Cantrips} {+tradition} {-tradition} {|tradition} {&tradition}

    9g. Pathfinder 2e Focus Spell Lists

sage! focus spells {Archetype|Class|Domain}
sage! {Archetype|Class|Domain} focus spells

    9h. Pathfinder 2e Starting Wealth Info

sage! starting wealth
sage! starting wealth {level}

    9i. Pathfinder 2e Income Info

sage! income earned
- Shows the entire table 4-2: Income Earned
sage! income earned {taskLevel}
- Shows the results for the given level.
sage! income earned {proficiency} {taskLevel}
- Shows the results for the given level and proficiency.

10. Pathfinder Society 2e Commands

The following commands are designed to help if you are playing Organized Play (Pathfinder Society) games for Pathfinder 2e.

    10a. Pathfinder PFS / Org Play

sage! pfs links
DISABLED FOR NOW (their site changed)

    10b. Pathfinder PFS Downtime Rolls

sage! pfs income {pcLevel} {skillProficiency} {skillModifier}
sage! pfs income {pcLevel} {skillProficiency} {skillModifier} {days}

    10c. Pathfinder PFS Scenario Randomizers

sage! pfs s1-01 {pc1Level}, {pc2Level}, {pc3Level}, {pc4Level}, {pc5Level}, {pc6Level}, {pc7Level}
Future releases will include more scenarios.
PFS Guidelines now recommend against 7 player tables

    10d. Pathfinder PFS Tier Calculator

sage! pfs {tier} {minLevel}-{maxLevel} {pc1Level} {pc2Level} {pc3Level} {pc4Level} {pc5Level} {pc6Level} {pc7Level}
PFS Guidelines now recommend against 7 player tables