Espanso: The Ultimate Text Expander for Efficiency and Productivity

In today’s fast-paced digital world, efficiency is key. Whether you’re typing emails, writing reports, or coding, you often find yourself typing the same phrases, sentences, or even entire blocks of text repeatedly. This repetitive task can slow you down and distract you from more important work. Luckily, there’s a tool that can help automate and streamline these repetitive actions: Espanso.

What is Espanso?

Espanso is a text expander that works by automatically replacing predefined text snippets (shortcodes) with longer text or even entire documents. For instance, instead of typing “Best regards,” you can set up a shortcut like :br that automatically expands to “Best regards, [Your Name]”. It’s a simple yet powerful tool that can enhance your typing speed and reduce repetitive typing.

Espanso is open-source and available on multiple operating systems, including Windows, macOS, and Linux. This wide compatibility ensures that most users can benefit from its features, regardless of their platform.

Key Features of Espanso

• Cross-Platform Compatibility
  Espanso works seamlessly across different operating systems, including Windows, macOS, and Linux. This means whether you’re working on a PC, Mac, or Linux machine, you can enjoy the same functionality across devices.
• Open Source
  Being open-source, Espanso is completely free to use, and its code is accessible to developers who may wish to customize or improve the software. This fosters a strong community that continually contributes to the development and refinement of Espanso.
• Snippet Creation
  At the heart of Espanso are its snippets. Users can define a shorthand trigger (called a “trigger word”) for any phrase, sentence, or block of text. When you type the trigger, Espanso automatically expands it into the predefined text. You can create triggers for anything from email signatures to long URLs, code snippets, or standard replies.

How Espanso Works

Espanso operates by running in the background and monitoring your keyboard input. It scans for any text that matches your defined triggers and expands it into the corresponding snippet. The expansion happens instantaneously and does not interrupt your workflow.

Here’s how it works:

• Define a Trigger:
  You start by defining a trigger word (e.g., :email) in Espanso’s configuration file. This is the shortcut you’ll type to activate the expansion.
• Set the Expansion Text:
  For the :email trigger, you could set the expansion to a full email signature, such as “Best regards, [Your Name], [Your Title], [Your Contact Information].”
• Trigger Activation:
  Once you type the trigger word (:email) in any text field, Espanso will automatically replace it with your defined signature.

How to Install Espanso

Espanso’s installation process is straightforward:

1. Windows:
Download the installer from the official Espanso website, run the installer, and follow the on-screen instructions.

2. macOS:
You can install Espanso using Homebrew with the command:

brew install espanso

3. Linux

On Linux, Espanso offers two distinct versions: one for X11 and another for Wayland. Be sure to install the version that matches your system’s display server to ensure optimal functionality.

# For X11

# on Debian/Ubuntu  
sudo apt install espanso 

# on Arch linux
sudo pacman -S espanso-bin

After installing Espanso on your Linux system, you need to register it and then start the application by running the espanso start command in the terminal.

# Register espanso as a systemd service (required only once)
espanso service register

# Start espanso
espanso start

Setting up espanso

On Linux, you need to edit the file “/home/$USER/.config/espanso/match/base.yml” to add your custom matches. Alternatively, you can run the following command to directly edit the base.yml file:

espanso edit

Simple text expansion

Here’s an example of a working base.yml file for Espanso, which defines custom text expansion triggers and their corresponding expanded text:

matches:
  # Email Signature
  - trigger: ":sig"
    replace: |
      Best regards,  
      John Doe 
  # Custom Markdown snippet
  - trigger: ":md_code"
    replace: |
      ```python
      def hello_world():
          print("Hello, World!")
      ```      

Multi-line expansions

 - trigger: hello
    replace: "line1\nline2"

Dynamic Matches

 - trigger: :now
    replace: It's {{mytime}}
    vars:
      - name: mytime
        type: date
        params:
          format: "%H:%M"

Variables can be used to personalize the snippet. These will be replaced based on context or input.

Global Variables

Global variables are variables that can be used across multiple matches. You can define them above your matches, and they will be available across all matches defined in that file and it’s children.

# Add this outsite the matches block (before matches block) 
global_vars:
  - name: greet
    type: echo
    params:
      echo: Hey

# Add this inside the matches block 
  - trigger: :hello
    replace: "{{greet}} Jon"

Word correction

- trigger: ther
    replace: there
    word: true

With word triggers you can now add the word: true property to a match, telling espanso to only trigger that match if surrounded by word separators ( such as spaces, commas and newlines). So in this case it becomes:

Case propagation

  - trigger: alh
    replace: although
    propagate_case: true
    word: true

Explanation:

