Triggers and Matches

Triggers are the keywords you type that get expanded. Matches define what they expand to.

How Expansion Works

Match File Format

Match files are YAML files placed in ~/.config/cli-expander/matches/. They define your triggers and their replacements.

matches:
  - trigger: ":hello"
    replace: "Hello World!"

Simple Text Replacement

The most basic match replaces a trigger with static text:

- trigger: ":thanks"
  replace: "Thank you for your help!"

Multiple Triggers

A match can have multiple triggers that all expand to the same thing:

- triggers: [":hello", ":hi", ":hey"]
  replace: "Greetings!"

Multi-line Replacement

Use YAML's | operator for multi-line expansions:

- trigger: ":sig"
  replace: |
    Best regards,
    John Doe
    Engineering Team

Match Options

Option	Type	Default	Description
trigger	string	—	Single trigger keyword
triggers	array	—	Multiple triggers for same match
replace	string	—	Text to replace trigger with
form	string	—	Form layout with [[field]] placeholders
form_fields	object	—	Field configuration for forms
vars	array	—	Variable definitions
global_vars	array	—	Shared variables for all matches in file
force_mode	string	—	Injection mode override: auto, clipboard, keys
propagate_case	bool	false	Match case of typed trigger
uppercase_style	string	—	capitalize_words for multi-word case
word	bool	false	Word boundary required
label	string	—	Display label for search and lists
search_terms	array	—	Alternative keywords for trigger search

Word Boundary Detection

With word: true, the trigger only matches at word boundaries — use this for autocorrection-style triggers that should not match inside other words:

- trigger: "ther"
  replace: "there"
  word: true

How It Works

Before	After
Is ther anyone else?	Is there anyone else?
I have other interests	I have other interests (no match — "ther" is inside "other")

The match occurs when the trigger is surrounded by word separators (spaces, commas, newlines, start/end of text).

Partial Word Boundaries

For more control, use left_word: true to only match at the start of a word, or right_word: true to only match at the end:

- trigger: "ing"
  replace: "ing_"
  right_word: true

Custom Word Separators

The word_separators global config option lets you define which characters act as word boundaries (default: whitespace and punctuation).

Prefix Convention

Triggers typically start with a special character to avoid accidental expansion:

- trigger: ":hello"    # colon prefix (recommended)
- trigger: "git!rel"   # exclamation separator
- trigger: ";div"      # semicolon prefix for code

tip

Using a consistent prefix like : prevents triggers from matching inside normal words. This is simpler than word: true for most use cases.

Cursor Hints

Place $|$ in your replace text to control where the cursor lands after expansion:

- trigger: ":div"
  replace: "<div>$|$</div>"

Expands to <div></div> with the cursor between the tags. Learn more →

Disambiguation

When multiple matches share the same trigger, cli-expander shows a selection dialog to choose. Learn more →

Case Propagation

Match the casing of your typed trigger automatically. Learn more →

Search Labels

Add label and search_terms to make triggers easier to find. Learn more →

What's Next

Learn about Match Files and Configuration for organizing your triggers.