### Example: Start Espanso with Custom Config Directory

Source: https://github.com/espanso/website/blob/main/docs/sync.md

This example demonstrates how to start Espanso in unmanaged mode while specifying a custom directory for its configuration files using the `--config_dir` parameter.

```bash
espanso --config_dir /path/to/your/files start --unmanaged
```

--------------------------------

### Install Espanso using Scoop

Source: https://github.com/espanso/website/blob/main/docs/install/win.mdx

Install Espanso using the Scoop package manager. This involves adding the main bucket and then installing espanso.

```cmd
scoop bucket add main
```

```cmd
scoop install main/espanso
```

--------------------------------

### Start Local Development Server

Source: https://github.com/espanso/website/blob/main/README.md

Starts a local development server for live preview. Changes are reflected without server restart.

```bash
yarn start
```

--------------------------------

### espanso start

Source: https://github.com/espanso/website/blob/main/docs/command lIne/cli_list.md

Start espanso as a service.

```APIDOC
## start

Start espanso as a service
```

--------------------------------

### Start Espanso in Unmanaged Mode

Source: https://github.com/espanso/website/blob/main/docs/install/linux/_x11-after-install.mdx

Alternatively, start espanso in unmanaged mode. Note that it will not start automatically and requires manual initiation.

```bash
espanso start --unmanaged
```

--------------------------------

### espanso install Command Options

Source: https://github.com/espanso/website/blob/main/docs/command lIne/cli_list.md

Install espanso packages from the Espanso Hub or external repositories. Options allow forcing installation, refreshing the index, or using native git.

```bash
USAGE:
    espanso install [FLAGS] [OPTIONS] [package_name]

FLAGS:
    -e, --external          Allow installing packages from non-verified repositories.
        --force             Overwrite the package if already installed
        --refresh-index     Request a fresh copy of the Espanso Hub package index instead of using the cached version.
        --use-native-git    If specified, espanso will use the 'git' command instead of trying direct methods.

OPTIONS:
        --git <git>                  Git repository from which espanso should install the package.
        --git-branch <git-branch>    Force espanso to search for the package on a specific git branch
        --version <version>          Force a particular version to be installed instead of the latest available.

ARGS:
    <package_name>    Package name
```

--------------------------------

### Install Dependencies with Yarn

Source: https://github.com/espanso/website/blob/main/README.md

Installs project dependencies using Yarn. Run this command in the project root.

```bash
yarn
```

--------------------------------

### Install Espanso Package

Source: https://github.com/espanso/website/blob/main/docs/get-started.md

Install packages from the Espanso Hub using the `espanso install` command followed by the package name. This automatically reloads the configuration.

```bash
espanso install basic-emojis
```

--------------------------------

### Publishing and Installing Custom Packages

Source: https://context7.com/espanso/website/llms.txt

Instructions for publishing to Espanso Hub or using a private/team repository template. Includes the command to install a package from a Git repository.

```bash
# Publish to Hub: fork https://github.com/espanso/hub, add your package, open a PR.
# For private/team use: fork https://github.com/espanso/espanso-external-repo-template
# then install with:
espanso install simple-package \
  --git https://github.com/yourorg/your-private-repo \
  --external

```

--------------------------------

### Start Espanso Application

Source: https://github.com/espanso/website/blob/main/docs/command lIne/cli_list.md

Start the Espanso application. Use the --unmanaged flag to run it without a system manager.

```bash
espanso start [FLAGS]
```

--------------------------------

### Install DEB Package

Source: https://github.com/espanso/website/blob/main/docs/install/linux.mdx

Install the downloaded DEB package using apt. You can ignore the 'unsandboxed as root' warning.

```bash
sudo apt install ./espanso-debian-x11-amd64.deb
```

--------------------------------

### Get Espanso Packages Directory

Source: https://github.com/espanso/website/blob/main/docs/packages/basics.md

Prints the file system path where Espanso stores installed packages.

```bash
espanso path packages
```

--------------------------------

### Espanso Default Match File Example

Source: https://github.com/espanso/website/blob/main/docs/get-started.md

An example of the default `base.yml` file, showing how to define simple text replacement matches.

```yaml
# espanso match file

# For a complete introduction, visit the official docs at: https://espanso.org/docs/

# You can use this file to define the base matches (aka snippets)
# that will be available in every application when using espanso.

# Matches are substitution rules: when you type the "trigger" string
# it gets replaced by the "replace" string.
matches:
  # Simple text replacement
  - trigger: ":espanso"
    replace: "Hi there!"
...
```

--------------------------------

### Install Espanso Package

Source: https://github.com/espanso/website/blob/main/docs/packages/basics.md

Installs a package from the Espanso Hub. Replace `<package_name>` with the desired package identifier.

```bash
espanso install <package_name>
```

```bash
espanso install lorem
```

--------------------------------

### Install Package from GitHub/GitLab Repository

Source: https://github.com/espanso/website/blob/main/docs/packages/external-packages.md

