cli-expander
A terminal-native text expander designed to help CLI usage. Written in Rust.
Type a short trigger like :hello and it expands to a full sentence. Need user input? Forms render directly in your terminal — no GUI popups.
┌────────────────────────────────────────────────┐
│ $ :hello[Space] │
│ $ Hello World! │
│ │
│ $ :greet[Space] │
│ ┌─────── Form: cli-expander ────────┐ │
│ │ Name: [__John_____________] │ │
│ │ │ │
│ │ [Submit] [Cancel] │ │
│ └──────────────────────────────────┘ │
│ $ Hello John! │
└────────────────────────────────────────────────┘
Learning Focus
By the end of this documentation, you will understand:
- How to create and manage text expansion triggers
- How to build interactive forms that render in your terminal
- How to use variables for dynamic content (date, clipboard, shell commands)
- How to integrate with your shell for in-prompt expansion
- How to configure system-wide keyboard detection
- How to share and organize match files effectively
Features
- Trigger expansion —
:hello→Hello World! - Cursor positioning —
$|$marker places cursor exactly where you want after expansion - Prompt-first workflow — Type
:trigger[Space], fill a TUI form, then edit or run the generated command from the shell prompt - Interactive forms — Text, password, checkbox, multiline, choice dropdowns, list selectors, cascade fields, and hierarchical section layouts — all in-terminal via Cursive TUI
- Searchable dropdowns — Press
/inside choice/list fields to filter large option sets by substring - Variable system — Date, clipboard, shell command output, and form field injection
- Variable chaining — Pass one variable's output as input to another for complex workflows
- Nested matches — Include the output of one match inside another
- Case propagation — Match the casing of your typed trigger automatically
- Word boundary detection — Only match triggers at word boundaries (autocorrection mode)
- Shell plugins — Expansion hooks for Zsh, Bash, and Fish
- FZF trigger search — Fuzzy-find triggers with preview panel (Bash)
- Tmux integration — Inject expansions into tmux panes, popup picker
- System-wide mode — evdev keyboard detection + uinput injection for any application
- Privacy-first — 100% local, no data leaves your machine
┌──────────── cli-expander – Find Command Builder ────────────┐
│ ── Scope ────────────────────────────────────────────────── │
│ - Path: [/home/user/projects___________________________] │
│ ── Search Criteria ──────────────────────────────────────── │
│ - Type: [▼ by-name ] │
│ - Name: [________________________] │
│ ── Output Action ────────────────────────────────────────── │
│ - Action: [▼ print ] │
│ │
│ Tab next │ / search │ Enter select │ Esc cancel │
└────────────────────────────────────────────────────────────┘
Quick Start
# Build from source
git clone https://github.com/donnyaw/cli-expander.git
cd cli-expander
cargo build --release
cp target/release/ce ~/.local/bin/
# Create your first match file
mkdir -p ~/.config/cli-expander/matches
cat > ~/.config/cli-expander/matches/base.yml << 'EOF'
matches:
- trigger: ":hello"
replace: "Hello World!"
EOF
# Try it
ce :hello
# Output: Hello World!
Documentation Structure
| Section | Description |
|---|---|
| 1. Introduction | What it is, installation, quickstart |
| 2. Core Concepts | Triggers, matches, word boundaries, cursor hints, case propagation, disambiguation |
| 3. Forms | Interactive form field types and controls |
| 4. Variables | Date, clipboard, shell, global variables, nested matches |
| 5. Shell Integration | Zsh, Bash, Fish plugin setup |
| 6. Advanced | Variable chaining, system-wide mode |
| 7. Examples | Common workflow examples |
| 8. Troubleshooting | Common issues, debugging, FAQ |
| 9. Reference | CLI commands, config reference, tmux |
| 10. Community | Contributing, changelog, resources |
| 11. Security | Privacy, shell safety, permissions |