The rough edges I hit while setting up `espanso/espanso` locally

Description and use

Setting up espanso: locate the config path, create a valid YAML file, check OS permissions, and test triggers across applications.

Problem

Users struggle with platform‑specific configuration paths, YAML syntax errors, and OS permission issues when installing the privacy‑first text expander espanso.

Outcome

Espanso is configured correctly across platforms, with valid YAML and necessary permissions, enabling reliable local text expansion.

Workflow

• 1. Run espanso path config to find the active configuration directory.
• 2. Create the match directory if it does not exist (e.g., mkdir -p ~/.config/espanso/match).
• 3. Add a minimal base.yml file with correct YAML indentation.
• 4. Restart espanso with espanso restart and verify status with espanso status.
• 5. Test triggers in various applications (editor, browser, terminal, password field).
• 6. If triggers fail, check logs and disable all matches except one to isolate the issue.
• 7. Grant Accessibility permission on macOS if required; verify Linux desktop environment compatibility.
• 8. Avoid expanding sensitive fields and use prefixes to prevent trigger collisions.

Evidence

The first setup gotcha is configuration location. Espanso uses platform-specific directories, so avoid hard-coding a path in scripts that must run on macOS, Linux, and Windows.

Source

On macOS, espanso may need Accessibility permission to detect and replace text in other applications.

Source