ir

Self-describing R scripts, cached package libraries, and reproducible command-line runs.

ir runs standalone R scripts and renders or previews Quarto sources that declare their runtime requirements in the file itself. It resolves those requirements into cached package libraries and runs the program with the selected R.

#!/usr/bin/env -S ir run
#| packages:
#|   - dplyr>=1.0
#|   - tidyr
#| r-version: ">= 4.0"
#| isolated: true
#| exclude-newer: 2024-01-15

library(dplyr)
library(tidyr)

1 + 1

Features

  • Declare package requirements in script frontmatter and run the file directly with ir run.
  • Resolve packages once, then reuse content-addressed cached libraries on later runs.
  • Pin CRAN resolution to a Posit Package Manager snapshot with --exclude-newer, IR_EXCLUDE_NEWER, or frontmatter exclude-newer.
  • Select R with --rscript, --r-version, environment variables, frontmatter r-version, or date-only exclude-newer.
  • Evaluate inline expressions with ir run -e and add command-line packages with --with.
  • Render or preview Quarto documents and Quarto-formatted R scripts through ir render or ir preview, using the same package metadata model with rmarkdown seeded automatically for the knitr engine.
  • Run executables from R package exec/, bin/, or bin/<arch>/ directories with rx or ir tool run.
  • Install persistent launchers for package tools with ir tool install; installed tool libraries live in the durable tool store.
  • Inspect and clear run/render cache state with ir cache dir and ir cache clean.
  • Configure cache, Rscript, Quarto, and launcher destinations with environment variables.
  • Bootstrap resolver tooling (pak, renv, secretbase) automatically on first use, with no manual install.

Common commands

$ ir run script.R
$ ir run --with cli -e 'cli::cli_alert_success("hi")'
$ ir run --exclude-newer 2024-01-15 script.R
$ ir render --r-version 4.5 report.qmd --to html
$ ir preview report.qmd
$ rx btw --help
$ ir tool run --from btw btw --help
$ ir tool install btw
$ ir cache dir