Espanso to FlitKey: YAML Migration Guide (2026)

1. Before you import: keep a reversible copy

Do not remove Espanso first. An import adds snippets to FlitKey; it does not alter the source YAML file or uninstall Espanso. Keeping both copies makes it easy to compare output and return to the old setup.

1. Run espanso path and note the configuration directory reported by Espanso. The exact location can change with the operating system and installation method.
2. Copy the entire Espanso configuration directory somewhere outside the live directory.
3. If you already use FlitKey, copy ~/.config/flitkey/config.json on Linux or %APPDATA%\flitkey\config.json on Windows.
4. Pause Espanso while testing imported triggers so two background processes do not react to the same abbreviation.

Espanso keeps matches in YAML files and allows multiple files. Import one file at a time. That gives you a clear count and makes a problematic file easier to isolate.

2. Importer Fidelity Corpus: What v0.6.0 Imports, Converts, or Skips

FlitKey's built-in parser in v0.6.0 reads Espanso YAML syntax and translates supported elements directly into local JSON records. To provide transparency, here is the exact feature-by-feature fidelity matrix:

3. Step-by-Step Import in FlitKey v0.6.0

1. Start FlitKey and open the main snippet-manager window.
2. Click Import in the top toolbar (in v0.6.0, this is a dedicated primary action).
3. Select Espanso YAML (.yml, .yaml) or AutoHotkey Script (.ahk) from the file type selector.
4. Select your match file. FlitKey parses the entries, reports the exact count of imported snippets, and warns if any unsupported scripts or forms were safely skipped.
5. Filter by Espanso: in the snippet list to inspect and verify newly added triggers.

You can also preview and test your conversion in your browser beforehand using our Online Config Converter.

4. Worked YAML Migration Example

The following sanitized Espanso YAML match block demonstrates both converted and skipped elements:

matches:
  # Supported: Static match
  - trigger: ":sig"
    label: "Engineering Signature"
    replace: "Kind regards,\nAlex Smith\nSenior DevOps"

  # Supported: Multiple triggers
  - triggers: [":thanks", ":ty"]
    replace: "Thank you for the detailed report!"

  # Supported: Dynamic placeholders
  - trigger: ":dt"
    replace: "Logged on: {{my_date}}"
    vars:
      - name: my_date
        type: date
        params:
          format: "%Y-%m-%d"

  # Unsupported: Shell command (safely skipped by FlitKey)
  - trigger: ":ip"
    replace: "{{output}}"
    vars:
      - name: output
        type: shell
        params:
          cmd: "curl -s ifconfig.me"

When imported into FlitKey v0.6.0, three native snippets are created in config.json:

5. Verify before switching

Use a disposable plain-text editor for the first pass. Test punctuation, Unicode, line breaks, and trigger collisions. Then test the applications that matter to you, such as a terminal, browser, Outlook, LibreOffice, or VS Code. Application behavior can differ, especially around synthetic keyboard input.

• Zero snippets found: confirm the file contains a top-level matches: list and static trigger/replace pairs.
• Only part of the file imported: split complex matches from static matches and import the smaller file.
• Replacement contains an unresolved Espanso variable: edit it into a supported FlitKey placeholder or keep that item in Espanso.
• Duplicate expansions: pause one app while testing. Once satisfied, enable only the tool that should own a trigger.
• Typed triggers do not work on Wayland: this is an explicit FlitKey limitation. Open Quick Insert from the app or tray, select the snippet, then paste from the clipboard. Read the Wayland workflow guide.

Migrate in batches: personal details first, then support replies, then developer or administrative snippets. Keep complex automation in Espanso until you have tested a simpler replacement.

6. Roll back without losing work

If the imported result is not useful, close FlitKey and restore the backed-up config.json to its original location. Restart FlitKey and confirm the previous snippet count. Resume Espanso only after you have disabled or removed conflicting triggers in FlitKey.

FlitKey stores snippets as local JSON. The app does not upload the imported file. Local storage reduces cloud exposure, but it is not a compliance certification; protect the configuration file with the same disk, account, and backup controls you use for any sensitive document.

What the importer report means

After a file is parsed, FlitKey reports counts rather than a silent success. Use those numbers against your inventory:

• Imported — static trigger/replace (and multi-trigger aliases) created as local snippets.
• Converted — date/clipboard-style variables rewritten to FlitKey placeholders such as {{date}} or {{clipboard}}.
• Skipped — shell, script, form, regex, or app-filter matches left untouched in Espanso on purpose.

If the imported count is far below your static-match inventory, split the YAML, fix top-level matches: structure, and re-import a smaller fixture before moving the rest of the library.

How this guide was checked

This guide was checked against FlitKey's importer source, automated importer tests, and the visible main-window Import flow. Espanso's official repository documents its file-based YAML configuration, variables, forms, packages, and experimental Wayland support. Product behavior may change after the versions named here.

• Espanso official repository and YAML example
• Espanso documentation
• FlitKey vs Espanso: decision guide
• All migration guides