R Cli App

Building CLI Apps with Rapp

Rapp (v0.3.0) is an R package that provides a drop-in replacement for Rscript that automatically parses command-line arguments into R values. It turns simple R scripts into polished CLI apps with argument parsing, help text, and subcommand support — with zero boilerplate.

R ≥ 4.1.0 | CRAN: install.packages("Rapp") | GitHub: r-lib/Rapp

After installing, put the Rapp launcher on PATH:

Rapp::install_pkg_cli_apps("Rapp")

This places the Rapp executable in ~/.local/bin (macOS/Linux) or %LOCALAPPDATA%\Programs\R\Rapp\bin (Windows).

---

Core Concept: Scripts Are the Spec

Rapp scans top-level expressions of an R script and converts specific patterns into CLI constructs. This means:

1. The same script works identically via source() and as a CLI tool.
2. You write normal R code — Rapp infers the CLI from what you write.
3. Default values in your R code become the CLI defaults.

Only top-level assignments are recognized. Assignments inside functions, loops, or conditionals are not parsed as CLI arguments.

---

Pattern Recognition: R → CLI Mapping

This table is the heart of Rapp — each R pattern automatically maps to a CLI surface:

| R Top-Level Expression | CLI Surface | Notes | |---|---|---| | foo | String option | | foo | Integer option | | foo | Float option | | foo | Optional integer (NA = not set) | | foo | Optional string (NA = not set) | | `foo (string, default "world") count (integer, default 1) threshold (float, default 0.5) seed (optional, NA if omitted) output (optional, NA if omitted)

For optional arguments, test whether the user supplied them:

```r
seed   Number of coin flips [default: 1] [type: integer]
      --sep       [default: " "] [type: string]
      --wrap / --no-wrap  [default: true]
      --seed     [default: NA] [type: integer]

Complete Example: Todo Manager (Subcommands)

#!/usr/bin/env Rapp
#| name: todo
#| description: Manage a simple todo list.

#| description: Path to the todo list file.
#| short: s
store = 0L) tasks `, so only `base`
and the package are auto-loaded. Use `library()` for other dependencies.

---

## Quick Reference: Common Patterns

### NA vs NULL for optional arguments

- **NA** (`NA_integer_`, `NA_character_`) → optional **named option**.
  Test: `!is.na(x)`.
- **NULL** + `#| required: false` → optional **positional arg**.
  Test: `!is.null(x)`.

### stdin/stdout

```r
input_file <- NA_character_
con <- if (is.na(input_file)) file("stdin") else file(input_file, "r")
lines <- readLines(con)
writeLines(lines, stdout())

Exit codes and stderr

message("Error: something went wrong")   # writes to stderr
cat("Error:", msg, "\n", file = stderr()) # also stderr
quit(status = 1)                          # non-zero exit

Error handling

tryCatch({
  result <- do_work()
}, error = function(e) {
  cat("Error:", conditionMessage(e), "\n", file = stderr())
  quit(status = 1)
})

---

Additional Reference

For less common topics — launcher customization (#| launcher: front matter), detailed Rapp::install_pkg_cli_apps() API options, and more complete examples (deduplication filter, variadic install-pkg, interactive fallback) — read references/advanced.md.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: posit-dev
• Source: posit-dev/skills
• License: MIT

Install and usage instructions live in the source repository linked above.