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:

┌─────────────────────────────┐
│  cli-expander               │
├─────────────────────────────┤
│  Tab next | / search ...    │
│  ─────────────────────────  │
│  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
/	Open search dialog (when choice/list field focused)

Form Help Bar

Every form shows a help bar at the top:

Tab next | / search dropdown | Enter select | Esc cancel

This reminds you of the available controls while filling out the form.

Hierarchical Sections

Forms can be organized into sections by adding non-field lines in the layout text. Any line that does not contain a [[field]] placeholder is treated as a section heading.

params:
  layout: |
    Find Smart

    Scope
      - Path: [[path]]

    Search Criteria
      - Use case: [[usecase]]
      - Preset: [[preset]]
      - Extra predicate: [[extra]]

    Output Action
      - Action: [[action]]

The form renders with blank separators between sections:

Find Smart
────────────────────────────────────
Tab next | / search dropdown | Enter select | Esc cancel
-----------------------------------------------

Scope
  - Path:
     [value widget]

Search Criteria
  - Use case:
     [value widget]
  - Preset:
     [value widget]
  - Extra predicate:
     [value widget]

Output Action
  - Action:
     [value widget]

Each field label is cleaned of leading/trailing box-art characters and formatted with a - Label: prefix. Field value widgets are indented underneath their labels with 3 spaces.

Searchable Dropdowns

Choice and list fields can be filtered by pressing / when focused. This opens a dialog with a live search input:

Search: Preset
─────────────────
Query: log

3 matches
  - -type f -name '*.log'
  - -type f -name '*.log.*'
  - -type f -path '*/logs/*'

Enter select | Esc close

The search is case-insensitive and matches by substring. When the query field is blank, all options are shown. If no options match, "No matches" is displayed. Selecting a result or pressing Esc returns to the form with the selection applied or unchanged.

What's Next

Learn about the different Form Field Types you can use.