Use this command to install a package from a public GitHub or GitLab repository. Ensure the repository follows the Espanso Package Specification.

```bash
espanso install dummy-package --git https://github.com/espanso/dummy-repository --external
```

--------------------------------

### Install Espanso Package

Source: https://github.com/espanso/website/blob/main/docs/command lIne/cli_list.md

Install a package from the Espanso Hub. Use flags like --force to overwrite or --refresh-index for the latest index.

```bash
espanso package install [FLAGS] [OPTIONS] [package_name]
```

--------------------------------

### Package README Example

Source: https://context7.com/espanso/website/llms.txt

A standard Markdown file for describing the package's purpose and usage.

```markdown
<!-- README.md -->
# Simple Package
This package demonstrates how to create and publish an Espanso package.

```

--------------------------------

### Start Espanso Service

Source: https://github.com/espanso/website/blob/main/docs/install/linux/_wayland-final-steps.mdx

Start the Espanso service after registering it. This ensures Espanso is running and ready to use.

```bash
espanso start
```

--------------------------------

### Install Espanso using Homebrew

Source: https://github.com/espanso/website/blob/main/docs/install/mac.mdx

Use this command to install Espanso via the Homebrew package manager. Ensure Homebrew is installed on your system.

```bash
brew install espanso
```

--------------------------------

### espanso install

Source: https://github.com/espanso/website/blob/main/docs/command lIne/cli_list.md

Install espanso packages from the espanso Hub or external repositories.

```APIDOC
## install

Install a package

### USAGE:
    espanso install [FLAGS] [OPTIONS] [package_name]

### FLAGS:
    -e, --external          Allow installing packages from non-verified repositories.
        --force             Overwrite the package if already installed
        --refresh-index     Request a fresh copy of the Espanso Hub package index instead of using the cached version.
        --use-native-git    If specified, espanso will use the 'git' command instead of trying direct methods.

### OPTIONS:
        --git <git>                  Git repository from which espanso should install the package.
        --git-branch <git-branch>    Force espanso to search for the package on a specific git branch
        --version <version>          Force a particular version to be installed instead of the latest available.

### ARGS:
    <package_name>    Package name
```

--------------------------------

### Register and Start Espanso Service

Source: https://github.com/espanso/website/blob/main/docs/install/linux/_x11-after-install.mdx

Register espanso as a systemd service for automatic startup and then start the service. This is typically done once.

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

# Start espanso
espanso start
```

--------------------------------

### Group Private Match Sets for Inclusion (CSS Example)

Source: https://github.com/espanso/website/blob/main/docs/matches/organizing-matches.md

Define private match sets (files starting with `_`) that are not loaded automatically. These can then be imported into other files or included in app-specific configurations.

```yaml
matches:
  - trigger: ":pad"
    replace: "padding: 10px"
```

--------------------------------

### Configuration Inheritance Example

Source: https://github.com/espanso/website/blob/main/docs/configuration/app-specific-configurations.md

Illustrates how app-specific configurations inherit options from the default configuration. Options defined in the app-specific file override those from the default.

```yaml
option_A: 10
option_B: 30
```

--------------------------------

### List Installed Espanso Packages

Source: https://github.com/espanso/website/blob/main/docs/packages/basics.md

Displays a list of all currently installed Espanso packages.

```bash
espanso package list
```

--------------------------------

### Example Filter for TextEdit App

Source: https://github.com/espanso/website/blob/main/docs/configuration/app-specific-configurations.md

This example demonstrates a simple `filter_class` configuration to match the TextEdit application on macOS, based on its detected window class.

```yaml
filter_class: "TextEdit"
```

--------------------------------

### Start Espanso with Custom Configuration Directories

Source: https://github.com/espanso/website/blob/main/docs/sync.md

Alternatively, use command-line parameters to specify custom directories for Espanso's configuration, packages, and runtime data. This is useful for temporary or script-based launches.

```bash
--config_dir
--package_dir
--runtime_dir
```

--------------------------------

### Install Espanso using Chocolatey

Source: https://github.com/espanso/website/blob/main/docs/install/win.mdx

Install Espanso using the Chocolatey package manager. Ensure Chocolatey is installed on your system before running this command.

```cmd
choco install espanso
```

--------------------------------

### Basic package.yml Example

Source: https://github.com/espanso/website/blob/main/docs/packages/package-specification.md

Defines the main matches (snippets) for a package. This file follows the same format as regular match files.

```yaml
matches:
  - trigger: ":hello"
    replace: "Hello from package"

  - trigger: ":another"
    replace: "Another snippet from the example package"
```

--------------------------------

### Install Espanso AppImage

Source: https://github.com/espanso/website/blob/main/docs/install/linux.mdx

Install Espanso using the AppImage for any Linux distribution. This involves downloading the AppImage, making it executable, and registering it as a command.

```bash
# Create the $HOME/opt destination folder
mkdir -p ~/opt
# Download the AppImage inside it
wget -O ~/opt/Espanso.AppImage 'https://github.com/espanso/espanso/releases/download/v2.2.0-beta.1/Espanso-x86_64.AppImage'
# Make it executable
chmod u+x ~/opt/Espanso.AppImage
# Create the "espanso" command alias
sudo ~/opt/Espanso.AppImage env-path register

