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
#|   - tidyr==1.3.1
#| r-version: ">= 4.3"
#| isolated: true
#| exclude-newer: 2024-02-01

airquality |> tidyr::drop_na(Ozone) |> dplyr::count(Month)

This records a last-known-good environment: tidyr is pinned to the version tested with the script, while the snapshot date selects dplyr and the transitive dependencies.

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 the default CRAN and Bioconductor repositories to Posit Package Manager snapshots with --exclude-newer, IR_EXCLUDE_NEWER, or frontmatter exclude-newer.
  • Select R with --rscript, --r-version, environment variables, frontmatter r-version, or exclude-newer. When r-version can match more than one R minor, exclude-newer limits the choice to minor versions released by the snapshot date.
  • 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 --with BiocGenerics -e 'library(BiocGenerics)'
$ ir run --exclude-newer 2024-02-01 script.R
$ ir render --r-version 4.3 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