% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/docs.R
\name{cli-config}
\alias{cli-config}
\title{cli environment variables and options}
\description{
cli environment variables and options
}
\section{User facing configuration}{


These are environment variables and options that users may set, to modify
the behavior of cli.
\subsection{Hyperlinks}{

cli uses ANSI escape sequences to create hyperlinks.
Specifically, cli creates \href{https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda}{OSC 8 hyperlinks} that have this syntax:

\if{html}{\out{<div class="sourceCode">}}\preformatted{OSC 8 ; \{OPTIONAL PARAMS \} ; \{URI\} ST \{LINK TEXT\} OSC 8 ; ; ST
}\if{html}{\out{</div>}}

Under the hood, \code{\link[=style_hyperlink]{style_hyperlink()}} is the helper that forms these links, but it is more common to request them indirectly via inline markup (documented in \code{help("links")}).
\subsection{\code{R_CLI_HYPERLINK_MODE}}{

Set to \code{posix} to force generating POSIX compatible ANSI hyperlinks.
This is about the specific operating system command (OSC) and string terminator (ST) used in hyperlinks.

If not set, then RStudio compatible links are generated. This is a
temporary crutch until RStudio handles POSIX hyperlinks correctly, and
after that it will be removed.
}

\subsection{\code{cli.hyperlink} option and \code{R_CLI_HYPERLINKS} env var}{

Set this option or env var to \code{true}, \code{TRUE} or \code{True} to tell cli that the terminal supports ANSI hyperlinks.
Leave this configuration unset (or set to anything else) when there is no hyperlink support.
Specifically, this configuration indicates the support for URL and file hyperlinks, requested via markup like \verb{\{.href url\}} or \verb{\{.file path/file\}}.
(Below we describe the configuration that indicates support for even more specialized types of hyperlinks.)

The option \code{cli.hyperlink} takes precedence over the \code{R_CLI_HYPERLINKS} env var.
}

\subsection{\verb{cli.hyperlink_*} options and \verb{R_CLI_HYPERLINK_*} env vars}{

cli supports a few special types of hyperlink that go beyond pointing to, e.g., a webpage or a file.
These specialized hyperlinks cause R-specific actions to happen, such as executing a bit of R code or opening specific documentation.

Set the relevant option or env var to \code{true}, \code{TRUE}, or \code{True} to tell cli that the terminal is capable of implementing these specialized behaviours.
Leave this configuration unset (or set to anything else) when there is no support for a specific type of hyperlink.\tabular{llll}{
   Action \tab Example inline markup \tab Option \tab Env var \cr
   Run R code \tab \verb{\{.run testthat::snapshot_review()\}} \tab \code{cli.hyperlink_run} \tab \code{R_CLI_HYPERLINK_RUN} \cr
   Open a help topic \tab \verb{\{.fun stats::lm\}} \verb{\{.topic tibble::tibble_options\}} \verb{\{.help [\{.fun lm\}](stats::lm)\}} \tab \code{cli.hyperlink_help} \tab \code{R_CLI_HYPERLINK_HELP} \cr
   Open a vignette \tab \verb{\{.vignette tibble::types\}} \tab \code{cli.hyperlink_vignette} \tab \code{R_CLI_HYPERLINK_VIGNETTE} \cr
}


In all cases, the option takes priority over the corresponding env var.
}

\subsection{\verb{cli.hyperlink_*_url_format} options and \verb{R_CLI_HYPERLINK_*_URL_FORMAT} env vars}{

Recall the overall structure of cli's hyperlinks:

\if{html}{\out{<div class="sourceCode">}}\preformatted{OSC 8 ; \{OPTIONAL PARAMS \} ; \{URI\} ST \{LINK TEXT\} OSC 8 ; ; ST
}\if{html}{\out{</div>}}

The \code{URI} part has a default format for each type of hyperlink, but it is possible to provide a custom format via an option or an env var.
If defined, the option takes priority over the env var.\tabular{llll}{
   Action \tab Default URI format \tab Customize via option \tab Customize via env var \cr
   Open a file \tab (see below) \tab \code{cli.hyperlink_file_url_format} \tab \code{R_CLI_HYPERLINK_FILE_URL_FORMAT} \cr
   Run R code \tab \code{x-r-run:{code}} \tab \code{cli.hyperlink_run_url_format} \tab \code{R_CLI_HYPERLINK_RUN_URL_FORMAT} \cr
   Open a help topic \tab \code{x-r-help:{topic}} \tab \code{cli.hyperlink_help_url_format} \tab \code{R_CLI_HYPERLINK_HELP_URL_FORMAT} \cr
   Open a vignette \tab \code{x-r-vignette:{vignette}} \tab \code{cli.hyperlink_vignette_url_format} \tab \code{R_CLI_HYPERLINK_VIGNETTE_URL_FORMAT} \cr
}


A format must be a glue-like template with the relevant placeholder in curly braces (\code{code}, \code{topic} or \code{vignette}).

Here's an example of a custom URI format for runnable code, which is useful in an integrated Positron terminal:

\if{html}{\out{<div class="sourceCode">}}\preformatted{positron://positron.positron-r/cli?command=x-r-run:\{code\}
}\if{html}{\out{</div>}}

(For backwards compatibility with older versions of RStudio, in some contexts, a legacy format is used, e.g. \code{ide:run:{code}}.)

The default handling for file hyperlinks is geared towards the expectations of RStudio and can't really be expressed as a URI format, but it's approximately \verb{file://\{path\}}, plus possibly passing \code{line} and \code{col} (yes, it really is \code{col}, not \code{column}) in the \verb{OPTIONAL PARAMS} part of the OSC 8 hyperlink.

A custom format can be provided for file hyperlinks and the relevant placeholders are \code{path}, \code{line}, and \code{column}.
Examples of custom file hyperlink formats:

\if{html}{\out{<div class="sourceCode">}}\preformatted{positron://file\{path\}:\{line\}:\{column\}
vscode://file\{path\}:\{line\}:\{column\}
txmt://open?url=file://\{path\}&line=\{line\}&column=\{column\}
}\if{html}{\out{</div>}}

It's OK if the format includes only \code{path}.
}

}

\subsection{User facing environment variables}{
\subsection{\code{NO_COLOR}}{

Set to a nonempty value to turn off ANSI colors.
See \code{\link[=num_ansi_colors]{num_ansi_colors()}}.
}

\subsection{\code{ESS_BACKGROUND_MODE}}{

Set this environment variable to \code{light} or \code{dark} to indicate dark mode
in Emacs. Once https://github.com/emacs-ess/ESS/pull/1178 is merged, ESS
will set this automatically.
}

\subsection{\code{R_CLI_DYNAMIC}}{

Set to \code{true}, \code{TRUE} or \code{True} to assume a dynamic terminal, that supports \verb{\\r}.
Set to anything else to assume a non-dynamic terminal.
See \code{\link[=is_dynamic_tty]{is_dynamic_tty()}}.
}

\subsection{\code{R_CLI_NUM_COLORS}}{

Set to a positive integer to assume a given number of colors.
See \code{\link[=num_ansi_colors]{num_ansi_colors()}}.
}

}

\subsection{User facing options}{
\subsection{\code{cli.ansi}}{

Set to \code{true}, \code{TRUE} or \code{True} to assume a terminal that supports ANSI
control sequences.
Set to anything else to assume a non-ANSI terminal.
See \code{\link[=is_ansi_tty]{is_ansi_tty()}}.
}

\subsection{\code{cli.condition_unicode_bullets}}{

\code{TRUE} or \code{FALSE} to force turn on or off the Unicode symbols when printing
conditions. E.g. in \code{format_error()}, \code{format_warning()}, \code{format_message()} and
also in \code{cli_abort()}, \code{cli_warn()} and \code{cli_inform()}.
}

\subsection{\code{cli.condition_width}}{

Integer scalar (or \code{Inf}) to set the console width when cli is formatting
errors, warnings or messages in \code{format_error()}, \code{format_warning()} and
\code{format_message()}. When formatting conditions this option takes precedence
over \code{cli.width}.
}

\subsection{\code{cli.default_handler}}{

General handler function for all cli conditions.
See \url{https://cli.r-lib.org/articles/semantic-cli.html#cli-messages-1}
}

\subsection{\code{cli.default_num_colors}}{

Default number of ANSI colors. This value is used if the number of colors
is not already set by
\itemize{
\item the \code{cli.num_colors} option,
\item the \code{R_CLI_NUM_COLORS} environment variable,
\item the \code{crayon.enabled} and \code{crayon.colors} options,
\item the \code{NO_COLOR} environment variable,
\item the \code{knitr.in.progress} option,
\item a \code{sink()} call for the stream.
}

You can also use this option if color support is detected correctly, but
you want to adjust the number of colors. E.g.
\itemize{
\item if \code{crayon.enabled} is \code{TRUE}, but \code{crayon.colors} is not,
\item in Emacs on Windows,
\item in terminals.
}

See \code{\link[=num_ansi_colors]{num_ansi_colors()}}. See also the \code{cli.num_colors} option.
}

\subsection{\code{cli.dynamic}}{

Set to \code{TRUE} to assume a dynamic terminal, that supports \verb{\\r}.
Set to anything else to assume a non-dynamic terminal.
See \code{\link[=is_dynamic_tty]{is_dynamic_tty()}}.
}

\subsection{\code{cli.hide_cursor}}{

Whether the cli status bar should try to hide the cursor on terminals.
Set the \code{FALSE} if the hidden cursor causes issues.
}

\subsection{\code{cli.ignore_unknown_rstudio_theme}}{

Set to \code{TRUE} to omit a warning for an unknown RStudio theme in
\code{code_highlight()}.
}

\subsection{\code{cli.num_colors}}{

Number of ANSI colors. See \code{\link[=num_ansi_colors]{num_ansi_colors()}}. See also the
\code{cli.default_num_colors} option.
}

\subsection{\code{cli.message_class}}{

Character vector of classes to add to cli's conditions.
}

\subsection{\code{cli.progress_bar_style}}{

Progress bar style.
See \code{\link[=cli_progress_styles]{cli_progress_styles()}}.
}

\subsection{\code{cli.progress_bar_style_ascii}}{

Progress bar style on ASCII consoles.
See \code{\link[=cli_progress_styles]{cli_progress_styles()}}.
}

\subsection{\code{cli.progress_bar_style_unicode}}{

Progress bar style on Unicode (UTF-8) consoles;
See \code{\link[=cli_progress_styles]{cli_progress_styles()}}.
}

\subsection{\code{cli.progress_clear}}{

Whether to clear terminated progress bar from the screen on dynamic terminals.
See \code{\link[=cli_progress_bar]{cli_progress_bar()}}.
}

\subsection{\code{cli.progress_demo_live}}{

Whether \code{cli_progress_demo()} should show a live demo, or just record the
progress bar frames.
}

\subsection{\code{cli.progress_format_download}}{

Default format string for \code{download} progress bars.
}

\subsection{\code{cli.progress_format_download_nototal}}{

Default format string for \code{download} progress bars with unknown totals.
}

\subsection{\code{cli.progress_format_iterator}}{

Default format string for \code{iterator} progress bars.
}

\subsection{\code{cli.progress_format_iterator_nototal}}{

Default format string for \code{iterator} progress bars with unknown total number
of progress units.
}

\subsection{\code{cli.progress_format_tasks}}{

Default format string for \code{tasks} progress bars.
}

\subsection{\code{cli.progress_format_tasks_nototal}}{

Default format string for \code{tasks} progress bars with unknown totals.
}

\subsection{\code{cli.progress_handlers}}{

Progress handlers to try.
See \code{\link[=cli_progress_builtin_handlers]{cli_progress_builtin_handlers()}}.
}

\subsection{\code{cli.progress_handlers_force}}{

Progress handlers that will always be used, even if another handler
was already selected.
See \code{\link[=cli_progress_builtin_handlers]{cli_progress_builtin_handlers()}}.
}

\subsection{\code{cli.progress_handlers_only}}{

Progress handlers to force, ignoring handlers set in
\code{cli.progress_handlers} and \code{cli.progress_handlers_force}.
See \code{\link[=cli_progress_builtin_handlers]{cli_progress_builtin_handlers()}}.
}

\subsection{\code{cli.progress_say_args}}{

Command line arguments for the \code{say} progress handlers.
See \code{\link[=cli_progress_builtin_handlers]{cli_progress_builtin_handlers()}}.
}

\subsection{\code{cli.progress_say_command}}{

External command to use in the \code{say} progress handler.
See \code{\link[=cli_progress_builtin_handlers]{cli_progress_builtin_handlers()}}.
}

\subsection{\code{cli.progress_say_frequency}}{

Minimum delay between \code{say} calls in the \code{say} progress handler.
\code{say} ignores very frequent updates, to keep the speech comprehensible.
See \code{\link[=cli_progress_builtin_handlers]{cli_progress_builtin_handlers()}}.
}

\subsection{\code{cli.progress_show_after}}{

Delay before showing a progress bar, in seconds.
Progress bars that finish before this delay are not shown at all.
cli also shows progress bars that have more than 50\% to go after half of
this delay has passed.
}

\subsection{\code{cli.spinner}}{

Default spinner to use, see \code{\link[=get_spinner]{get_spinner()}}.
}

\subsection{\code{cli.spinner_ascii}}{

Default spinner to use on ASCII terminals, see \code{\link[=get_spinner]{get_spinner()}}.
}

\subsection{\code{cli.spinner_unicode}}{

Default spinner to use on Unicode terminals, see \code{\link[=get_spinner]{get_spinner()}}.
}

\subsection{\code{cli.theme}}{

Default cli theme, in addition to the built-in theme.
This option in intended for the package developers.
See \link{themes} and \code{\link[=start_app]{start_app()}}.
}

\subsection{\code{cli.theme_dark}}{

Whether cli should assume a dark theme for the builtin theme.
See \code{\link[=builtin_theme]{builtin_theme()}}.
}

\subsection{\code{cli.unicode}}{

Whether to assume a Unicode terminal.
If not set, then it is auto-detected.
See \code{\link[=is_utf8_output]{is_utf8_output()}}.
}

\subsection{\code{cli.user_theme}}{

cli user theme.
This option is intended for end users.
See \link{themes}.
}

\subsection{\code{cli.warn_inline_newlines}}{

Whether to emit a warning when cli replaces newline characters with
spaces within a \code{{.class }} inline style.
Defaults to \code{FALSE}.
}

\subsection{\code{cli.width}}{

Terminal width to assume.
If not set, then it is auto-detected.
See \code{\link[=console_width]{console_width()}}.
}

\subsection{\code{rlib_interactive}}{

Whether to assume an interactive R session.
If not set, then it is auto-detected.
}

\subsection{\code{width}}{

Terminal width.
This is used on some platforms, if \code{cli.width} is not set.
}

}
}

\section{Internal configuration}{


These environment variables and options are for cli developers. Users
should not rely on them as they may change between cli releases.
\subsection{Internal environment variables}{
\subsection{\code{ASCIICAST}}{

Used to detect an asciicast sub-process in RStudio.
}

\subsection{\code{ANSICON}}{

Used to detect ANSICON when detecting the number of ANSI colors.
}

\subsection{\code{CI}}{

Used to detect if the code is running on a CI.
If yes, we avoid ANSI hyperlinks.
}

\subsection{\code{CLI_DEBUG_BAD_END}}{

Whether to warn about \code{cli_end()} calls when there is no container to close.
}

\subsection{\code{CLI_NO_BUILTIN_THEME}}{

Set it to \code{true} to omit the builtin theme.
}

\subsection{\code{CLI_SPEED_TIME}}{

Can be used to speed up cli's timer.
It is a factor, e.g. setting it to 2 makes cli's time go twice as fast.
}

\subsection{\code{CLI_TICK_TIME}}{

How often the cli timer should alert, in milliseconds.
}

\subsection{\code{CMDER_ROOT}}{

Used to detect cmder when detecting the number of ANSI colors.
}

\subsection{\code{COLORTERM}}{

Used when detecting ANSI color support.
}

\subsection{\code{ConEmuANSI}}{

Used to detect ConEmu when detecting the number of ANSI colors.
}

\subsection{\code{EMACS}}{

Used to detect Emacs.
}

\subsection{\code{INSIDE_EMACS}}{

Used to detect Emacs.
}

\subsection{\code{NOT_CRAN}}{

Set to \code{true} to run tests / examples / checks, that do not run on CRAN.
}

\subsection{\verb{_R_CHECK_PACKAGE_NAME_}}{

Used to detect \verb{R CMD check}.
}

\subsection{\code{R_BROWSER}}{

Used to detect the RStudio build pane.
}

\subsection{\code{R_GUI_APP_VERSION}}{

Used to detect R.app on macOS, to decide if the console has ANSI control
sequences.
}

\subsection{\code{R_PACKAGE_DIR}}{

Used to detect if the code is running under \verb{R CMD INSTALL}.
}

\subsection{\code{R_PDFVIEWER}}{

Used to detect the RStudio build pane.
}

\subsection{\code{R_PROGRESS_NO_EXAMPLES}}{

Set to \code{true} to avoid running examples, outside of \verb{R CMD check}.
}

\subsection{\code{RSTUDIO}}{

Used to detect RStudio, in various functions.
}

\subsection{\code{RSTUDIO_CONSOLE_COLOR}}{

Used to detect the number of colors in RStudio.
See \code{\link[=num_ansi_colors]{num_ansi_colors()}}.
}

\subsection{\code{RSTUDIO_CONSOLE_WIDTH}}{

Used to auto-detect console width in RStudio.
}

\subsection{\code{RSTUDIO_TERM}}{

Used to detect the RStudio build pane.
}

\subsection{\code{TEAMCITY_VERSION}}{

Used to detect the TeamCity CI, to turn off ANSI hyperlinks.
}

\subsection{\code{TERM}}{

Used to detect if the console has ANSI control sequences, in a terminal.
}

\subsection{\code{TERM_PROGRAM}}{

Used to detect iTerm for the dark theme detection and the ANSI hyperlink
support detection.
}

\subsection{\code{TERM_PROGRAM_VERSION}}{

Used to detect a suitable iTerm version for ANSI hyperlink support.
}

\subsection{\code{TESTTHAT}}{

Used to detect running in testthat tests.
}

\subsection{\code{VTE_VERSION}}{

Used to detect a suitable VTE version for ANSI hyperlinks.
}

}

\subsection{Internal options}{
\subsection{\code{cli__pb}}{

This option is set to the progress bar that is being updated, when
interpolating the format string.
}

\subsection{\code{cli.record}}{

Internal option to mark the state that cli is recording messages.
}

\subsection{\code{crayon.colors}}{

Deprecated option for the number of ANSI colors, that is still supported
by cli, when the new options are not set.
See \code{\link[=num_ansi_colors]{num_ansi_colors()}}.
}

\subsection{\code{crayon.enabled}}{

Deprecated option to turn ANSI colors on/off.
This is still supported by cli when the new options are not set.
See \code{\link[=num_ansi_colors]{num_ansi_colors()}}.
}

\subsection{\code{crayon.hyperlink}}{

Whether to assume ANSI hyperlink support.
See \code{\link[=ansi_has_hyperlink_support]{ansi_has_hyperlink_support()}}.
}

\subsection{\code{knitr.in.progress}}{

Used to detect knitr when detecting interactive sessions and ANSI color
support.
}

\subsection{\code{rstudio.notebook.executing}}{

Used to detect knitr when detecting interactive sessions.
}

}
}