```

--------------------------------

### Install Linux Packages for X11

Source: https://github.com/espanso/website/blob/main/docs/install/linux.mdx

Installs essential build tools and development libraries required for compiling Espanso on Ubuntu/Debian systems for X11.

```bash
sudo apt update && sudo apt install build-essential git libx11-dev libxtst-dev libxkbcommon-dev libdbus-1-dev libssl-dev libwxgtk3.*-dev
```

--------------------------------

### Install Linux Packages for Wayland (Fedora)

Source: https://github.com/espanso/website/blob/main/docs/install/linux.mdx

Installs essential build tools and development libraries required for compiling Espanso on Fedora systems for Wayland.

```bash
sudo dnf install @development-tools gcc-c++ wl-clipboard libxkbcommon-devel dbus-devel wxGTK-devel.x86_64
```

--------------------------------

### Start Espanso Service

Source: https://github.com/espanso/website/blob/main/docs/command lIne/cli_list.md

Start the Espanso service. The --unmanaged flag allows running it outside of a system manager.

```bash
espanso service start [FLAGS]
```

--------------------------------

### Install Espanso via DNF (Fedora Wayland)

Source: https://github.com/espanso/website/blob/main/docs/install/linux.mdx

Installs the Espanso Wayland package on Fedora-based systems after adding the Terra repository.

```bash
sudo dnf install espanso-wayland
```

--------------------------------

### Install Wayland DEB Package

Source: https://github.com/espanso/website/blob/main/docs/install/linux.mdx

Installs the downloaded Espanso Wayland .deb package on Ubuntu/Debian systems.

```bash
sudo apt install ./espanso-debian-wayland-amd64.deb
```

--------------------------------

### Install Linux Packages for Wayland (Ubuntu/Debian)

Source: https://github.com/espanso/website/blob/main/docs/install/linux.mdx

Installs essential build tools and development libraries required for compiling Espanso on Ubuntu/Debian systems for Wayland.

```bash
sudo apt update && sudo apt install build-essential git wl-clipboard libxkbcommon-dev libdbus-1-dev libssl-dev libwxgtk3.*-dev
```

--------------------------------

### Install Espanso using winget

Source: https://github.com/espanso/website/blob/main/docs/install/win.mdx

Use the Windows Package Manager (winget) to install Espanso. This is a convenient command-line method for managing software on Windows.

```cmd
winget install --id=Espanso.Espanso -e
```

--------------------------------

### Install Linux Packages for Wayland (Arch/Manjaro)

Source: https://github.com/espanso/website/blob/main/docs/install/linux.mdx

Installs essential build tools and development libraries required for compiling Espanso on Arch/Manjaro systems for Wayland.

```bash
sudo pacman -S --needed git dbus base-devel wl-clipboard wxwidgets-gtk3
```

--------------------------------

### Install Espanso with Terra RPM Package

Source: https://github.com/espanso/website/blob/main/docs/install/linux.mdx

Install Espanso on Fedora-based systems after adding the Terra repository. This command uses dnf to install the espanso-x11 package.

```bash
sudo dnf install espanso-x11
```

--------------------------------

### Force Espanso Package Installation

Source: https://github.com/espanso/website/blob/main/docs/packages/basics.md

Forces the installation of a package, even if it is already installed. Useful for overwriting local changes or rolling back to an official version.

```bash
espanso install lorem --force
```

--------------------------------

### Platform-Specific Filter Example (Windows)

Source: https://github.com/espanso/website/blob/main/docs/configuration/app-specific-configurations.md

This `filter_exec` example is specific to Windows and will only match the Telegram application if it's running on a Windows operating system.

```yaml
filter_exec: Telegram.exe
```

--------------------------------

### Python Script Example for Espanso

Source: https://context7.com/espanso/website/llms.txt

Example Python script that accesses Espanso variables as environment variables (e.g., ESPANSO_MYVAR). Prints a greeting.

```python
# %CONFIG%/scripts/greet.py
import os
# Access Espanso variables as ESPANSO_<VARNAME> environment variables
myvar = os.environ.get('ESPANSO_MYVAR', 'World')
print(f"Hello, {myvar}!")
```

--------------------------------

### Install Specific Version of Espanso Package

Source: https://github.com/espanso/website/blob/main/docs/packages/basics.md

Installs a specific version of a package. Use this when you need a particular release rather than the latest.

```bash
espanso install <package_name> --version <package_version>
```

```bash
espanso install html-utils-package --version 0.1.0
```

--------------------------------

### Using Forms with Shell Extension

Source: https://github.com/espanso/website/blob/main/docs/matches/forms.md

This example demonstrates how to use a form with the shell extension. The form's input is passed to a shell command, and the output is used in the replacement text.

```yaml
- trigger: ":rev"
  replace: "{{reversed}}"
  vars:
  - name: form1
    type: form
    params:
      layout: |
        Reverse [[name]]
  - name: reversed
    type: shell
    params:
     cmd: "echo '{{form1.name}}' | rev"
