The Storyteller’s Guide to Espanso Logic

Estimated reading time at 200 wpm: 7 minutes

Most of us spend our lives fighting with our keyboards. We have these thoughts—medical observations, legal arguments, complex lines of code—but the physical act of typing it out over and over feels like a tax on our time. When I first looked at Espanso, I almost closed the window. It looked like a wall of symbols. But once you realise it’s just a way to teach your computer how you think, it changes everything.

This guide is for the people who are tired of “renting” their productivity from subscription services. Whether you’re a doctor tired of retyping medication lists, a writer needing a signature block, or a developer building a whole app skeleton, this is about taking back your time. We’re going to look at how to build a system that works at the speed of your brain, turning frightening code into a simple set of instructions you actually own. Free your mind. Command your computer.

1. The Basic Handshake (Trigger and Replace)

At its simplest, Espanso is a game of “If this, then that.”

The Code:

  - trigger: "/twr"
    replace: "The White Rabbit"

What happens in the real world:

• You type: I saw /twr running by.
• The Result: I saw The White Rabbit running by.

The Breakdown:

• The Dash (-): Think of this as a bullet point. It tells the computer, “Here is a new item on the list.“
• The Colon (:): This is just an equals sign. trigger: "/twr" means “The trigger equals /twr.”

2. The “Two-Space” Rule: The Foundation

Before we go any further, we have to talk about the “air” in the file. In this language, the alignment tells the computer who is in charge. This is usually where people get their first errors.

• The Parents: trigger and replace sit on the left.
• The Children: Anything that belongs to a shortcut (like the “thinking” section we’ll see later) is pushed in by two spaces.
• The Grandchildren: Details inside those sections are pushed in by four spaces.

The Golden Rule:

1. Be very careful with the Tab key in a standard Notepad editor. Even though it looks the same, the computer sees a Tab as a “ghost character” that breaks the logic. Use the Spacebar for everything. Think of it like an outline: the further to the right a line is, the more it “belongs” to the line above it.
2. Tab keys work well from real experience in VS Code – which is a stupidly simple kind of editor for lots of things – that most people are afraid of. Yuh know, anything with ‘Code‘ in it is guaranteed to cause panic attacks about being arrested for being a hacker!

3. The “Vertical Pipe” (|): The Storyteller’s Secret

Sometimes, you don’t just want a name; you want an entire paragraph. This is where people get confused by that vertical line (|).

In the computer world, a regular “replace” instruction expects everything to stay on one single line. If you try to hit “Enter” to start a new paragraph, the computer gets lost. The vertical pipe is your way of saying: “Attention! I am about to tell a long story with many lines. Please keep them exactly as I write them.”

The Code:

  - trigger: "/alice"
    replace: |
      "Curiouser and curiouser!" cried Alice 
      (she was so much surprised, that for the 
      moment she quite forgot how to speak 
      good English).

What happens in the real world:

• You type: /alice
• The Result: > “Curiouser and curiouser!” cried Alice

(she was so much surprised, that for the

moment she quite forgot how to speak

good English).

The vars: Giving the Shortcut a Brain

This is where you give a specific shortcut its own “utility belt” so it can do some thinking before it types.

The Code:

  - trigger: "/teatime"
    replace: "It's always six o'clock here, but my watch says {{current_time}}."
    vars:
      - name: current_time
        type: date
        params:
          format: "%H:%M"

Connecting the Dots: How it works under the hood

1. The Hook ({{current_time}}): Inside the replace: line, those double brackets act as a “Wanted” poster. You are telling Espanso: “Don’t type the literal words current_time. Instead, go find the instruction manual for a guy with that exact name.”
2. The Brain (vars:): This is the start of the manual. It tells the computer: “Stop typing for a split second. I have extra work for you to do before we fill that gap.”
3. The Matching Label (name: current_time): This name must match the word you put inside the brackets above. This is the link that tells the computer: “I am now giving you the definition for that specific ‘Hook’ you just saw.”
4. The Action (type: date): You are telling the computer which tool to use. “To fill this gap, look at the system clock.”

5. Advanced Logic: The “Interactive” Shortcut

Variables can also stop and wait for you to give them information.

A. The “Pop-up Window” (The Form)

Imagine you want the computer to ask you for a name so you don’t have to type it in the middle of a sentence.

The Code:

  - trigger: "/greet"
    replace: "Hello {{person_name}}, would you like some tea?"
    vars:
      - name: person_name
        type: form
        params:
          layout: "Name: [[input]]"

What happens: You type /greet, a window pops up, you type “Alice,” and the computer finishes the sentence for you.

B. The “Future Date” (Date Math)

You can tell Espanso to do the math for a follow-up date (like “one week from today”).

The Code:

  - trigger: "/followup"
    replace: "Please return for a follow-up on {{next_week}}."
    vars:
      - name: next_week
        type: date
        params:
          format: "%d/%m/%Y"
          offset_days: 7

6. The Developer’s Toolbox: The Python Hook

For coders, Espanso can act like an automated architect. You can create a complex hook that builds a Python file, asks you for the class name, and even automatically looks up your computer’s username so you don’t have to type it.

The Code:

  - trigger: "/pyclass"
    replace: |
      """
      Module: {{class_name}}
      Author: {{my_user}}
      Created: {{today}}
      """

      class {{class_name}}:
          def __init__(self):
              pass

      if __name__ == "__main__":
          app = {{class_name}}()

    vars:
      - name: class_name
        type: form
        params:
          layout: "Class Name: [[input]]"
      - name: my_user
        type: shell
        params:
          cmd: "whoami"
      - name: today
        type: date
        params:
          format: "%Y-%m-%d"

Why this is a “Power Move”:

• The Shell Hook (type: shell): This is the ultimate tool. You are telling Espanso: “Open the terminal, run the command whoami (which returns your computer’s login name), and bring that text back to me.”
• The Mix-and-Match: Notice how this one shortcut uses a Form (asking you a question), a Shell (checking your identity), and a Date (checking the clock) all at the same time.
• The Result: You type /pyclass, enter “DataAnalyser” in the pop-up, and instantly get a perfectly formatted Python file header and class structure.

Summary of the “Grammar”

• - = “New List Item”
• : = “Equals”
• | = “A long story is coming (multi-line text)”
• {{...}} = “Wait! Look at the sub-instructions below to fill this gap”
• vars: = “The thinking/sub-instruction section”
• type: form = “Stop and ask me for input”
• type: shell = “Run a terminal command to find information”
• offset_days: = “Look into the future (or the past)”

The Story Behind the Symbols

There is a shift that happens when the “code” stops being a barrier and starts being a set of instructions you actually own. You stop being a passenger in your own work. You start seeing the symbols—the dashes, the colons, that strange vertical line—as tools that wait for your command.

It’s about moving from a state of frustration to one of control. We often think of automation as something that makes us less human, but here, it’s the opposite. It removes the friction between what you want to say and how it actually lands on the page. Once those first few triggers start firing and your snippets begin to expand, you realise you aren’t just saving a few seconds; you’re clearing the mental fog that comes with repetitive tasks. It turns the keyboard back into what it was always meant to be: a way to tell your story without the software getting in the way.