Form Field Types

cli-expander supports seven form field types, all rendered using native Cursive widgets in your terminal.

Text Field (Default)

The simplest input type. A single-line text box.

- trigger: ":name"
  form: "Enter name: [[name]]"
  form_fields:
    name:
      placeholder: "Your full name"
      default: "John Doe"

Option	Description
placeholder	Hint text shown when empty
default	Pre-filled value

Multiline Text Area

For longer input like notes, descriptions, or code.

- trigger: ":note"
  form: |
    Notes:
    [[notes]]
  form_fields:
    notes:
      multiline: true
      default: "Enter your notes here..."

Option	Description
multiline: true	Enables multi-line editing
default	Pre-filled content

Choice Dropdown

A single-select dropdown list. The user picks one option.

- trigger: ":priority"
  form: "Priority: [[level]]"
  form_fields:
    level:
      type: choice
      values:
        - Low
        - Medium
        - High
        - Critical

When focused, the dropdown opens and the user navigates with arrow keys.

List Selector

A scrollable list with a single selection. Visually distinct from choice — items display with a - prefix in the TUI.

- trigger: ":file"
  form: "Select file: [[file]]"
  form_fields:
    file:
      type: list
      values:
        - document.txt
        - notes.md
        - script.sh
        - config.yml

Checkbox

A boolean toggle. Returns true or false.

- trigger: ":confirm"
  form: "Are you sure? [[ok]]"
  form_fields:
    ok:
      type: checkbox
      default: "true"

Option	Description
default	"true", "yes", "1", or "on" to pre-check

Password

A hidden/masked single-line input field.

- trigger: ":secret"
  form: "Token: [[token]]"
  form_fields:
    token:
      type: password
      placeholder: "enter secret"

Cascading Choice

A child dropdown whose options change dynamically based on the parent selection.

- trigger: ":cascade"
  replace: "Selected {{cat}}: {{item}}"
  vars:
    - name: form
      type: form
      params:
        layout: |
          Category: [[cat]]
          Item: [[item]]
        fields:
          cat:
            type: choice
            values:
              - Fruits
              - Animals
              - Colors
          item:
            type: choice
            depends_on: cat
            values:
              Fruits: [Apple, Banana, Cherry, Durian]
              Animals: [Cat, Dog, Elephant, Fox]
              Colors: [Red, Green, Blue, Yellow]

When the user changes the parent (cat), the child (item) options update immediately.

Field Comparison

Feature	Text	Multiline	Choice	List	Checkbox	Password	Cascade
Single line input	✓	—	—	—	—	✓	—
Multi-line input	—	✓	—	—	—	—	—
Dropdown selection	—	—	✓	✓	—	—	✓
Boolean toggle	—	—	—	—	✓	—	—
Hidden input	—	—	—	—	—	✓	—
Dynamic options	—	—	—	—	—	—	✓
Default value	✓	✓	✓	✓	✓	—	—
Placeholder	✓	✓	—	—	—	✓	—

What's Next

Now learn about the Variable System for dynamic content in your expansions.