```

--------------------------------

### Clipboard Extension for Dynamic Content

Source: https://github.com/espanso/website/blob/main/docs/matches/extensions.mdx

Integrate the Clipboard extension to insert the current content of the system clipboard into your replacements. This is demonstrated with an example for creating HTML links.

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

--------------------------------

### Execute Python Script with Script Extension (Array Args)

Source: https://github.com/espanso/website/blob/main/docs/matches/extensions.mdx

An alternative syntax for specifying script arguments as a YAML array. This is functionally equivalent to the previous example.

```yaml
          args: [python, /path/to/your/script.py]
```

--------------------------------

### Basic Regex Trigger Example

Source: https://github.com/espanso/website/blob/main/docs/matches/regex-triggers.md

Use a simple regex pattern to match multiple variations of a trigger. Note the double backslash required for escaping in YAML.

```yaml
  - regex: ":greet\\d"
    replace: "Hello!"
```

--------------------------------

### Populate Form Choices with Shell Command Output

Source: https://github.com/espanso/website/blob/main/docs/matches/examples.md

Use the output of a shell command to populate a form's choice control. This example implements a rudimentary file-picker.

```yaml
  - trigger: ":file"
    replace: "{{form1.file}}"
    vars:
      - name: files
        type: shell
        params:
          cmd: "find ~/Documents -maxdepth 1"
      - name: form1
        type: form
        params:
          layout: |
            Select file:
            [[file]]
          fields:
            file:
              type: list
              values: "{{files}}"
```

--------------------------------

### Verbose Form Syntax with Fields

Source: https://github.com/espanso/website/blob/main/docs/matches/forms.md

This example shows the verbose form syntax with the `fields` parameter, allowing for custom controls like multiline text inputs and choice lists.

```yaml
- trigger: ":form"
  replace: "Hey {{form1.name}}, how are you? Do you like {{form1.fruit}}?"
  vars:
    - name: "form1"
      type: form
      params:
        layout: "Name: [[name]] 
Fruit: [[fruit]]"
        fields:
          name:
            multiline: true
          fruit:
            type: list # or `choice`
            values:
              - Apples
              - Bananas
              - Oranges
              - Peaches
```

--------------------------------

### Espanso Configuration Directory Structure

Source: https://github.com/espanso/website/blob/main/docs/get-started.md

Default structure of the Espanso configuration directory after a fresh installation.

```yaml
$CONFIG/
  config/
    default.yml
  match/
    base.yml
```

--------------------------------

### Download Wayland DEB Package

Source: https://github.com/espanso/website/blob/main/docs/install/linux.mdx

Downloads the Espanso Wayland .deb package for Debian-based systems. Ensure you have `wget` installed.

```bash
wget https://github.com/espanso/espanso/releases/download/v2.2.0/espanso-debian-wayland-amd64.deb
```

--------------------------------

### Espanso Package Management Commands

Source: https://github.com/espanso/website/blob/main/docs/command lIne/cli_list.md

Manage Espanso packages with install, list, uninstall, and update subcommands.

```bash
espanso package install
espanso package list
espanso package uninstall
espanso package update
```

--------------------------------

### Calculate Sum with Regex and Shell Command (Direct Variable Injection)

Source: https://github.com/espanso/website/blob/main/docs/matches/regex-triggers.md

An alternative to the previous example, this snippet shows how to directly inject captured regex groups as variables into the shell command. This method is often more concise.

```yaml
          cmd: "expr {{num1}} + {{num2}}"
```

--------------------------------

### Espanso: No Quotes Example

Source: https://github.com/espanso/website/blob/main/docs/matches/quotes.md

Using no quotes for `trigger` and `replace` values. This is generally permissive but requires quotes when using escape sequences (e.g., `\n`) or when strings start with YAML reserved indicators.

```yml
  - trigger: :test
    replace: something
```

--------------------------------

### Importing Match Sets from External Locations

Source: https://github.com/espanso/website/blob/main/docs/matches/organizing-matches.md

Use the `imports` keyword to load match sets from paths outside your main configuration directory. This is useful for shared configurations or organizing complex setups.

```yaml
# Import other matches from external locations
imports:
  - "/path/to/other/matchsets.yml"
  - "/path/to/shared/google/drive/matches.yml"

matches:
  - trigger: ":company"
    replace: "This is just a normal trigger I use at my company"
```

--------------------------------

### Manually Restart Espanso

Source: https://github.com/espanso/website/blob/main/docs/get-started.md

If Espanso does not automatically reload after a configuration change or package installation, manually restart it using the `espanso restart` command.

```bash
espanso restart
```

--------------------------------

### Include Tomorrow's Date with Date Extension

Source: https://github.com/espanso/website/blob/main/docs/matches/extensions.mdx

Add future dates to your matches by using the `offset` parameter with a positive value in seconds. This example adds 24 hours.

```yaml
  - trigger: ":tomorrow"
    replace: "{{mytime}}"
    vars:
      - name: mytime
        type: date
        params:
          format: "%x"
          offset: 86400
