# 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: See Macro Autocomplete below for details on getting suggestions while typing.

Macro autocomplete provides suggestions for available macros as you type. It works in all text fields that support macros throughout SillyTavern.

Type {{ to start autocomplete for macros, showing available macros and their arguments, potential Macro Flags, Variable Shorthands, and more.

Where autocomplete appears by default:

• Chat user input box
• Expanded editor (full-screen text editing, opened via the 'Expand' button next to text fields)
• Prompt manager editor

Triggering autocomplete in other fields:

• Press Ctrl+Space in any macro-supporting text field to open the autocomplete popup
• Enable Settings → AutoComplete Settings → Show in all macro fields to have autocomplete appear automatically in all macro fields

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 Shorthands)
• 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 Shorthands 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 Shorthands 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.

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 (e.g. {{getvar::my§var----}}), or rename/move your variable value.

Variable values can contain nested macros:

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

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

Whitespace around operators is allowed:

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

The following operators can be used with variable shorthands. Each operator follows the pattern {{.varName operator value}} or {{$varName operator value}}.

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 ++ to increment a numeric variable by 1:

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

Equivalent to {{incvar counter}} and {{incglobalvar counter}}. Returns the new value after incrementing.

Use -- to decrement a numeric variable by 1:

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

Equivalent to {{decvar counter}} and {{decglobalvar counter}}. Returns the new value after decrementing.

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 strings to an existing string variable, 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.

Use -= to subtract a numeric value from a variable:

{{.health -= 10}}    // Subtract 10 from local variable
{{$points -= 5}}     // Subtract 5 from global variable

Equivalent to {{addvar::score::10}} and {{addglobalvar::total::5}}, but with a negative/inverted number. Returns an empty string. If the value is not a valid number, a warning is logged and the variable is unchanged.

Use || to provide a fallback value when the variable is falsy (empty string, 0, false):

{{.name || Anonymous}}     // Returns "Anonymous" if .name is empty or falsy
{{$setting || default}}    // Returns "default" if $setting is falsy

Returns the variable value if truthy, otherwise returns the fallback value. The fallback is only evaluated if needed (lazy evaluation).

Use ?? to provide a fallback value only when the variable does not exist:

{{.name ?? Guest}}         // Returns "Guest" only if .name is not defined
{{$config ?? default}}     // Returns "default" only if $config doesn't exist

Unlike ||, this returns the variable value even if it's falsy (empty string, 0, false) — as long as the variable exists. The fallback is only evaluated if needed (lazy evaluation).

Use ||= to set a variable to a value only if it's currently falsy:

{{.name ||= Anonymous}}    // Sets and returns "Anonymous" if .name is falsy
{{$count ||= 0}}           // Sets and returns "0" if $count is falsy

If the variable is already truthy, returns the current value without modification. Returns the final value (either existing or newly set).

Use ??= to set a variable to a value only if it doesn't exist:

{{.name ??= Guest}}        // Sets and returns "Guest" only if .name is undefined
{{$config ??= default}}    // Sets and returns "default" only if $config doesn't exist

Unlike ||=, this preserves falsy values (empty string, 0, false) if the variable already exists. Returns the final value (either existing or newly set).

Use == to compare a variable value to another value:

{{.status == active}}      // Returns "true" if .status equals "active", otherwise "false"
{{$mode == dark}}          // Returns "true" if $mode equals "dark", otherwise "false"

Performs a string comparison and returns the literal string "true" or "false".
Treats not existing variables, null variables and empty variables as the same.

Useful in {{if}} conditions:

{{if {{.status == active}} }}Active mode{{/if}}

Use != to compare a variable value to another value for inequality:

{{.status != inactive}}    // Returns "true" if .status is NOT "inactive", otherwise "false"
{{$mode != light}}         // Returns "true" if $mode is NOT "light", otherwise "false"

Performs a string comparison and returns "true" if the values are different, "false" if they are equal.
Treats not existing variables, null variables and empty variables as the same.

Useful in {{if}} conditions:

{{if {{.status != disabled}} }}Feature enabled{{/if}}

Use > to check if a variable's numeric value is greater than another value:

{{.score > 50}}        // Returns "true" if .score is greater than 50
{{$level > 5}}         // Returns "true" if $level is greater than 5

Performs a numeric comparison and returns the literal string "true" or "false".

Useful in {{if}} conditions:

{{if {{.score > 100}} }}High score!{{/if}}

Use >= to check if a variable's numeric value is greater than or equal to another value:

{{.level >= 10}}       // Returns "true" if .level is at least 10
{{$points >= 100}}     // Returns "true" if $points is 100 or more

Performs a numeric comparison and returns the literal string "true" or "false".

Useful in {{if}} conditions:

{{if {{$level >= 10}} }}Unlocked advanced features{{/if}}

Use < to check if a variable's numeric value is less than another value:

{{.health < 20}}       // Returns "true" if .health is below 20
{{$timer < 0}}         // Returns "true" if $timer is negative

Performs a numeric comparison and returns the literal string "true" or "false".

Useful in {{if}} conditions:

{{if {{.health < 20}} }}Low health warning!{{/if}}

Use <= to check if a variable's numeric value is less than or equal to another value:

{{.health <= 0}}       // Returns "true" if .health is 0 or below
{{$attempts <= 3}}     // Returns "true" if $attempts is 3 or fewer

Performs a numeric comparison and returns the literal string "true" or "false".

Useful in {{if}} conditions:

{{if {{.health <= 0}} }}Game over{{/if}}

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.