minicli

minicli is a minimal stand-in for the small slice of cli most packages actually use: coloured alert messages, unicode symbols with an ascii fallback, a rule, and a bullet list. See the README for the full API reference and capability-detection details; this page walks through each piece and builds up to how they combine.

Functions

Core functions

• mcli_alert_success()/_danger()/_warning()/_info() – print a message() with a coloured symbol prefix; extra ... arguments are passed through sprintf().
• mcli_symbol(name) – look up a single symbol by name, returning its unicode glyph or an ascii fallback depending on what’s safe to print.
• mcli_rule(title = NULL) – print a horizontal divider spanning the console width, optionally with a centred title.
• mcli_bullets(items) – print a simple bulleted list, one entry per line.
• mcli_col_black()/_red()/_green()/_yellow()/_blue()/ _magenta()/_cyan()/_white()/_grey() – wrap a string in an ANSI colour code.
• mcli_style_bold()/_dim()/_italic()/_underline() – wrap a string in an ANSI style code.

Internal helpers

• .mcli_ansi_enabled() – decide whether it’s currently safe to emit ANSI escape codes (checks cli.num_colors, NO_COLOR, whether knitr/Quarto is rendering, whether output is being captured, and whether stdout is a real terminal).
• .mcli_unicode_enabled() – decide whether it’s currently safe to print unicode symbols (checks cli.unicode, then the session’s locale).
• .mcli_ansi_style(code) – factory that builds one of the mcli_col_*()/mcli_style_*() functions from a raw SGR code.
• .mcli_alert(symbol_name, color_fn, text, ...) – shared implementation behind the four mcli_alert_*() functions.

Capability detection

Every colour/symbol decision in minicli runs through .mcli_ansi_enabled() and .mcli_unicode_enabled(), so the same code looks right whether it’s running in an interactive terminal that supports unicode and colour, a plain terminal that supports neither, or – as on this page – a Quarto render. Quarto/knitr renders are detected as a non-terminal (getOption("knitr.in.progress")), so ANSI colour is disabled automatically here. That means the alerts below print in plain text with their symbol prefix, exactly as they would in a captured log or a non-interactive session, rather than showing colour codes as literal text on the page.

Alerts

mcli_alert_success()/_danger()/_warning()/_info() are the functions you’ll reach for most often: thin message() wrappers with a symbol prefix, meant for the kind of status line a script prints while it works. Extra ... arguments are passed through sprintf(), so the first argument can be a format string:

mcli_alert_success("Wrote %d files to %s", 3, "output/")

✔ Wrote 3 files to output/

mcli_alert_warning("Skipped %d rows with missing values", 12)

⚠ Skipped 12 rows with missing values

mcli_alert_danger("Failed to connect to %s", "database")

✖ Failed to connect to database

mcli_alert_info("Using default configuration")

ℹ Using default configuration

If there’s no ... to format with, the text is used as-is – no sprintf() call, so a literal % in the message is safe:

mcli_alert_info("Discount: 10% off")

ℹ Discount: 10% off

Symbols

Each alert’s prefix comes from mcli_symbol(), which looks up a named symbol and returns either its unicode glyph or an ascii fallback, depending on .mcli_unicode_enabled(). It’s also useful on its own, for building custom messages that follow the same convention as the built-in alerts:

mcli_symbol("tick")

[1] "✔"

mcli_symbol("cross")

[1] "✖"

mcli_symbol("arrow_right")

[1] "→"

An unrecognised name is an error rather than a silent NA:

mcli_symbol("star")

Error:
! Unknown symbol: star

Rule

mcli_rule() prints a horizontal divider, useful for separating sections of console output. Called with no arguments, it spans the full console width:

mcli_rule()

────────────────────────────────────────────────────────────────────────────────

Pass a title and it’s centred within the rule instead:

mcli_rule("Summary")

─────────────────────────────────── Summary ────────────────────────────────────

Bullets

mcli_bullets() prints a simple bulleted list, one entry per line – handy for summarising a small set of results without reaching for a full table:

mcli_bullets(c("one", "two", "three"))

• one
• two
• three

Colours and styles

Under the hood, each alert calls one of the mcli_col_*() functions to colour its symbol. Those functions – along with the mcli_style_*() family – are also exported directly, for colouring or styling arbitrary text of your own. Both wrap their input in an ANSI escape code and its matching reset code, and both are no-ops (returning the text unchanged) whenever .mcli_ansi_enabled() is FALSE – which, per the capability-detection note above, is always true on this page:

identical(mcli_col_red("danger"), "danger")

[1] TRUE

identical(mcli_style_bold("emphasis"), "emphasis")

[1] TRUE

Colours and styles nest freely, since each wrapper’s reset code is emitted immediately after its own content rather than at the very end of the whole string:

mcli_style_bold(mcli_col_red("bold and red"))

[1] "bold and red"

Outside of a Quarto render – in an interactive terminal session, say – that same call would print bold red text rather than the plain string shown here.