```

--------------------------------

### Get Espanso Configuration Path

Source: https://github.com/espanso/website/blob/main/docs/sync.md

Use this command to determine the current configuration path Espanso is using on your system. This path is essential for setting up symbolic links.

```bash
espanso path config
```

--------------------------------

### Shell Extension for External Commands

Source: https://github.com/espanso/website/blob/main/docs/matches/extensions.mdx

Leverage the Shell extension to execute shell commands and include their output in replacements. This example fetches the public IP address using `curl`.

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

--------------------------------

### Espanso Package Manager CLI Commands

Source: https://context7.com/espanso/website/llms.txt

Manage snippet packs from Espanso Hub or Git repositories using the `espanso install`, `uninstall`, `list`, `path`, `update`, and `package update` commands. Supports specific versions and force reinstalls.

```bash
# Install a package from Espanso Hub
espanso install basic-emojis

# Install a specific version
espanso install html-utils-package --version 0.1.0

# Force reinstall (overwrite local edits)
espanso install lorem --force

# Uninstall a package
espanso uninstall lorem

# List installed packages
espanso package list

# Show where packages are stored
espanso path packages

# Update a single package
espanso package update lorem

# Update all packages
espanso package update all

# Install from a GitHub/GitLab repository (must follow package spec)
espanso install dummy-package \
  --git https://github.com/espanso/dummy-repository \
  --external

```

--------------------------------

### Open Default Configuration File with CLI

Source: https://github.com/espanso/website/blob/main/docs/configuration/basics.md

Use the `espanso edit` command to open the `match/base.yml` file in your default system editor.

```bash
espanso edit
```

--------------------------------

### Deploy Website to GitHub Pages

Source: https://github.com/espanso/website/blob/main/README.md

Builds the website and pushes it to the 'gh-pages' branch, suitable for GitHub Pages hosting. Replace <Your GitHub username> with your actual username.

```bash
GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
```

--------------------------------

### Compile Espanso from Source

Source: https://github.com/espanso/website/blob/main/docs/install/linux.mdx

Clone the Espanso repository and compile the binary in release mode with specific features enabled. This process may take a significant amount of time.

```bash
# Clone the Espanso repository
git clone https://github.com/espanso/espanso

cd espanso

# Compile espanso in release mode
# NOTE: this will take a while (~5/15 minutes)
cargo build -p espanso --release --no-default-features --features modulo,vendored-tls,wayland
```

--------------------------------

### Customizing README.md

Source: https://github.com/espanso/website/blob/main/docs/packages/creating-a-package.md

Describe your package and add documentation using Markdown syntax. This content will be displayed on the package's Hub page.

```markdown
This is a **simple package** and its purpose
is to show how to create new Espanso packages!
```

--------------------------------

### Reading Environment Variables in WSL (Windows)

Source: https://github.com/espanso/website/blob/main/docs/matches/variables.md

Illustrates how to read environment variables in WSL on Windows using the $NAME syntax.

```bash
echo $ESPANSO_FORM1_NAME
```

--------------------------------

### Compile Espanso from Source (X11)

Source: https://github.com/espanso/website/blob/main/docs/install/linux.mdx

Clones the Espanso repository and compiles it in release mode. This process can take a significant amount of time.

```bash
# Clone the Espanso repository
git clone https://github.com/espanso/espanso

cd espanso

# Compile espanso in release mode
# NOTE: this will take a while (~5/15 minutes)
cargo build -p espanso --release --no-default-features --features vendored-tls,modulo
```

--------------------------------

### Remove Old Homebrew Tap for Espanso

Source: https://github.com/espanso/website/blob/main/docs/install/mac.mdx

If upgrading from an older Espanso version installed via Homebrew, you might need to remove the previous tap. Use the appropriate command based on your previous installation.

```bash
brew untap federico-terzi/espanso
```

```bash
brew untap espanso/espanso
```

--------------------------------

### espanso uninstall

Source: https://github.com/espanso/website/blob/main/docs/command lIne/cli_list.md

Remove an installed espanso package.

```APIDOC
## uninstall

