Espanso Manager

A simple, browser-based GUI for managing Espanso text expansion snippets. No YAML editing required.

Disclaimer: This is an unofficial tool. It is not affiliated with or endorsed by the official Espanso project.

Features

• Create, edit, delete snippets through a clean web interface
• Search across all your snippets instantly
• File management — activate, archive, import, and export .yml match files
• Auto-backup before every change, with one-click restore
• Labels — give each snippet a human-readable name (saved as YAML comments)
• Bilingual — English/Russian interface switcher
• Cross-platform — Works on Windows, macOS, and Linux

Quick Start

1. Install Espanso

See docs/espanso-setup.md for instructions.

2. Run the Manager

Windows:

start.bat

macOS / Linux:

chmod +x start.sh
./start.sh

Or manually (any OS):

pip install -r requirements.txt
python tray_app.py

The browser will open automatically at http://localhost:5567.

3. First Use

• Click "+ New Record" to create your first snippet
• Use the Search bar to find existing snippets
• Visit the Files & Archive tab to import/export match files
• Switch language using the RU/EN button in the header

For Users

Action	How
Create snippet	+ New Record → fill in Trigger and Replace
Edit snippet	Click "Edit" on the card
Delete snippet	Click "Delete" → confirm
Search	Type in the search bar (filters by name, trigger, or text)
Archive a file	Tab "Files & Archive" → "Archive"
Import snippets	Tab "Files & Archive" → drag & drop a .yml file
Restore backup	Tab "Backups" → "Restore"

For Developers

Project Structure

espanso-manager/
├── app.py              # Flask backend (CRUD API, YAML parsing)
├── tray_app.py         # Launcher (starts server + opens browser)
├── start.bat           # Windows launcher (auto-finds Python, installs deps)
├── start.sh            # Linux/macOS launcher
├── requirements.txt    # Python dependencies
├── templates/
│   └── index.html      # Frontend (HTML/CSS/JS, single file)
└── docs/
    └── espanso-setup.md  # How to install Espanso

How It Works

1. tray_app.py starts a Flask server on localhost:5567
2. The server reads/writes .yml files from your Espanso match/ directory
3. All changes are backed up automatically before being written
4. YAML is validated before saving to prevent corruption

API Endpoints

Method	Endpoint	Description
GET	/api/matches	List all matches
POST	/api/matches	Create a new match
PUT	/api/matches/<file>/<index>	Update a match
DELETE	/api/matches/<file>/<index>	Delete a match
GET	/api/files	List active and inactive files
POST	/api/files/move	Move file between active/archive
GET	/api/export/<file>	Download a match file
POST	/api/import	Import a .yml file
GET	/api/backups	List backups
POST	/api/backups/<name>/restore	Restore a backup

License

MIT License — see LICENSE for details.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

---

Vibecoded with Qwen 3.6 Plus Free