Selector Options

Selector Options

Selector options control how the picker displays shell output and what value is returned when the user makes a selection. They are appended after --- on any variable definition line.

Syntax

var name = <shell> --- <options>
var name --- <options>
var name := <value> --- <options>

The --- separator is required. Options are space-separated; quote values that contain spaces.

Available options

Option	Effect
--header "..."	Header text shown above the picker
--delimiter "X"	Split each output line by X into columns
--column N	Show column N (1-indexed) in the picker (display only)
--select-column N	Return column N (1-indexed) as the value
--map "cmd"	Pipe the selected value through cmd via stdin
--multi	Enable multi-select using Space to toggle checkboxes

--header

Shows a label above the selection list or input prompt:

var host --- --header "Enter the target hostname"
var container = docker ps --format "{{.Names}}" --- --header "Select container"

Works on all three variable forms (prompt-only, shell, literal).

--delimiter and --column

Split each line into columns for display. --column controls what the user sees in the picker; it never affects the return value.

var service = systemctl list-units --type=service --no-legend \
    --- --delimiter " " --column 1 --header "Service"

--select-column

Controls what value is returned when the user picks a row. Without this, the full original line is returned.

var auth = printf 'key\tUse SSH key\npassword\tUse password\n' \
    --- --delimiter '\t' --column 2 --select-column 1 --header "Auth method"

The user sees the description (column 2: "Use SSH key") but the variable gets the key (column 1: "key").

Order of operations

When the user selects a line:

1. --select-column extracts the column from the original line
2. --map transforms the extracted value

--column is display-only and never participates in the return pipeline.

--map

Pipes the selected value through a shell command via stdin. Use this when a column extract isn't enough - for transformations like lower-casing, regex extraction, or JSON field access.

var bucket = aws s3 ls --- --map "awk '{print \$3}'" --header "Bucket"
var lower  = printf 'A\nB\nC' --- --map "tr '[:upper:]' '[:lower:]'"

aws s3 ls outputs 2024-01-15 12:00:00 my-bucket per line. --map extracts just the bucket name.

--multi

Enables selecting multiple options from a single variable prompt. This allows users to build up a list of values.

var ports = echo -e "80\n443\n8080" --- --multi --delimiter ,

When --multi is provided:

1. The picker list renders interactive [x] and [ ] checkboxes.
2. The user can press Space to toggle an option.
3. The user can press Enter to confirm their selections.

If multiple options are selected, they are mapped (if --map is used) and joined together using the --delimiter character. If --delimiter is empty, they will be joined with a comma (,) by default.

Combining options

A complete example showing all options together:

var target = kubectl get pods -o wide --no-headers \
    --- --delimiter " " \
        --column 1 \
        --select-column 6 \
        --map "cut -d: -f1" \
        --header "Select pod (showing name, returning IP)"

See also

• Variables - the three var forms
• Recipes - copy-pasteable patterns using these options