# Macros

Macros are dynamic placeholders that get replaced with actual values when text is processed. They are used throughout SillyTavern in prompts, character cards, lorebooks, Quick Replies, and more.

SillyTavern provides built-in documentation for all available macros:

• Slash command: Type /? macros in the chat input to display a list of all registered macros with their descriptions.
• Autocomplete: Type {{ during slash commands autocomplete in the input field to get suggestions for available macros.

Macros are enclosed in double curly braces:

{{macroName}}

Macro names are case-insensitive. {{User}}, {{USER}}, and {{user}} all resolve to the same macro.

Examples:

{{user}}        // Returns the current user/persona name
{{char}}        // Returns the current character name
{{time}}        // Returns the current time
{{date}}        // Returns the current date

Many macros accept arguments to customize their behavior.

For macros with a single argument, a space can separate the macro name from its argument:

{{macroName argument}}

Examples:

{{getvar myVariable}}
{{roll 1d20}}
{{reverse Hello World}}

Use :: to separate multiple arguments:

{{macroName::arg1::arg2::arg3}}

Examples:

{{setvar::myVariable::Hello World}}
{{random::red::green::blue}}
{{roll::2d6+3}}

Both space and :: are the recommended syntax for macro arguments.

A single : can also introduce arguments, but this syntax is considered legacy and not recommended for new content:

{{macroName:argument}}

Examples:

{{roll:1d20}}

Whitespace between the macro name, separators, and arguments is ignored. This allows for more readable formatting:

{{ macroName :: arg1 :: arg2 }}
{{ setvar :: myVariable :: some value }}
{{ if :: condition }}

All of the above are equivalent to their compact forms without extra spaces.

Macros can be nested inside other macros. Inner macros are resolved first:

{{getvar::{{char}}_mood}}

This first resolves {{char}} (e.g., to "Alice"), then resolves {{getvar::Alice_mood}}.

More examples:

{{setvar::greeting::Hello, {{user}}!}}

Sets a variable with content that includes the user's name.

{{if {{getvar::showDetails}}}}Details here{{/if}}

The condition itself is a macro that retrieves a variable value.

Any macro that accepts at least one argument supports scoped syntax. The content between opening and closing tags becomes the last argument of the macro.

Instead of writing the last argument inline, it can be placed between opening and closing tags:

{{macroName argument}}
  scoped content here
{{/macroName}}

The closing tag uses the / flag before the macro name: {{/macroName}}.

This is equivalent to writing:

{{macroName::argument::scoped content here}}

Setting a variable with multiline content:

{{ setvar backstory }}
  This character was born in a small village
  and grew up to become a renowned scholar.
{{ /setvar }}

Using reverse with scoped content:

{{ reverse }}
  Hello World
{{ /reverse }}

This returns "dlroW olleH".

By default, scoped content is automatically trimmed:

• Leading and trailing whitespace is removed
• Consistent indentation is de-dented (the indentation of the first non-empty line is removed from all lines)

This allows clean formatting:

{{ if condition }}
    # Heading
    Some content here
{{ /if }}

Produces # Heading\nSome content here (without the leading spaces).

To preserve all whitespace including leading/trailing newlines, use the # flag. See Macro Flags for details.

The {{if}} macro renders content conditionally based on whether a value is truthy or falsy.

{{ if description }}
  # Character Description
  {{ description }}
{{ /if }}

This displays the heading and description only if description returns a non-empty value.

The condition can be:

• A macro name (resolved automatically if no arguments are required)
• Any value from a nested macro like {{getvar::flag}}
• A variable shorthand like .myFlag or $globalFlag (see Variable Shorthand Syntax)
• Any text you want (that will implicitly resolve to truthy or falsy based on its content)

Falsy values: empty string, false, 0, off, no.

Variable shorthands provide a concise way to check variable values in conditions:

{{ if .isEnabled }}
  Feature is enabled.
{{ /if }}

{{ if !$globalDisabled }}
  Not globally disabled.
{{ /if }}

See Variable Shorthand Syntax for more details on shorthand notation.

Prefix the condition with ! to invert it:

{{ if !personality }}
  No personality defined for this character.
{{ /if }}

Use {{else}} inside an {{if}} block to define an alternative branch:

{{ if personality }}
  {{ personality }}
{{ else }}
  No personality defined.
{{ /if }}

Another example:

{{ if {{getvar::details-block}} }}
  # Details Block
  {{ getvar::details-block }}
{{ else }}
  No details currently exist.
{{ /if }}

Flags are special symbol characters placed between the opening braces and the macro name that modify macro behavior.

{{!macroName}}
{{#macroName}}

Flags can be combined:

{{!?macroName}}

Whitespace is allowed between flags and the macro name:

{{ / macroName }}
{{ # macroName }}

Variable shorthand syntax uses prefix operators (. and $) which behave similarly to flags but are not flags themselves.
See the Variable Shorthand Syntax section for details.

Use the # flag when you need to preserve all whitespace in scoped content, including leading/trailing newlines and indentation:

{{ # setvar code }}
    function hello() {
        return "world";
    }
{{ /setvar }}

Without #, the content would be trimmed and dedented. With #, all whitespace is preserved exactly as written—including the newline after the opening tag and before the closing tag.

Use the comment macro to add notes that won't appear in the output:

{{// This is a comment and will be removed}}

For multi-line comments, use scoped syntax:

{{ // }}
  This entire block is a comment.
  It can span multiple lines.
{{ /// }}

To display literal curly braces without macro resolution, escape them with backslashes:

\{\{notAMacro\}\}

This outputs {{notAMacro}} as plain text.

Variable shorthands provide a concise syntax for common variable operations. Use . for local variables and $ for global variables.

These prefix operators have to be placed immediately before the variable name, after any optionally appearing Macro Flags. They aren't considered macro flags, but more indicators that a variable shorthand is being inserted, instead of a macro by name. The prefix operators are not part of the variable name itself, but rather modifiers that change how the variable is accessed.

Retrieve variable values with a simple prefix:

{{.myvar}}       // Get local variable "myvar"
{{$myvar}}       // Get global variable "myvar"

Equivalent to {{getvar::myvar}} and {{getglobalvar::myvar}}.

Use the = operator to set a variable value:

{{ .myvar = Hello World }}     // Set local variable
{{ $myvar = Some value }}      // Set global variable

Equivalent to {{setvar::myvar::Hello World}} and {{setglobalvar::myvar::Hello World}}. Returns an empty string.

Use ++ and -- to increment or decrement numeric variables:

{{.counter++}}    // Increment local variable, returns new value
{{$counter--}}    // Decrement global variable, returns new value

Equivalent to {{incvar counter}} and {{decglobalvar counter}}.

Use += to add a numeric value to a variable:

{{.score += 10}}     // Add 10 to local variable
{{$total += 5}}      // Add 5 to global variable

Equivalent to {{addvar::score::10}} and {{addglobalvar::total::5}}. Returns an empty string.

The add operator also supports appending string to an existing string macro, if neither of them are numbers.

{{.myvar += {{noop}} | Second block}}   // Resolves to "Content | Second block" when the variable before was "Content".
                                        // Use `{{noop}}` to be able to add whitespaces, that otherwise would be trimmed automatically.

Variable values can contain nested macros:

{{.greeting = Hello, {{user}}!}}

Resolves to a variable that that saves Hello, User! inside. (If {{user}} is named "User")

Whitespace around operators is allowed:

{{ .myvar = spaced value }}
{{ .counter ++ }}

Variable names follow the same rules as macro identifiers: start with a letter, followed by letters, digits, underscores, or hyphens. The last character is not allowed to be an underscore or hyphen.

{{.my-var}}       // Valid
{{.my_var}}       // Valid
{{.myVar123}}     // Valid

If your variable has an identifier that does not match the standard rules, you have to use the full variable macro syntax with angle brackets (e.g. {{getvar::my§var----}}), or rename/move your variable value.

For backwards compatibility, angle bracket markers are still supported:

These are automatically converted to their macro equivalents during processing.

Note: Legacy syntax is not recommended. Use the equivalent {{macro}} syntax instead for new content.