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	Ghost text shown when field has no default — disappears when you type
default	Pre-filled editable value

Ghost text placeholder: When a field has only placeholder (no default), the hint text appears as ghost text that disappears automatically when you start typing. No need to delete it first — just type and your input replaces the placeholder. This is especially useful for command builder forms where placeholder text is long (e.g., e.g. ./file.txt, /var/log/app.log).

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.

Searchable Dropdowns

Choice and list fields support live filtering by pressing / while the field is focused. This is especially useful for dropdowns with 50+ options.

- trigger: ":bigdropdown"
  replace: "Selected package: {{package}}"
  vars:
    - name: form
      type: form
      params:
        layout: |
          Package: [[package]]
        fields:
          package:
            type: choice
            values:
              - nginx
              - postgresql
              - redis-server
              # ... 47 more options (see examples/forms-advanced.yml)

When the dropdown is focused, press / to open a search dialog:

Search: Package
─────────────────
Query: post

2 matches
  - postgresql
  - postman (if present)

Enter select | Esc close

Key search controls:

Key	Action
/	Open search dialog (when dropdown focused)
Type	Filter results by case-insensitive substring
Enter	Select highlighted result
Esc	Close search without changing selection

Search respects cascade dependencies: if the field is a cascade child, only the currently valid options are searched — not every possible item in the config.

Hierarchical Form Layouts

Forms can use section headings and indented field blocks for better readability. Non-field lines in the layout text are parsed as section titles.

- trigger: ":find-smart"
  replace: "find {{path}} {{preset}} {{extra}} {{action}}"
  vars:
    - name: form
      type: form
      params:
        layout: |
          Find Smart

          Scope
            - Path: [[path]]

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

          Output Action
            - Action: [[action]]

The form renders as:

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]

[Submit] [Cancel]

This layout works with any field type: text, choice, list, multiline, checkbox, or password. Sections are automatically detected from any line in the layout that does not contain a [[field]] placeholder.

Field Comparison

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

What's Next

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