Config Reference

Match File Schema

matches:
  - trigger: ":hello"             # Single trigger keyword
    triggers: [":hi", ":hey"]     # Multiple triggers (alternative)
    replace: "Hello World!"       # Static replacement text
    form: "Hello [[name]]!"       # Form layout with [[field]] placeholders
    form_fields:                   # Field configuration (for forms)
      field_name:
        type: choice               # Field type: text, choice, list, checkbox, password
        multiline: true            # Enable multi-line (text only)
        default: "Default value"   # Pre-filled value
        placeholder: "Hint text"   # Placeholder when empty
        values:                    # Options for choice/list
          - Option A
          - Option B
        depends_on: other_field    # Cascade dependency
    vars:                          # Variable definitions
      - name: var_name
        type: date                 # Variable type: date, clipboard, shell, form, match
        params:                    # Type-specific parameters
          format: "%Y-%m-%d"
          offset: 86400           # Seconds offset for date
    global_vars:                   # Shared across all matches in file
      - name: shared_var
        type: shell
        params:
          cmd: "whoami"
    force_mode: clipboard          # Injection mode override: auto, clipboard, keys
    propagate_case: true           # Match case of typed trigger
    uppercase_style: capitalize_words  # Multi-word capitalization
    word: true                     # Word boundary required
    label: "Human-readable name"   # Display label for search
    search_terms:                  # Alternative search keywords
      - keyword1
      - keyword2

Variable Type Reference

Type	Parameters	Description
date	format (strftime), offset (seconds), locale, tz	Current date/time
clipboard	—	System clipboard content
shell	cmd (command), trim (bool), debug (bool), shell (string)	Command stdout
form	layout, fields	Interactive form input
match	trigger	Nested match expansion

Match Options Reference

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: 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 search

Form Field Types

Type	Multiline	Default	Placeholder	Values	Depends On	Description
text	✓	✓	✓	—	—	Single-line text input
choice	—	✓	—	✓	✓	Single-select dropdown
list	—	✓	—	✓	✓	Scrollable list selection
checkbox	—	✓	—	—	—	Boolean toggle
password	—	✓	✓	—	—	Masked text input

Global Config Options

File: ~/.config/cli-expander/config.yml

Option	Type	Default	Description
search_trigger	string	:	Search trigger character
backend	string	auto	Injection backend: auto, clipboard, keys
max_form_width	int	80	Maximum form width in characters
max_form_height	int	40	Maximum form height in characters

Exit Codes

Code	Meaning
0	Success
1	General error (no match, invalid config, etc.)