dotfiles/docs/ESPANSO.md

Espanso Quick Reference

Text expansion with 100+ pre-configured snippets using ..trigger syntax.

Controls

Action	Shortcut
Toggle on/off	ALT+SHIFT+E
Search snippets	ALT+SPACE
Restart	espanso restart
Status	espanso status
View logs	espanso log

---

Snippet Categories

Date & Time

Trigger	Output	Example
..date	Current date	2025-12-15
..sds	Filename-safe date	20251215
..time	Current time	14:30:45
..ts	ISO timestamp	2025-12-15T14:30:45.123Z
..utc	UTC datetime	2025-12-15 14:30:45.123 UTC
..dt	Local datetime	2025-12-15 14:30:45 EST
..udt	UTC datetime	2025-12-15 14:30:45 UTC
..ztime	Time with timezone	14:30:45.123 EST
..epoch	Unix timestamp	1702573845
..epochms	Unix ms timestamp	1702573845123
..month	Month name	December
..day	Day name	Saturday
..week	Week number	Week 50
..year	Year	2025

Git Commands

Trigger	Output
..gstat	git status
..gco	git checkout
..gcm	git commit -m ""
..glog	git log --oneline --graph --decorate --all
..gpush	git push origin
..gpull	git pull origin
..gbranch	git branch -a
..gdiff	git diff
..gadd	git add .
..branch	Current branch name (dynamic)

Docker Commands

Trigger	Output
..dps	docker ps
..dpsa	docker ps -a
..dcup	docker-compose up -d
..dcdown	docker-compose down
..dlog	docker logs -f
..dexec	docker exec -it
..dim	docker images
..dprune	docker system prune -af

System Info

Trigger	Output
..ip	Public IP (via curl)
..locip	Local IP

Code Templates

Trigger	Output
..bash	Bash script with shebang + set -euo pipefail
..python	Python script with main()
..she!	#!/usr/bin/env bash

Markdown

Trigger	Output
..mdcode	Code block (triple backticks)
..mdbash	Bash code block
..mdpy	Python code block
..mdjs	JavaScript code block
..mdtable	Table template
..mdlink	Link (prompts for text/url)
..mdimg	Image (prompts for alt/url)

Comments

Trigger	Output
..todo	// TODO:
..fixme	// FIXME:
..note	// NOTE:
..hack	// HACK:
..debug	// DEBUG:

Quick Commands

Trigger	Output
..ll	ls -lah
..la	ls -A
..grep	grep -rni "" .
..find	find . -name ""
..port	lsof -i :
..kill	kill -9
..proc	`ps aux
..disk	df -h
..mem	free -h

Navigation

Trigger	Output
..~	cd ~
..tmp	cd /tmp/
..logs	cd /var/log/

URLs

Trigger	Output
..gh	https://github.com
..gl	https://gitlab.com
..gist	https://gist.github.com
..so	https://stackoverflow.com
..reddit	https://reddit.com

Emoticons & Symbols

Trigger	Output
..shrug	¯\_(ツ)_/¯
..flip	(╯°□°)╯︵ ┻━┻
..unflip	┬─┬ ノ( ゜-゜ノ)
..lenny	( ͡° ͜ʖ ͡°)
..check	✓
..cross	✗
..arrow	→
..larrow	←

Quick Responses

Trigger	Output
..brb	Be right back
..omw	On my way
..tyvm	Thank you very much
..lgtm	Looks good to me
..wfm	Works for me
..ack	Acknowledged
..asap	As soon as possible

Lorem Ipsum

Trigger	Output
..lorem	One paragraph
..loremlong	Four paragraphs

Clipboard

Trigger	Output
..qp	Paste from primary selection (X11/Wayland)

---

Auto-Corrections

These work without the .. prefix:

Typo	Correction
teh	the
recieve	receive
definately	definitely
seperator	separator
occured	occurred
lenght	length
wierd	weird
thier	their

---

Personal Snippets

Edit ~/.dotfiles/espanso/match/personal.yml:

matches:
  - trigger: "..myemail"
    replace: "your.email@example.com"

  - trigger: "..myname"
    replace: "Your Full Name"

  - trigger: "..myphone"
    replace: "+1 (555) 123-4567"

  - trigger: "..sig"
    replace: |
      Best regards,
      Your Full Name
      your.email@example.com

  - trigger: "..myaddr"
    replace: |
      123 Main Street
      City, ST 12345

Run setup-espanso.sh to configure interactively.

---

Adding Custom Snippets

Edit ~/.dotfiles/espanso/match/base.yml:

Simple Replacement

matches:
  - trigger: "..hw"
    replace: "Hello, World!"

With Shell Command

  - trigger: "..uptime"
    replace: "{{output}}"
    vars:
      - name: output
        type: shell
        params:
          cmd: 'uptime -p'

With Date Formatting

  - trigger: "..today"
    replace: "Today is {{mydate}}"
    vars:
      - name: mydate
        type: date
        params:
          format: "%B %d, %Y"

With Form Input

  - trigger: "..mailto"
    replace: "<a href=\"mailto:{{email}}\">{{name}}</a>"
    vars:
      - name: email
        type: form
        params:
          layout: "Email: {{email}}"
      - name: name
        type: form
        params:
          layout: "Display name: {{name}}"

With Clipboard

  - trigger: "..cliplink"
    replace: "[{{clipboard}}]({{clipboard}})"
    vars:
      - name: clipboard
        type: clipboard

After editing: espanso restart

---

Config Files

~/.config/espanso/          (symlinked to ~/.dotfiles/espanso/)
├── config/
│   └── default.yml         # Global settings
└── match/
    ├── base.yml            # Main snippets (100+)
    ├── personal.yml        # Your personal info
    └── packages/           # Installed packages

---

Useful Commands

espanso status              # Check if running
espanso start               # Start service
espanso restart             # Restart service
espanso stop                # Stop service
espanso log                 # View logs
espanso edit                # Open config in editor
espanso match list          # List all triggers
espanso path                # Show config paths

---

Installing Packages

Browse packages: https://hub.espanso.org/

espanso install emoji          # :smile: → 😊
espanso install greek-letters  # :alpha: → α
espanso install math           # :sum: → ∑
espanso install lorem          # More lorem ipsum options
espanso package list           # Show installed
espanso package uninstall <n>  # Remove package

---

Troubleshooting

Espanso Not Starting

espanso service register    # Register as service
espanso start

Snippets Not Expanding

espanso restart
espanso log                 # Check for errors

Wrong Keyboard Layout

Edit ~/.config/espanso/config/default.yml:

backend: Clipboard          # Try different backend

Check Syntax

espanso --help              # Will error if YAML is invalid
espanso match list          # Lists triggers if syntax is OK

Wayland Issues

If using Wayland, you may need the Wayland-specific build:

# Check your session
echo $XDG_SESSION_TYPE

# Install Wayland version if needed
# (varies by distro)

---

Tips

1. Test snippets - Type them in any text field
2. Use search - ALT+SPACE to search all triggers
3. Escape triggers - Type slowly or add a space to prevent expansion
4. Backup config - It's in your dotfiles, so it syncs automatically
5. Restart after changes - espanso restart