README.Rmd

---
title: cli
output:
  github_document:
always_allow_html: yes
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE, cache = FALSE}
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

<!-- badges: start -->
[![R-CMD-check](https://github.com/r-lib/cli/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/r-lib/cli/actions/workflows/R-CMD-check.yaml)
[![](https://www.r-pkg.org/badges/version/cli)](https://www.r-pkg.org/pkg/cli)
[![CRAN RStudio mirror downloads](https://cranlogs.r-pkg.org/badges/cli)](https://www.r-pkg.org/pkg/cli)
[![Codecov test coverage](https://codecov.io/gh/r-lib/cli/branch/main/graph/badge.svg)](https://app.codecov.io/gh/r-lib/cli?branch=main)
<!-- badges: end -->

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](https://github.com/tidyverse/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:

```r
install.packages("cli")
```

Install the development version from GitHub:

```r
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](https://github.com/tidyverse/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/`](https://cli.r-lib.org/reference/index.html)
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](https://cli.r-lib.org/dev/CODE_OF_CONDUCT.html).
By contributing to this project, you agree to abide by its terms.

# License

MIT © Posit Software, PBC