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

--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