Form Syntax

Forms are the signature feature of cli-expander. They collect user input before expansion — all rendered in your terminal via Cursive TUI.

How Forms Work

When a match has a form field instead of replace, cli-expander opens an interactive form dialog when the trigger is matched. The user fills in the fields and submits with Tab+Enter. The field values are then substituted into the form layout.

Shorthand Syntax

The simplest way to create a form uses inline [[field]] placeholders in the form field:

- trigger: ":greet"
  form: |
    Hello [[name]]!
    You are [[age]] years old.
  form_fields:
    name:
      placeholder: "Your name"
    age:
      placeholder: "Your age"

When expanded, the form shows:

┌─────────────────────────────┐
│  texpand                    │
├─────────────────────────────┤
│  Hello [[name]]!            │
│  You are [[age]] years old. │
│                             │
│  Your name: [____________]  │
│  Your age:  [____________]  │
│                             │
│  [Submit]        [Cancel]   │
└─────────────────────────────┘

Verbose Syntax

The verbose syntax uses vars to define the form as a variable. This enables variable chaining and shell integration.

- trigger: ":greet"
  replace: "Hello {{form.name}}! You are {{form.age}}."
  vars:
    - name: form
      type: form
      params:
        layout: |
          Name: [[name]]
          Age: [[age]]
        fields:
          name:
            placeholder: "Enter name"
          age:
            type: choice
            values:
              - 18-25
              - 26-35
              - 36+

Field Configuration

Each field in form_fields can be configured with these options:

Option	Type	Applies to	Description
type	string	all	text (default), choice, list, checkbox, password
multiline	bool	text	Enable multi-line input
default	string	all	Pre-filled value
placeholder	string	text, password	Hint text when field is empty
values	array/map	choice, list	Available options (or depends map for cascades)
depends_on	string	choice	Parent field name for cascading dropdowns

Form Controls

Key	Action
Tab	Move to next field
Shift+Tab	Move to previous field
Enter	Submit form (when Submit button focused)
Esc	Cancel form
Arrow keys	Navigate choice/list options

What's Next

Learn about the different Form Field Types you can use.