Remove a package
```

--------------------------------

### Uninstall Espanso Package

Source: https://github.com/espanso/website/blob/main/docs/command lIne/cli_list.md

Remove an installed package by specifying its name.

```bash
espanso package uninstall [package_name]
```

--------------------------------

### Build Static Website Content

Source: https://github.com/espanso/website/blob/main/README.md

Generates static website files into the 'build' directory. These files can be hosted on any static hosting service.

```bash
yarn build
```

--------------------------------

### Reading Environment Variables in Command Prompt (Windows)

Source: https://github.com/espanso/website/blob/main/docs/matches/variables.md

Illustrates how to read environment variables in the Windows Command Prompt using the %NAME% syntax.

```cmd
echo %ESPANSO_FORM1_NAME%
```

--------------------------------

### Update All Espanso Packages

Source: https://github.com/espanso/website/blob/main/docs/packages/basics.md

Updates all installed Espanso packages to their latest available versions simultaneously.

```bash
espanso package update all
```

--------------------------------

### Create Symbolic Link for Espanso Configuration on Windows

Source: https://github.com/espanso/website/blob/main/docs/sync.md

On Windows, use the `mklink /J` command to create a directory junction (symbolic link) that points your original Espanso configuration directory to a new location, typically within a cloud storage folder.

```batch
mklink /J "$CONFIG" "C:\Users\user\Dropbox\espanso"
```

--------------------------------

### Update Espanso Package

Source: https://github.com/espanso/website/blob/main/docs/packages/basics.md

Updates a specific installed package to its latest available version. Replace `<package_name>` with the package to update.

```bash
espanso package update <package_name>
```

```bash
espanso package update lorem
```

--------------------------------

### Create Symbolic Link for Espanso Configuration on Linux

Source: https://github.com/espanso/website/blob/main/docs/sync.md

On Linux, use the `ln -s` command to create a symbolic link that points your original Espanso configuration directory to a new location, typically within a cloud storage folder.

```bash
ln -s "/home/user/Dropbox/espanso" "$CONFIG"
```

--------------------------------

### Espanso Service Management Commands

Source: https://github.com/espanso/website/blob/main/docs/command lIne/cli_list.md

Manage the Espanso Linux service, including checking status, registering, starting, stopping, and unregistering.

```bash
espanso service [SUBCOMMAND]
```

--------------------------------

### Espanso Command-Line Interface Utilities

Source: https://context7.com/espanso/website/llms.txt

Common CLI commands for managing Espanso's status, configuration, matches, and logs. Includes starting/stopping the service, enabling/disabling expansions, editing files, and viewing paths.

```bash
# Check if Espanso is running
espanso status

# Start / stop / restart
espanso start
espanso stop
espanso restart

# Enable / disable / toggle expansions
espanso cmd enable
espanso cmd disable
espanso cmd toggle

# Open the default match file in the system editor
espanso edit

# Edit a specific file (file name, relative path, or with extension)
espanso edit match/emails.yml
espanso edit emails           # resolves to match/emails.yml

# Show config and package paths
espanso path
espanso path config
espanso path packages

# List all active matches
espanso match list
espanso match list --help

# Trigger a match programmatically
espanso match exec -t ":br"

# View logs (useful when debug: true is set on a shell/script extension)
espanso log

```

--------------------------------

### Check Espanso Status on Linux

Source: https://github.com/espanso/website/blob/main/docs/get-started.md

Use this command in the terminal to verify if Espanso is currently running on your Linux system. This is a crucial step after installation.

```bash
espanso status
```

--------------------------------

### Create a Selection Dialog with Choice Extension

Source: https://github.com/espanso/website/blob/main/docs/matches/extensions.mdx

Use the Choice extension to present a selection dialog to the user. This is useful for choosing between multiple predefined values.

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

--------------------------------

### Set Custom Editor Environment Variable (Linux/macOS)

Source: https://github.com/espanso/website/blob/main/docs/configuration/basics.md

Configure your preferred text editor by setting the `EDITOR` environment variable. This example uses Vim.

```bash
EDITOR=/usr/bin/vim
```

--------------------------------

### Group Private Match Sets for Inclusion

Source: https://github.com/espanso/website/blob/main/docs/matches/organizing-matches.md

Define private match sets (files starting with `_`) that are not loaded automatically. These can then be imported into other files or included in app-specific configurations.

```yaml
matches:
  - trigger: ":log"
    replace: "console.log($|$);"
```

--------------------------------

### Check Desktop Environment

Source: https://github.com/espanso/website/blob/main/docs/install/linux.mdx

Run this command in the terminal to determine if your system uses X11 or Wayland.

```bash
echo $XDG_SESSION_TYPE
```

--------------------------------

### Set Espanso Configuration Directories via Environment Variables

Source: https://github.com/espanso/website/blob/main/docs/sync.md

Use these environment variables to specify custom directories for Espanso's configuration, packages, and runtime data when running in unmanaged mode. This allows for flexible configuration management.

```bash
ESPANSO_CONFIG_DIR
ESPANSO_PACKAGE_DIR
ESPANSO_RUNTIME_DIR
```

--------------------------------

### Special Character Replacement with Unicode

Source: https://github.com/espanso/website/blob/main/docs/matches/basics.md

Replace triggers with special characters using Unicode escape sequences. This example demonstrates replacing ':euro' with the Euro symbol.

```yaml
- trigger: :euro
  replace: "\u20ac"
```

--------------------------------

### espanso edit Command

Source: https://github.com/espanso/website/blob/main/docs/command lIne/cli_list.md

Open configuration files in your default text editor. You can specify a target file or it defaults to 'match/base.yml'.

```bash
USAGE:
    espanso edit [target_file]

