Package {climenu}

Title: Interactive Command-Line Menus
Version: 0.2.0
Author: Petr Čala [aut, cre]
Maintainer: Petr Čala <61505008@fsv.cuni.cz>
Description: Provides interactive command-line menu functionality with single and multiple selection menus, keyboard navigation (arrow keys or vi-style j/k), preselection, and graceful fallback for non-interactive environments. Inspired by tools such as 'inquirer.js' https://github.com/SBoudrias/Inquirer.js, 'pick' https://github.com/aisk/pick, and 'survey' https://github.com/AlecAivazis/survey. Designed to be lightweight and easy to integrate into 'R' packages and scripts.
License: MIT + file LICENSE
URL: https://github.com/PetrCala/climenu
BugReports: https://github.com/PetrCala/climenu/issues
Depends: R (≥ 4.0.0)
Imports: cli (≥ 3.6.0), keypress (≥ 1.0.0)
Suggests: covr, devtools, knitr, rmarkdown, roxygen2 (≥ 7.0.0), testthat (≥ 3.0.0)
VignetteBuilder: knitr
Config/testthat/edition: 3
Config/testthat/parallel: TRUE
Encoding: UTF-8
Config/roxygen2/version: 8.1.0
NeedsCompilation: no
Packaged: 2026-08-31 09:09:42 UTC; runner
Repository: CRAN
Date/Publication: 2026-08-31 17:00:28 UTC

Multiple Selection Menu (Checkbox)

Description

Interactive menu for selecting multiple items from a list. Uses arrow keys (or j/k) to navigate, Space to toggle, and Enter to confirm. Optionally includes a "Select all" / "Deselect all" option at the top when allow_select_all = TRUE.

Usage

checkbox(
  choices,
  prompt = "Select items (Space to toggle, Enter to confirm):",
  selected = NULL,
  return_index = FALSE,
  max_visible = 10L,
  allow_select_all = FALSE,
  descriptions = NULL,
  echo = TRUE
)

Arguments

choices

Character vector of choices to display. When the vector is named, the names are the labels shown in the menu and the (unnamed) values are what gets returned, separating display text from stable return values. Unnamed vectors are displayed and returned as-is.

prompt

Prompt message to display

selected

Pre-selected items (indices or values). Character values match the returned values first, then the displayed labels.

return_index

Return indices instead of values (default: FALSE)

max_visible

Maximum number of items to display at once (default: 10). Set to NULL to show all items.

allow_select_all

If TRUE, adds a "Select all" / "Deselect all" option at the top of the menu. When selected, toggles all items at once. The option text dynamically changes based on selection state (default: FALSE).

descriptions

Optional character vector with one entry per choice, rendered dim after each label as an aligned second column. Display-only: descriptions are never echoed or returned, and an empty string renders nothing for that item (default: NULL).

echo

Print the confirmation summary after a completed selection (default: TRUE). Cancellation notices print regardless.

Value

Selected items as character vector or indices, or NULL if cancelled. For named choices the unnamed values are returned, not the displayed labels. The special "Select all" option is never included in the returned results.

Examples

if (interactive()) {
  toppings <- checkbox(
    c("Pepperoni", "Mushrooms", "Olives"),
    prompt = "Select toppings:"
  )

  # With pre-selection
  options <- checkbox(
    c("Option A", "Option B", "Option C"),
    selected = c(1, 3)
  )

  # Labels differ from the returned values
  methods <- checkbox(c("Linear tests" = "linear_tests", "BMA" = "bma"))

  # With scrolling for long lists
  items <- checkbox(as.character(1:100), max_visible = 10)

  # With select all feature
  methods <- checkbox(
    c("method_a", "method_b", "method_c"),
    allow_select_all = TRUE,
    prompt = "Select methods to run:"
  )
}

Description

Creates an interactive menu in the R console allowing users to select items. Inspired by inquirer.js, Python's pick, and Go's survey libraries.

Usage

menu(
  choices,
  prompt = "Select an item:",
  type = c("select", "checkbox"),
  selected = NULL,
  return_index = FALSE,
  max_visible = 10L,
  allow_select_all = FALSE,
  descriptions = NULL,
  echo = TRUE
)

Arguments

choices

Character vector of choices to display. When the vector is named, the names are the labels shown in the menu and the (unnamed) values are what gets returned, separating display text from stable return values. Unnamed vectors are displayed and returned as-is.

prompt

Prompt message to display (default: "Select an item:")

type

Menu type: "select" (single) or "checkbox" (multiple) (default: "select")

selected

Pre-selected items (indices or values). Character values match the returned values first, then the displayed labels.

return_index

Return indices instead of values (default: FALSE)

max_visible

Maximum number of items to display at once (default: 10). Set to NULL to show all items.

allow_select_all

If TRUE, adds a "Select all" / "Deselect all" option at the top of the menu. Only used when type = "checkbox" (default: FALSE).

descriptions

Optional character vector with one entry per choice, rendered dim after each label as an aligned second column. Display-only: descriptions are never echoed or returned, and an empty string renders nothing for that item (default: NULL).

echo

Print the confirmation line after a completed selection (default: TRUE). Cancellation notices print regardless.

Value

Selected item(s) as character vector or indices, or NULL if cancelled. For named choices the unnamed values are returned, not the displayed labels.

Examples

if (interactive()) {
  # Single selection
  color <- menu(c("Red", "Green", "Blue"), prompt = "Pick a color:")

  # Multiple selection
  toppings <- menu(
    c("Pepperoni", "Mushrooms", "Olives"),
    type = "checkbox",
    prompt = "Select toppings:"
  )
}

Single Selection Menu

Description

Interactive menu for selecting a single item from a list. Uses arrow keys (or j/k) to navigate and Enter to select.

Usage

select(
  choices,
  prompt = "Select an item:",
  selected = NULL,
  return_index = FALSE,
  max_visible = 10L,
  descriptions = NULL,
  echo = TRUE
)

Arguments

choices

Character vector of choices to display. When the vector is named, the names are the labels shown in the menu and the (unnamed) values are what gets returned, separating display text from stable return values. Unnamed vectors are displayed and returned as-is.

prompt

Prompt message to display

selected

Pre-selected item (index or value). A character value matches the returned values first, then the displayed labels.

return_index

Return index instead of value (default: FALSE)

max_visible

Maximum number of items to display at once (default: 10). Set to NULL to show all items.

descriptions

Optional character vector with one entry per choice, rendered dim after each label as an aligned second column. Display-only: descriptions are never echoed or returned, and an empty string renders nothing for that item (default: NULL).

echo

Print the confirmation line after a completed selection (default: TRUE). Cancellation notices print regardless.

Value

Selected value as character or index, or NULL if cancelled. For named choices the unnamed value is returned, not the displayed label.

Examples

if (interactive()) {
  choice <- select(c("Yes", "No", "Maybe"))
  index <- select(c("First", "Second", "Third"), return_index = TRUE)

  # Labels differ from the returned values
  action <- select(c("Run methods" = "run", "Quit" = "quit"))

  # With dim descriptions
  screen <- select(
    c("Studies", "Columns"),
    descriptions = c("per-study estimate counts", "role and type per column")
  )

  # With scrolling for long lists
  choice <- select(as.character(1:100), max_visible = 10)
}