Command Guide

Most are also NOT case sensitive.

`{}`

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.
Sage asks for various permissions needed to function as expected:

some features are still in development

**Manage Roles:**A future Sage feature will create/manage roles for games. in development**Manage Channels:**A future Sage feature will create/manage channels for games. in development**Create Invite:**A future Sage feature will create invites for games posted as looking for players. not yet in development**Manage Emojis and Stickers:**A future Sage feature may allow custom emojis for games. not yet in development**Manage Webhooks:**This is how Sage posts dialog as characters instead of their players.**Read Messages:**Sage needs to be able to read messages to parse commands.**Send Messages:**Sage needs to be able to send messages to respond to commands.**Manage Messages:**Sage needs to be able to manage messages to function (such as edit, pin, or delete messages).**Embed Links:**Sage needs to be able to embed links to link game material to their source (such as Archives of Nethys).**Attach Files:**Sage's import command can attach a .txt of your character formatted in markdown.**Read Message History:**Sage needs to be able to search messages to function. A future Sage feature may allow for more enhanced game/dialog specific search.*(not yet in development)***Add Reactions:**Sage needs to be able to add reactions to inform and interact with users.**Use External Emojis:**Sage needs access to the default emoji set on RPG Sage's Discord server.**Use Application Commands:**I am currently moving most of the commands from posting as a message to Slash Commands!

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

- Dialog Commands
- Dice Commands
- Message Commands
- Slash Commands

Dialog and Dice commands will be discussed later.

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.**Arguments**^{1,2}are any details you need to give Sage so that it can do the task for you.

^{1}Arguments 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"`

).
^{2}If 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`

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`

.

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`

.
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`

.

- `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.

`sage! help 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`

`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.

`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.

`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.

`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

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

`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.

`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!

`sage! help admin gm`

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

`sage!! gm list`

`sage!! gm remove @UserMention`

`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.

`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.

`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.

`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.

`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.

`{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

`sage! help dialog edit`

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

`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::`

`sage! help dice`

These commands are how you roll dice with Sage.

`[1d20]`

`[1d20 attack]`

`[1d6 damage]`

`[1d20 + 5 Description]`

`[1d20 + 5]`

`[1d8 + 2 + 1d6]`

`[1d8 sword + 2 strength + 1d6 holy]`

`[1d100 < 25]`

`[1d20 + 5 >= 10 Description]`

`[1d20 >= 10]`

`[1d20 attack; 1d8 damage]`

`[1d20+5 attack; 1d8 + 2 slashing damage]`

`[1d20+2 attack; 1d4 dagger + 2d6 sneak damage]`

`[1d20 > 10 attack; 1d8 damage]`

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

`[1d20 + 5 ac 10 Description]`

`[1d20 ac 10]`

`[1d20 dc 10]`

`[1d20 vs 10]`

Future releases will add this for other game systems.

`[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

`[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.

`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.)*

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.

`sage! help command`

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

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

`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

The following commands are specific to Pathfinder 2e.

`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.

`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`

`sage! list {deities|gods} by domain {domain}`

`sage! list {weapons|armor|spells} by trait {trait}`

Future releases will expand on these lists.

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.

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.

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}`

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

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

`sage! starting wealth`

`sage! starting wealth {level}`

`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.

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

`sage! pfs links`

DISABLED FOR NOW (their site changed)

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

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

`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

`sage! pfs {tier} {minLevel}-{maxLevel} {pc1Level} {pc2Level} {pc3Level} {pc4Level} {pc5Level} {pc6Level} {pc7Level}`

PFS Guidelines now recommend against 7 player tables