ARGS:
    <target_file>   Defaults to "match/base.yml". 
        It contains the relative path of the file you want to edit, such as 'config/default.yml' or 'match/base.yml'. 
        For convenience, you can also specify the name directly and espanso will figure out the path. For example, specifying 'email' is equivalent to 'match/email.yml'.
```

--------------------------------

### Include Yesterday's Date with Date Extension

Source: https://github.com/espanso/website/blob/main/docs/matches/extensions.mdx

Include past dates by specifying a negative value for the `offset` parameter in seconds. This example subtracts 24 hours.

```yaml
  - trigger: ":yesterday"
    replace: "{{mytime}}"
    vars:
      - name: mytime
        type: date
        params:
          format: "%x"
          offset: -86400
```

--------------------------------

### Espanso Configuration Synchronization Methods

Source: https://context7.com/espanso/website/llms.txt

Methods for syncing Espanso configuration across machines, including an experimental environment variable method (v2+) and the classic symlink method for macOS/Linux.

```bash
# --- Experimental: env-var method (v2 onwards) ---
# Stop the managed service first
espanso stop
espanso service unregister

# Start unmanaged, pointing at a synced directory
espanso --config_dir "$HOME/Dropbox/espanso" start --unmanaged

# --- Classic symlink method (macOS/Linux) ---
# 1. Move config to Dropbox
mv "$HOME/Library/Application Support/espanso" "$HOME/Dropbox/espanso"

# 2. Create symlink in original location
ln -s "$HOME/Dropbox/espanso" "$HOME/Library/Application Support/espanso"

```

--------------------------------

### Use Global Variables in a Match

Source: https://github.com/espanso/website/blob/main/docs/matches/basics.md

Utilize a globally defined variable within a match to dynamically insert its value. This example uses the 'greet' variable defined previously.

```yaml
- trigger: :hello
  replace: "{{greet}} Jon"
```

--------------------------------

### Replace Default Includes with `includes`

Source: https://github.com/espanso/website/blob/main/docs/configuration/include-and-exclude.md

Use `includes` to define a completely new set of match files, ignoring any default Espanso configurations. This is useful for app-specific configurations.

```yaml
filter_exec: Telegram

includes:
  - "../match/jokes.yml"
```

--------------------------------

### Espanso Configuration Directory Structure

Source: https://github.com/espanso/website/blob/main/docs/configuration/basics.md

This illustrates the default directory structure for Espanso configurations, with `config` for behavior and `match` for snippets.

```yaml
config/
  default.yml
match/
  base.yml
```

--------------------------------

### Define Global Variables in Espanso

Source: https://github.com/espanso/website/blob/main/docs/matches/basics.md

Define global variables in your `match/base.yml` file to make them accessible across multiple matches. This example shows how to define a simple 'greet' variable.

```yaml
global_vars:
  - name: greet
    type: echo
    params:
      echo: Hey
```

--------------------------------

### Edit Configuration File by Name with CLI

Source: https://github.com/espanso/website/blob/main/docs/configuration/basics.md

For convenience, you can omit the path and `.yml` extension when editing files. Espanso will attempt to locate the correct file, typically in the `match` directory.

```bash
espanso edit emails
```

--------------------------------

### espanso cmd

Source: https://github.com/espanso/website/blob/main/docs/command lIne/cli_list.md

Send a command to the espanso daemon to manage expansions.

```APIDOC
## cmd

Send a command to the espanso daemon.

### USAGE:
    espanso cmd [SUBCOMMAND]

### SUBCOMMANDS:
    disable    Disable expansions.
    enable     Enable expansions.
    search     Open the espanso search bar.
    toggle     Enable/Disable expansions.
```

--------------------------------

### Register Espanso as a Systemd Service

Source: https://github.com/espanso/website/blob/main/docs/install/linux/_wayland-final-steps.mdx

Register Espanso to run as a systemd service for automatic startup on boot. This command only needs to be run once.

```bash
espanso service register
```

--------------------------------

### Case Propagation for Trigger Casing

Source: https://github.com/espanso/website/blob/main/docs/matches/basics.md

Enable case propagation to match the casing of the trigger in the replacement text. This example shows how 'alh' can expand to 'although', 'Although', or 'ALTHOUGH' based on input.

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

--------------------------------

### Configure Keyboard Layout

Source: https://github.com/espanso/website/blob/main/docs/install/linux/_wayland-final-steps.mdx

Specify your keyboard layout in the default.yml configuration file if you are using a non-US keyboard layout. This ensures correct input detection.

```yaml
keyboard_layout:
  layout: "it"
```

--------------------------------

### Regex for Categorizing Matches

Source: https://github.com/espanso/website/blob/main/docs/matches/examples.md

Utilize regex triggers to categorize matches, allowing for structured input like code snippets or contacts. This example shows how to define triggers for different subcategories.

```yaml
  - regex: "(code|cd) (all|py) (all|pr)" # Code Category - Python Subcategory - Print
    replace: "print(\"Hello World\")"
```

```yaml
  - regex: "(code|cd) (all|py) (all|fn)" # Code Category - Python Subcategory - Function
    replace: "def myPythonFunction():"
