Skip to main content

Quickstart

A 5-minute guide to using cli-expander.

Step 1: Create Match Files​

Create a directory for your match files and add some triggers.

mkdir -p ~/.config/cli-expander/matches
cat > ~/.config/cli-expander/matches/base.yml << 'ENDCONF'
matches:
  - trigger: ":hello"
    replace: "Hello World!"
  - trigger: ":thanks"
    replace: "Thank you!"
ENDCONF

Step 2: Test Expansion​

ce :hello
# Output: Hello World!

ce :thanks
# Output: Thank you!

Step 3: Add a Date Variable​

cat >> ~/.config/cli-expander/matches/base.yml << 'ENDCONF'
  - trigger: ":today"
    replace: "Today's date: {{today}}"
    vars:
      - name: today
        type: date
        params:
          format: "%B %d, %Y"
ENDCONF

ce :today
# Output: Today's date: June 14, 2026

Step 4: Try a Form​

Forms prompt you for input before expanding.

cat >> ~/.config/cli-expander/matches/base.yml << 'ENDCONF'
  - trigger: ":greet"
    form: |
      Hello [[name]]!
    form_fields:
      name:
        placeholder: "Your name"
ENDCONF

When you expand this trigger, a form dialog opens in your terminal. Fill in the fields and submit.

┌───────── cli-expander ─────────┐
│  Name: [__John_________]       │
│                                │
│  [Submit]  [Cancel]           │
└────────────────────────────────┘
ce :greet
# Opens interactive form
tip

Forms require a real terminal session. They won't work in piped contexts or headless environments.

Step 5: Use a Cursor Hint​

Position the cursor automatically after expansion:

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

The $|$ marker tells cli-expander where to place your cursor.

Step 6: List Available Triggers​

ce list
# Output:
# Trigger    Replace/Form    Type
# :hello     Hello World!    text
# :thanks    Thank you!      text
# :today     {{today}}       text
# :greet                     form

Step 7: Add Shell Integration (Optional)​

echo 'source /path/to/shell/cli-expander.bash' >> ~/.bashrc
# Restart your shell, then type :hello and press Space

What's Next​