• If you write alh, the match will be expanded to although.
• If you write Alh, the match will be expanded to Although.
• If you write ALH, the match will be expanded to ALTHOUGH.

Case propagation with uppercase_style

 - trigger: ;ols
    replace: ordinary least squares
    uppercase_style: capitalize_words
    propagate_case: true
    
# In this case, typing ;Ols gets expanded to Ordinary Least Squares.

Cursor Hints

Insert $|$ where you want the cursor to be positioned,

 - trigger: :div
    replace: <div>$|$</div>

Multiple Matches

if multiple matches share the same trigger? In such cases, Espanso will use match disambiguation (custom espanso gui) to let you choose the appropriate one.

Multiple triggers

At times, it can be helpful to expand a snippet using different aliases. To accommodate this, Espanso supports multi-trigger matches, enabling users to assign multiple triggers to expand the same snippet. To use this feature, simply list the triggers under the triggers field, instead of specifying a single trigger.

  - triggers: [world, wrd]
    replace: Hello world

Nested Matches

Nested matches makes it possible to include the output of a match inside another one.

  - trigger: :one
    replace: nested

  - trigger: :nested
    replace: This is a {{output}} match
    vars:
      - name: output
        type: match
        params:
          trigger: :one

Markdown text

Espanso also support markdown text expansion

  - trigger: :rich
    markdown: This *text* is **very rich**!

Extensions

Choice Extension

This will open the Espanso GUI, allowing you to choose from a list of available items.

 - trigger: ":quote"
    replace: "{{output}}"
    vars:
      - name: output
        type: choice
        params:
          values:
            - "Every moment is a fresh beginning."
            - "Everything you can imagine is real."
            - "Whatever you do, do it well."

Random Extension

You can define multiple possible expansions for a match, and Espanso will randomly select one. This feature helps prevent repetitive text and adds variety to your snippets.

  - trigger: ":quote"
    replace: "{{output}}"
    vars:
      - name: output
        type: random
        params:
          choices:
            - "Every moment is a fresh beginning."
            - "Everything you can imagine is real."
            - "Whatever you do, do it well."

Clipboard Extension

The Clipboard Extension enables to include the current clipboard content in a match.

  - trigger: ":a"
    replace: "<a href='{{clipb}}' />$|$</a>"
    vars:
      - name: "clipb"
        type: "clipboard"

Shell Extension

The Shell extension in Espanso allows users to trigger text expansions directly from the command line or execute shell commands as part of an expansion. This feature is particularly useful for advanced users who want to integrate text expansion with their workflows, automate tasks, or include dynamic content generated from shell scripts.

  - trigger: ":ip"
    replace: "{{output}}"
    vars:
      - name: output
        type: shell
        params:
          cmd: "curl 'https://api.ipify.org'"

Script extension

The Script extension in Espanso allows you to trigger and run custom scripts as part of a text expansion. This feature enables more advanced and dynamic functionality by allowing users to run scripts—whether shell scripts, Python scripts, or other executable files—directly through their text snippets.

  - trigger: ":pyscript"
    replace: "{{output}}"
    vars:
      - name: output
        type: script
        params:
          args:
            - python
            - /path/to/your/script.py
            
# contents of script.py

print("hello world from your script)

Adding more parameters

# Adding more parameters

 - trigger: ":pyscript"
    replace: "{{output}}"
    vars:
      - name: output
        type: script
        params:
          args:
            - python
            - "%CONFIG%/scripts/script.py"
            - parameter_1
            - parameter_2

Inline scripts​: directly executing script commands

  - trigger: ":pyscript"
    replace: "{{output}}"
    vars:
      - name: output
        type: script
        params:
          args:
            - python
            - -c 
            - print("hello world")

Combining global vars and inline scripts

global_vars:
  - name: pscript
    type: echo
    params:
      echo: |
        fruits = ["apple", "banana", "cherry"]
        for x in fruits:
          print(x) 

matches:
  - trigger: :test
    replace: "{{output}}"
    vars:
      - name: output
        type: script
        params:
          args: [python, -c, "{{pscript}}"]

Anchor syntax : This is alternative to global variable syntax

anchors:      
  - &script1 |
      fruits = ["apple", "banana", "cherry"]
      for x in fruits:
        print(x) 

matches:
  - trigger: :testt
    replace: "{{output}}"
    vars:
      - name: output
        type: script
        params:
          args: [python, -c, *script1]    

Conclusion

Espanso is a simple yet powerful tool that can significantly improve productivity by automating the process of typing repetitive text. Its flexibility, ease of use, and open-source nature make it a favorite among users who need an efficient text expansion tool. Whether you’re a writer, developer, or customer service agent, Espanso can streamline your workflow, reduce typing errors, and help you focus on what matters most—creating and communicating effectively.