```

```yaml
  - regex: "(code|cd) (all|js) (all|fn)" # Code Category - Javascript Subcategory - Function
    replace: "function main(){}"
```

```yaml
  - regex: "(contact|ct) (all|n) (all|jj)" # Contact Category - Name Subcategory - John Jacobs
    replace: "John Jacobs"
```

```yaml
  - regex: "(contact|ct) (all|n) (all|js)" # Contact Category - Name Subcategory - John Stuart
    replace: "John Stuart"
```

```yaml
  - regex: "(contact|ct) (all|e) (all|jj)" # Contact Category - Email Subcategory - John Jacobs
    replace: "john.jacobs@example.com"
```

--------------------------------

### Espanso Path Commands

Source: https://github.com/espanso/website/blob/main/docs/command lIne/cli_list.md

Print various Espanso directory paths for configuration and data files.

```bash
espanso path [SUBCOMMAND]
```

--------------------------------

### Default Global Variable Evaluation Order

Source: https://github.com/espanso/website/blob/main/docs/matches/variables.md

This example demonstrates the default evaluation order of global and local variables. Global variables may be evaluated before local variables if no explicit dependencies are set.

```yaml
global_vars:
  - name: three
    type: shell
    params:
      cmd: "echo three"

matches:
  - trigger: ":hello"
    replace: "hello {{one}} {{two}} {{three}}"
    vars:
      - name: one
        type: shell
        params:
          cmd: "echo one"
      - name: two
        type: shell
        params:
          cmd: "echo two"
```

--------------------------------

### Create Espanso Symlink (Windows CMD)

Source: https://context7.com/espanso/website/llms.txt

Use this command in an administrator Command Prompt to create a symbolic link for Espanso's configuration directory on Windows.

```batch
mklink /J "C:\Users\user\AppData\Roaming\espanso" "C:\Users\user\Dropbox\espanso"
```

--------------------------------

### Restart Espanso Service (Service Subcommand)

Source: https://github.com/espanso/website/blob/main/docs/command lIne/cli_list.md

Restart the Espanso service. Use --unmanaged to run without a system manager.

```bash
espanso service restart [FLAGS]
```

--------------------------------

### App-Specific Espanso Configurations

Source: https://context7.com/espanso/website/llms.txt

Create YAML files in `$CONFIG/config/` to apply different options or matches for specific applications using regex filters. Use `#detect#` to find app identifiers.

```yaml
# $CONFIG/config/telegram.yml — disable Espanso in Telegram
filter_exec: Telegram
enable: false

---

# $CONFIG/config/chrome.yml — add email snippets only in Chrome
filter_exec: chrome
extra_includes:
  - "../match/_email.yml"

---

# $CONFIG/config/vscode.yml — clipboard backend + code snippets in VS Code
filter_title: "Visual Studio Code"
backend: clipboard
extra_includes:
  - "../match/_code_snippets.yml"

---

# $CONFIG/config/youtube.yml — disable on YouTube tab
filter_title: YouTube
enable: false

---

# $CONFIG/config/terminal.yml — remove built-in patch to use CTRL+V paste
filter_class: terminal
apply_patch: false
```

--------------------------------

### Regex Trigger with Named Group for Arguments

Source: https://github.com/espanso/website/blob/main/docs/matches/regex-triggers.md

Capture dynamic input using a named group `(?P<name>exp)` and use it in the replacement string via `{{name}}`. This example captures a person's name.

```yaml
  - regex: ":greet\\((?P<person>.*)\\)"
    replace: "Hi {{person}}!"
```

--------------------------------

### Control Active Matches Per Application

Source: https://context7.com/espanso/website/llms.txt

Use `includes`, `extra_includes`, `excludes`, and `extra_excludes` to manage which match files are active for specific applications. Files prefixed with an underscore are not auto-loaded.

```yaml
# $CONFIG/match/_email.yml  (underscore prefix = NOT auto-loaded)
matches:
  - trigger: ":contact"
    replace: |
      Hi,
      Thank you for contacting us!
      Best regards, The Support Team

---

# $CONFIG/config/browser.yml — enable email matches in browsers
filter_exec: "chrome|firefox"
extra_includes:
  - "../match/_email.yml"

---

# $CONFIG/config/telegram.yml — disable all-emojis package in Telegram
filter_exec: Telegram
extra_excludes:
  - "../match/packages/all-emojis/*"

---

# $CONFIG/config/slack.yml — replace ALL default includes with only jokes.yml
filter_exec: Slack
includes:
  - "../match/jokes.yml"
# use_standard_includes: false  # equivalent alternative

```

--------------------------------

### Download DEB Package for X11

Source: https://github.com/espanso/website/blob/main/docs/install/linux.mdx

Download the Espanso DEB package for Debian-based systems running X11. This command uses wget to fetch the package.

```bash
wget https://github.com/espanso/espanso/releases/download/v2.2.0-beta.1/espanso-debian-x11-amd64.deb
```