---
name: "iselect"
section: "1"
platform: "linux"
package: "iselect"
version: "1.4.2-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/iselect"
---

# iselect(1)

Interactive Selection Tool

## NAME

**iSelect** – Interactive Selection Tool

## SYNOPSIS

**iselect** \[**-d** *beg***,***end*\] \[**-cfae**\] \[**-p** *linenum*\] \[**-k** *key*\[**:***okey*\]\] \[**-m**\] \[**-n** *name*\] \[**-t** *title*\] \[**-SKP**\] \[**-Q** *fallback*\] *line*…

**iselect** \[**-d** *beg***,***end*\] \[**-cfae**\] \[**-p** *linenum*\] \[**-k** *key*\[**:***okey*\]\] \[**-m**\] \[**-n** *name*\] \[**-t** *title*\] \[**-SKP**\] \[**-Q** *fallback*\] \< *lines*

**iselect** **-V**\|**-h**

## DESCRIPTION

### Intent

**iSelect** is an interactive line selection tool, operating via a full-screen Curses-based terminal session. It can be used either as a user interface frontend controlled by the shell, Perl, or another type of script backend as its wrapper, or in batch as a pipe filter (usually between **grep** and the final executing command). In other words: **iSelect** was designed to be used for any type of interactive line-based selection.

### Input Data

If no arguments are given, lines are read from the standard input stream. Otherwise, *line*s are used directly.

Each selectable line is fully bold; parts of other lines may be set in bold by wrapping them in ‘\<b\>...\</b\>’.

### Selections

By default, a single line may be chosen; with **-m** multiple lines can be selected. By default, only lines containing the tag ‘\<s\>’ (or with different delimiters set with **-d**) may be selected. **-a** allows selecting all lines, but the tag is always removed. Selected lines are written to the standard output stream

The tag has a variant that looks like ‘\<s:result text\>’, which, instead of writing the line itself, writes *result text*. Every format specifier in the form ‘%\[prompt string\]s’ or ‘%\[prompt string\]S’ in the output is replaced by a line entered in an interactive prompt. The **s** variant allows empty responses; **S** doesn't.

## OPTIONS

### Input Options

- **-d** *beg***,***end*, **--delimiter**=*beg***,***end*

  Sets the delimiters for the selection tags. The default is **\<** and **\>** — the selection tags have to read ‘\<s\>’ and ‘\<s:result text\>’.

- **-c**, **--strip-comments**

  Discard input lines starting with ‘#’.

- **-f**, **--force-browse**

  Open the full-screen browser even if input contains less than \<*2* lines. This may happen anyway if a ‘%\[prompt\]s’ needs to be substituted.

- **-a**, **--all-select**

  Force all lines to be selectable. ‘\<s\>’ tags are still removed.

- **-e**, **--exit-no-select**

  Exit immediately if no lines are selectable.

### Display Options

- **-p**, **--position**=*linenum*

  Sets the cursor position to **1**-based *linenum*ber.

- **-k**, **--key**=*key***:***okey*

  Maps *key* to *okey*. Both may be either a printable character or one of **SPACE**, **RETURN**, **KEY\_UP** (↑), **KEY\_DOWN** (↓), **KEY\_LEFT** (←), **KEY\_RIGHT** (→), **KEY\_PPAGE** (PgUp), **KEY\_NPAGE** (PgDn). This can be given any number of times, and is applied in order.

- **-k**, **--key**=*key*

  Same as **-k** *key***:**RETURN. For example, **-k** *f* allows using ‘f’ to confirm the selection.

- **-m**, **--multi-line**

  Allow selecting more than one line with Space.

- **-n**, **--name**=*name*

  Changes the string displayed flush left at the bottom of the browser window from "iSelect".

- **-t**, **--title**=*title*

  Sets the *file ...*, displayed centered at the bottom of the browser window.

### Output Options

- **-S**, **--strip-result**

  Strip all leading and trailing whitespace from the result string.

- **-K**, **--key-result**

  Prefix each result with the key used to confirm the selection. This is usually "**RETURN**" or "**KEY\_RIGHT**", but in the presence of **-k**, this is the (unmapped) *key*; thus, with **-k** *f*, selecting line Foo Bar by pressing ‘f’ yields ‘f:Foo Bar’. A Space is rendered as a literal space, not as "**SPACE**".

- **-P**, **--position-result**

  Prefix each result with its **1**-based line number in the buffer.

- **-Q**, **--quit-result**=*fallback*

  Write *fallback* to the standard output stream when quitting.

### Giving Feedback

- **-V**, **--version**

  Write the version and licence information to the standard output stream, exit **0**.

- **-h**, **--help**

  Write the usage string information to the standard error stream, exit **0**.

## KEYSTROKES

### Cursor Movement

Use these to browse through the selection list:

```
  CURSOR-UP ..... Move cursor one line up
  CURSOR-DOWN ... Move cursor one line down
  PAGE-UP ....... Move cursor one page up
  PAGE-DOWN ..... Move cursor one page down
  g ............. Goto first line
  G ............. Goto last line
```

### Line Selection

Use these to select one line and exit in standard mode, or one or more lines in multi-line mode:

```
  RETURN ........ Select line and exit
  CURSOR-RIGHT .. Select line and exit
  SPACE ......... Select line and stay (multi-line mode only)
  C ............. Clear current marks  (multi-line mode only)
```

### Others

Use these to quit **iSelect** or to show the help or version pages:

```
  q ............. Quit (exit without selection)
  CURSOR-LEFT ... Quit (exit without selection)
  h ............. Help Page
  v ............. Version Page
```

## FILES

The Curses session is always opened on */dev/tty*, because the standard I/O streams are usually tied to pipes.

## EXIT STATUS

- **0**

  if a selection was made, a selection wasn't made, or succumbed to SIGINT or SIGTERM.

- **1**

  if an unknown \[*o*\]*key* was given or an I/O error occurred.

## EXAMPLES

As an example we present a real-life situation where **iSelect** can enhance existing functionality. We define two shell functions (for your *$HOME/.bashrc* file) which enhance the shell's **cd** built-in.

```
#   database scan
cds () {
    find "$HOME" -type d | sort > ~/.dirs &
}
#   enhanced cd command
cd () {
    if [ -d "$1" ]; then
        builtin cd "$1"
    else
        builtin cd "$(grep -E "/$1[^/]*$" ~/.dirs   |
                      iselect -a -Q "$1" -n "chdir" \
                      -t "Change Directory to...")"
    fi
}
```

This **cd**() is compatible with the built-in in the case where the specified directory actually exists. When it doesn't, the original **cd** would immediately give an error (assuming CDPATH is not set). This version tries harder by searching for such a directory in a previously-built (via **cds**()) ($HOME/.dirs) file. When no match is found, **iSelect** just returns the given directory as the default result and **cd** fails as usual. When only one directory was found, **iSelect** gives it to **cd** silently. Only when more then one directory was found, **iSelect** shows a menu to pick between matches interactively. The chosen directory is then given to **cd**.

For more useful examples on how to use **iSelect**, see */usr/share/doc/iselect/examples*.

## AUTHORS

Ralf S. Engelschall ⟨rse@engelschall.com⟩ (**http://www.engelschall.com**)

## SEE ALSO

*New* *iSelect* *Home:* **https://sr.ht/~nabijaczleweli/ossp**