In r-lib/cli: Helpers for Developing Command Line Interfaces

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README",
  out.width = "100%",
  cache = TRUE,
  asciicast_theme = if (Sys.getenv("IN_PKGDOWN") == "true") "pkgdown" else "readme"
)
Sys.setenv(CLI_TICK_TIME = "100")
asciicast::init_knitr_engine(
  startup = quote({
    library(cli)
    set.seed(1) }),
  echo = TRUE,
  echo_input = FALSE
)

Helpers for Developing Command Line Interfaces

A suite of tools to build attractive command line interfaces (CLIs), from semantic elements: headers, lists, alerts, paragraphs, etc. Supports theming via a CSS-like language. It also contains a number of lower level CLI elements: rules, boxes, trees, and Unicode symbols with ASCII alternatives. It supports ANSI markup for terminal colors and font styles.

---

Features

• Build a CLI using semantic elements: headings, lists, alerts, paragraphs.
• Theming via a CSS-like language.
• Terminal colors and font styles.
• All cli text can contain interpreted string literals, via the glue package.
• Progress bars from R and C code.
• Error and warning messages with rich text formatting.
• Support for pluralized messages.
• ANSI styled string manipulation.

Installation

Install the stable version from CRAN:

install.packages("cli")

Install the development version from GitHub:

pak::pak("r-lib/cli")

Short tour

Some of the more commonly used cli elements, and features.

Short alert messages

One liner messages to inform or warn.

```{asciicast alert-success} pkgs <- c("foo", "bar", "foobar") cli_alert_success("Downloaded {length(pkgs)} packages.")

```{asciicast alert-info}
db_url <- "example.com:port"
cli_alert_info("Reopened database {.url {db_url}}.")

```{asciicast alert-warning} cli_alert_warning("Cannot reach GitHub, using local database cache.")

```{asciicast alert-danger}
cli_alert_danger("Failed to connect to database.")

```{asciicast alert} cli_alert("A generic alert")

## Headings

Three levels of headings.

```{asciicast h1}
cli_h1("Heading 1")

```{asciicast h2} cli_h2("Heading 2")

```{asciicast h3}
cli_h3("Heading 3")

Lists

Ordered, unordered and description lists, that can be nested.

```{asciicast lists} fun <- function() { cli_ol() cli_li("Item 1") ulid <- cli_ul() cli_li("Subitem 1") cli_li("Subitem 2") cli_end(ulid) cli_li("Item 2") cli_end() } fun()

## Themes

Theming via a CSS-like language.

```{asciicast themes}
fun <- function() {
  cli_div(theme = list(span.emph = list(color = "orange")))
  cli_text("This is very {.emph important}")
  cli_end()
  cli_text("Back to the {.emph previous theme}")
}
fun()

Command substitution

Automatic command substitution via the glue package.

```{asciicast glue} size <- 123143123 dt <- 1.3454 cli_alert_info(c( "Downloaded {prettyunits::pretty_bytes(size)} in ", "{prettyunits::pretty_sec(dt)}"))

## Pluralization

Pluralization support.

```{asciicast plurals}
nfiles <- 3
ndirs <- 1
cli_alert_info("Found {nfiles} file{?s} and {ndirs} director{?y/ies}.")

Progress bars

```{asciicast progress-setup, include = FALSE, cache = FALSE} options(cli.progress_show_after = 0) options(cli.progress_clear = FALSE)

```{asciicast progress}
#| asciicast_knitr_output = "svg",
#| asciicast_at = "all",
#| asciicast_cursor = FALSE
clean <- function() {
  cli_progress_bar("Cleaning data", total = 100)
  for (i in 1:100) {
    Sys.sleep(5/100)
    cli_progress_update()
  }
}
clean()

Documentation

See at https://cli.r-lib.org/ and also in the installed package: help(package = "cli").

Code of Conduct

Please note that the cli project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

License

MIT © Posit Software, PBC

r-lib/cli documentation built on April 4, 2024, 11:48 a.m.