From 647548be9d9b3f7e50d9cacbcd7b0cf9ca7fbb9e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?G=C3=A1bor=20Cs=C3=A1rdi?= <csardi.gabor@gmail.com>
Date: Thu, 1 Oct 2026 14:49:40 +0200
Subject: [PATCH] Improve shebang in scripts

Closes #413.
---
 NEWS.md               |   5 +
 src/args.rs           | 241 ++++++++++++++++++++++++++++++++++++++++--
 src/help-generated.in |   2 +-
 src/help/run.md       |  18 +++-
 src/scrun.rs          |  28 +----
 tests/test-linux.sh   |   8 ++
 tests/test-macos.sh   |   8 ++
 7 files changed, 272 insertions(+), 38 deletions(-)

diff --git a/NEWS.md b/NEWS.md
index 122be64e..86e6366e 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -52,6 +52,11 @@
   `rig proj sync` uses this target only if no other target matches the
   machine.
 
+* `rig run <script>` now passes every argument after the script on to the
+  script, including the ones starting with `-`, and `--`. A script that
+  starts with `#!`, e.g. `#!/usr/bin/env -S rig run`, does not need an
+  `.R` extension any more (#413).
+
 ## Windows specific changes
 
 * The rig binaries themselves are now signed on Windows, not only the
diff --git a/src/args.rs b/src/args.rs
index 79647ca4..ea688047 100644
--- a/src/args.rs
+++ b/src/args.rs
@@ -2961,20 +2961,62 @@ where
     out
 }
 
+/// Whether `arg` is an existing file that `rig run <arg>` runs as a script,
+/// same as `rig run -f <arg>`: a `.R` file, or any file that starts with
+/// `#!`, so a script with a `#!/usr/bin/env -S rig run` line can have any
+/// name.
+pub fn is_r_script_file(arg: &str) -> bool {
+    use std::io::Read;
+    let path = std::path::Path::new(arg);
+    if !path.is_file() {
+        return false;
+    }
+    if path
+        .extension()
+        .is_some_and(|ext| ext.eq_ignore_ascii_case("r"))
+    {
+        return true;
+    }
+    let mut start = [0u8; 2];
+    std::fs::File::open(path)
+        .and_then(|mut f| f.read_exact(&mut start))
+        .is_ok_and(|_| &start == b"#!")
+}
+
+// `rig run` options that take a value, in a separate argument unless they
+// are written as `--opt=value` or `-oVALUE`.
+const RUN_VALUE_OPTS: [&str; 8] = [
+    "-r",
+    "--r-version",
+    "-t",
+    "--app-type",
+    "-e",
+    "--eval",
+    "-f",
+    "--script",
+];
+
 // Splits `rig`'s raw arguments before clap sees them.
 //
 // `rig run --cmd <command> [args...]`: unchanged, delegates to
 // `rcmd_argv()` -- a literal `--` is auto-inserted right after `--cmd` so
 // clap doesn't reinterpret the R CMD command's own flags as rig's.
 //
-// `rig run [...] -- <r-args...>` (without `--cmd`): a literal `--`
-// separates rig's own arguments (an eval/script/app name and its own
-// arguments) from raw R/`Rscript` engine flags, e.g. `rig run -- --vanilla`
-// or `rig run report --format pdf -- --vanilla`. Everything from that `--`
-// onward is pulled out *here*, before clap ever sees it, so it can never
-// collide with rig's own flags (not even the built-in `--help`/`--version`),
-// and returned separately for `sc_run()` to forward straight to the R
-// process. `--` is not otherwise meaningful to any rig command.
+// `rig run [...] <script> [args...]` and `rig run [...] -f <script>
+// [args...]`: every argument after the script goes to the script as is,
+// even if it looks like a flag of rig, or it is a `--`. This is what a
+// script with a `#!/usr/bin/env -S rig run` line needs. A `--` is inserted
+// before these arguments, so clap puts them into `command` unchanged.
+//
+// `rig run [...] -- <r-args...>` (otherwise): a literal `--` separates rig's
+// own arguments (an eval expression, or an app or project script name and
+// its own arguments) from raw R/`Rscript` engine flags, e.g.
+// `rig run -- --vanilla` or `rig run report --format pdf -- --vanilla`.
+// Everything from that `--` onward is pulled out *here*, before clap ever
+// sees it, so it can never collide with rig's own flags (not even the
+// built-in `--help`/`--version`), and returned separately for `sc_run()` to
+// forward straight to the R process. `--` is not otherwise meaningful to
+// any rig command.
 fn split_run_args<I>(argv: I) -> (Vec<std::ffi::OsString>, Vec<String>)
 where
     I: IntoIterator<Item = std::ffi::OsString>,
@@ -2986,6 +3028,23 @@ where
     }
     let mut out = Vec::new();
     let mut iter = argv.into_iter();
+    // argv[0], then global flags (none of them takes a value) up to the
+    // subcommand.
+    let mut is_run = false;
+    if let Some(arg0) = iter.next() {
+        out.push(arg0);
+    }
+    for arg in iter.by_ref() {
+        let flag = arg.to_string_lossy().starts_with('-');
+        is_run = arg.as_os_str() == OsStr::new("run");
+        out.push(arg);
+        if !flag {
+            break;
+        }
+    }
+    // Only scripts given before the first non-script positional argument
+    // count, the arguments of an app or a project script are not checked.
+    let mut seen_positional = false;
     while let Some(arg) = iter.next() {
         if arg.as_os_str() == OsStr::new("--") {
             return (
@@ -2993,7 +3052,37 @@ where
                 iter.map(|a| a.to_string_lossy().into_owned()).collect(),
             );
         }
+        let s = arg.to_string_lossy().into_owned();
         out.push(arg);
+        if !is_run || seen_positional {
+            continue;
+        }
+        let script = if s == "-f" || s == "--script" {
+            match iter.next() {
+                Some(file) => {
+                    out.push(file);
+                    true
+                }
+                None => false,
+            }
+        } else if s.starts_with("--script=") || (s.starts_with("-f") && s.len() > 2) {
+            true
+        } else if RUN_VALUE_OPTS.contains(&s.as_str()) {
+            if let Some(value) = iter.next() {
+                out.push(value);
+            }
+            false
+        } else if s.starts_with('-') {
+            false
+        } else {
+            seen_positional = true;
+            is_r_script_file(&s)
+        };
+        if script {
+            out.push(std::ffi::OsString::from("--"));
+            out.extend(iter);
+            return (out, vec![]);
+        }
     }
     (out, vec![])
 }
@@ -3307,6 +3396,142 @@ mod tests {
         assert_eq!(r_args, ["--vanilla"]);
     }
 
+    #[test]
+    fn test_is_r_script_file() {
+        let dir = tempfile::tempdir().unwrap();
+        let upper = dir.path().join("a.R");
+        let lower = dir.path().join("b.r");
+        let other = dir.path().join("c.Rmd");
+        let shebang = dir.path().join("d");
+        let plain = dir.path().join("e");
+        let short = dir.path().join("f");
+        for f in [&upper, &lower, &other, &plain] {
+            std::fs::write(f, "1\n").unwrap();
+        }
+        std::fs::write(&shebang, "#!/usr/bin/env -S rig run\n1\n").unwrap();
+        std::fs::write(&short, "#").unwrap();
+        assert!(is_r_script_file(upper.to_str().unwrap()));
+        assert!(is_r_script_file(lower.to_str().unwrap()));
+        assert!(is_r_script_file(shebang.to_str().unwrap()));
+        assert!(!is_r_script_file(other.to_str().unwrap()));
+        assert!(!is_r_script_file(plain.to_str().unwrap()));
+        assert!(!is_r_script_file(short.to_str().unwrap()));
+        assert!(!is_r_script_file(
+            dir.path().join("missing.R").to_str().unwrap()
+        ));
+        assert!(!is_r_script_file(dir.path().to_str().unwrap()));
+    }
+
+    // A directory with an `s.R` script and an `s` script without an
+    // extension, but with a `#!` line.
+    fn script_dir() -> (tempfile::TempDir, String, String) {
+        let dir = tempfile::tempdir().unwrap();
+        let r = dir.path().join("s.R");
+        let sh = dir.path().join("s");
+        std::fs::write(&r, "1\n").unwrap();
+        std::fs::write(&sh, "#!/usr/bin/env -S rig run\n1\n").unwrap();
+        let r = r.to_string_lossy().into_owned();
+        let sh = sh.to_string_lossy().into_owned();
+        (dir, r, sh)
+    }
+
+    #[test]
+    fn test_split_run_args_script_args() {
+        let (_dir, r, _) = script_dir();
+        let (out, r_args) = split(&["rig", "run", &r, "a", "--foo", "-x"]);
+        assert_eq!(out, ["rig", "run", &r, "--", "a", "--foo", "-x"]);
+        assert!(r_args.is_empty());
+    }
+
+    #[test]
+    fn test_split_run_args_script_gets_separator() {
+        let (_dir, r, _) = script_dir();
+        let (out, r_args) = split(&["rig", "run", &r, "a", "--", "b"]);
+        assert_eq!(out, ["rig", "run", &r, "--", "a", "--", "b"]);
+        assert!(r_args.is_empty());
+    }
+
+    #[test]
+    fn test_split_run_args_shebang_script() {
+        let (_dir, _, sh) = script_dir();
+        let (out, r_args) = split(&["rig", "run", &sh, "--help"]);
+        assert_eq!(out, ["rig", "run", &sh, "--", "--help"]);
+        assert!(r_args.is_empty());
+    }
+
+    #[test]
+    fn test_split_run_args_script_flag() {
+        let (_dir, _, sh) = script_dir();
+        let (out, _) = split(&["rig", "run", "-f", &sh, "a", "--help"]);
+        assert_eq!(out, ["rig", "run", "-f", &sh, "--", "a", "--help"]);
+        let opt = format!("--script={}", sh);
+        let (out, _) = split(&["rig", "run", &opt, "-r", "4.4"]);
+        assert_eq!(out, ["rig", "run", &opt, "--", "-r", "4.4"]);
+    }
+
+    #[test]
+    fn test_split_run_args_rig_options_before_script() {
+        let (_dir, r, _) = script_dir();
+        let (out, _) = split(&[
+            "rig",
+            "--user",
+            "run",
+            "-r",
+            "4.4",
+            "--rscript",
+            &r,
+            "--dry-run",
+        ]);
+        assert_eq!(
+            out,
+            [
+                "rig",
+                "--user",
+                "run",
+                "-r",
+                "4.4",
+                "--rscript",
+                &r,
+                "--",
+                "--dry-run"
+            ]
+        );
+        // `-e` takes a value, which is not a script, even if it names a file.
+        let (out, r_args) = split(&["rig", "run", "-e", &r, "--", "--vanilla"]);
+        assert_eq!(out, ["rig", "run", "-e", &r]);
+        assert_eq!(r_args, ["--vanilla"]);
+    }
+
+    #[test]
+    fn test_split_run_args_script_only_first_positional() {
+        // The arguments of an app are not scripts.
+        let (_dir, r, _) = script_dir();
+        let (out, r_args) = split(&["rig", "run", "myapp", &r, "--", "--vanilla"]);
+        assert_eq!(out, ["rig", "run", "myapp", &r]);
+        assert_eq!(r_args, ["--vanilla"]);
+    }
+
+    #[test]
+    fn test_run_script_args() {
+        let (_dir, r, sh) = script_dir();
+        let matches = |argv: &[&str]| {
+            let (out, _) = split(argv);
+            rig_app().try_get_matches_from(out).unwrap()
+        };
+        let m = matches(&["rig", "run", &r, "a", "--dry-run", "--", "-x"]);
+        let run = m.subcommand_matches("run").unwrap();
+        assert!(!run.get_flag("dry-run"));
+        let cmdargs: Vec<&String> = run.get_many::<String>("command").unwrap().collect();
+        assert_eq!(cmdargs, [&r, "a", "--dry-run", "--", "-x"]);
+
+        let m = matches(&["rig", "run", "--dry-run", "-f", &sh, "--help"]);
+        let run = m.subcommand_matches("run").unwrap();
+        assert!(run.get_flag("dry-run"));
+        assert_eq!(run.get_one::<String>("script"), Some(&sh));
+        let cmdargs: Vec<&String> = run.get_many::<String>("command").unwrap().collect();
+        assert_eq!(cmdargs, ["--help"]);
+    }
+
     #[test]
     fn test_split_run_args_cmd_untouched() {
         // Any `--cmd` in the argv delegates entirely to `rcmd_argv()`, and no
diff --git a/src/help-generated.in b/src/help-generated.in
index 7817c60f..fde1224a 100644
--- a/src/help-generated.in
+++ b/src/help-generated.in
@@ -126,7 +126,7 @@ const HELP_RTOOLS_RM: &str = "\u{1b}[1m\u{1b}[34mDescription:\u{1b}[39m\u{1b}[22
 const ABOUT_RTOOLS: &str = "Manage Rtools installations";
 const HELP_RTOOLS: &str = "\u{1b}[1m\u{1b}[34mDescription:\u{1b}[39m\u{1b}[22m\n  Manage Rtools installations (Windows only).\n\n  Rtools is the collection of build tools (compilers, \u{1b}[32mmake\u{1b}[39m, etc.) needed to\n  build R packages from source on Windows. Each R version needs a matching\n  Rtools version.\n\n  \u{1b}[32mrig rtools list\u{1b}[39m lists the installed Rtools versions. \u{1b}[32mrig rtools add\u{1b}[39m\n  installs Rtools, by default every version needed by the currently installed\n  R versions. \u{1b}[32mrig rtools rm\u{1b}[39m removes Rtools versions.\n\n  On non-Windows platforms this command does nothing and is hidden.";
 const ABOUT_RUN: &str = "Run R, an R script or an R project";
-const HELP_RUN: &str = "\u{1b}[1m\u{1b}[34mDescription:\u{1b}[39m\u{1b}[22m\n  Run R, an R script or an R project, using the selected R version.\n\n  All of these examples allow an \u{1b}[32m--r-version\u{1b}[39m argument, to use a specific R\n  version.\n\n  rig run                    # start R\n  rig run <script.R>         # run an R script\n  rig run -f <script-file>   # run an R script\n  rig run -e <expression>    # evaluate an R expression\n  rig run <pkg>::<script>    # run a script from a package's exec directory\n  rig run <name>             # run a script the project declares\n  rig run --list             # list the scripts the project declares\n  rig run <path-to-app>      # run an R app\n  rig run --cmd <command>    # run `R CMD <command>`\n  rig run --activate         # start R with the selected version on PATH\n  rig run --shell            # start a shell with the selected version on PATH\n  rig run --rscript ...      # run `Rscript` instead of `R`\n  rig run -- --vanilla       # pass flags to R/Rscript\n\n\u{1b}[1m\u{1b}[34mSupported apps:\u{1b}[39m\u{1b}[22m\n  Currently supported apps are:\n\n  - Plumber APIs,\n  - Shiny apps,\n  - Quarto documents embedding Shiny apps,\n  - Quarto documents,\n  - Rmd documents,\n  - Rmd documents embedding Shiny apps,\n  - Static web sites.\n\n\u{1b}[1m\u{1b}[34mR arguments:\u{1b}[39m\u{1b}[22m\n  Anything after a literal \u{1b}[32m--\u{1b}[39m is passed straight to the R (or \u{1b}[32mRscript\u{1b}[39m)\n  process as its own command-line flags, e.g. \u{1b}[32mrig run -- --vanilla\u{1b}[39m.\n\n  Plain \u{1b}[32mrig run\u{1b}[39m (no \u{1b}[32m-e\u{1b}[39m/\u{1b}[32m-f\u{1b}[39m/app/\u{1b}[32m--cmd\u{1b}[39m) defaults to\n  \u{1b}[32m--no-save --no-restore\u{1b}[39m, so it never shows the \"Save workspace image?\"\n  prompt on exit. Override with \u{1b}[32mrig run -- --save --restore\u{1b}[39m.\n\n\u{1b}[1m\u{1b}[34mProjects:\u{1b}[39m\u{1b}[22m\n  If the current directory is inside a project, then \u{1b}[32mrig run\u{1b}[39m uses\n  the project's own environment instead of the default R version: it runs\n  \u{1b}[32m.rvenv/bin/R\u{1b}[39m. It also runs \u{1b}[32mrig proj lock\u{1b}[39m and \u{1b}[32mrig proj sync\u{1b}[39m as needed.\n\n  Use \u{1b}[32m--no-project\u{1b}[39m to ignore a project, or \u{1b}[32m--r-version\u{1b}[39m to select an R\n  version directly.\n\n\u{1b}[1m\u{1b}[34mScripts with inline dependencies:\u{1b}[39m\u{1b}[22m\n  \u{1b}[32mrig run -f script.R\u{1b}[39m runs an R script (the \u{1b}[32m-f\u{1b}[39m can be omitted). A\n  script can declare the packages and the R version it needs in a comment\n  block at its top, so it runs anywhere without a project:\n\n  # /// script\n  # [dependencies]\n  # R = \">= 4.4\"\n  # cli = \"*\"\n  # dplyr = \">= 1.1\"\n  #\n  # [tool.rig]\n  # exclude-newer = \"2026-06-01\"\n  # ///\n  library(dplyr)\n\n  The block starts with a \u{1b}[32m# /// script\u{1b}[39m line and ends with a \u{1b}[32m# ///\u{1b}[39m line.\n  In between, every line is a comment, and without the leading \u{1b}[32m#\u{1b}[39m they form\n  a TOML document. The block takes the \u{1b}[32m[dependencies]\u{1b}[39m, \u{1b}[32m[[repository]]\u{1b}[39m and\n  \u{1b}[32m[tool.rig]\u{1b}[39m tables of \u{1b}[32mrproj.toml\u{1b}[39m, with the same meaning.\n\n  rig creates an environment for the script in its cache directory, and runs\n  the script there, isolated from your own package library. It picks an\n  installed R version that fits the \u{1b}[32mR\u{1b}[39m requirement, or installs one, then\n  locks and installs the packages, the same way \u{1b}[32mrig proj sync\u{1b}[39m does for a\n  project. Later runs reuse the environment. Scripts with the same block\n  share one environment, and changing the block creates a new one. A script\n  with a block always uses its own environment, even inside a project.\n  \u{1b}[32m--r-version\u{1b}[39m selects the R version, which must fit the \u{1b}[32mR\u{1b}[39m requirement.\n\n  \u{1b}[32mrig cache clean --category scripts\u{1b}[39m deletes all script environments. A\n  script can start with \u{1b}[32m#!/usr/bin/env -S rig run\u{1b}[39m, to run it directly.\n\n\u{1b}[1m\u{1b}[34mProject scripts:\u{1b}[39m\u{1b}[22m\n  A project can give its own scripts a name, in the \u{1b}[32m[[bin]]\u{1b}[39m tables of its\n  \u{1b}[32mrproj.toml\u{1b}[39m:\n\n  [[bin]]\n  name = \"report\"\n  path = \"scripts/report.R\"\n  description = \"Build the report\"\n\n  \u{1b}[32mrig run report --format pdf\u{1b}[39m then runs \u{1b}[32mscripts/report.R\u{1b}[39m in the project's\n  environment, and passes \u{1b}[32m--format pdf\u{1b}[39m on to the script, where\n  \u{1b}[32mcommandArgs(TRUE)\u{1b}[39m picks it up. \u{1b}[32mpath\u{1b}[39m is relative to the project directory,\n  so a declared script works the same from anywhere within the project.\n  \u{1b}[32mrig run --list\u{1b}[39m lists the declared scripts, and \u{1b}[32m--json\u{1b}[39m prints them as JSON.\n\n  A declared name wins over a directory of the same name. Arguments that look\n  like a path rather than a name are never script names: anything containing\n  a slash or \u{1b}[32m::\u{1b}[39m, anything ending in \u{1b}[32m.R\u{1b}[39m, \u{1b}[32m.r\u{1b}[39m, \u{1b}[32m.Rmd\u{1b}[39m or \u{1b}[32m.qmd\u{1b}[39m, and \u{1b}[32m.\u{1b}[39m and \u{1b}[32m..\u{1b}[39m. Use\n  \u{1b}[32m./name\u{1b}[39m to run an app in a directory whose name a script has taken.\n\n\u{1b}[1m\u{1b}[34mActivation:\u{1b}[39m\u{1b}[22m\n  \u{1b}[32mrig run --activate\u{1b}[39m puts the selected R version's \u{1b}[32mbin\u{1b}[39m directory on\n  \u{1b}[32mPATH\u{1b}[39m for the R process it starts. \u{1b}[32m--shell\u{1b}[39m starts a shell instead of R,\n  with the same \u{1b}[32mPATH\u{1b}[39m change, so \u{1b}[32mR\u{1b}[39m and its subprocesses start the\n  activated R version.\n\n  Inside a project, both flags put the project's \u{1b}[32m.rvenv/bin\u{1b}[39m on\n  \u{1b}[32mPATH\u{1b}[39m rather than the raw R installation, so a nested \u{1b}[32mR\u{1b}[39m (started from\n  the shell \u{1b}[32m--shell\u{1b}[39m opens, or from R itself) picks up the project's package\n  library and repositories too, not just its version.\n\n\u{1b}[1m\u{1b}[34mRscript:\u{1b}[39m\u{1b}[22m\n  \u{1b}[32mrig run --rscript\u{1b}[39m runs the selected R version's \u{1b}[32mRscript\u{1b}[39m instead of \u{1b}[32mR\u{1b}[39m.\n  Unlike \u{1b}[32mR -e\u{1b}[39m/\u{1b}[32mR -f\u{1b}[39m, \u{1b}[32mRscript\u{1b}[39m never echoes back the code it runs, which\n  fits scripts and pipelines better than \u{1b}[32mR\u{1b}[39m's interactive-style echo.\n\n  \u{1b}[32m--rscript\u{1b}[39m works with \u{1b}[32m-e\u{1b}[39m/\u{1b}[32m-f\u{1b}[39m, scripts, project scripts, apps and \u{1b}[32m--activate\u{1b}[39m,\n  but not with \u{1b}[32m--cmd\u{1b}[39m (\u{1b}[32mR CMD\u{1b}[39m only exists as part of the \u{1b}[32mR\u{1b}[39m front-end) or\n  \u{1b}[32m--shell\u{1b}[39m (which never runs the R binary at all).";
+const HELP_RUN: &str = "\u{1b}[1m\u{1b}[34mDescription:\u{1b}[39m\u{1b}[22m\n  Run R, an R script or an R project, using the selected R version.\n\n  All of these examples allow an \u{1b}[32m--r-version\u{1b}[39m argument, to use a specific R\n  version.\n\n  rig run                    # start R\n  rig run <script.R>         # run an R script\n  rig run -f <script-file>   # run an R script\n  rig run -e <expression>    # evaluate an R expression\n  rig run <pkg>::<script>    # run a script from a package's exec directory\n  rig run <name>             # run a script the project declares\n  rig run --list             # list the scripts the project declares\n  rig run <path-to-app>      # run an R app\n  rig run --cmd <command>    # run `R CMD <command>`\n  rig run --activate         # start R with the selected version on PATH\n  rig run --shell            # start a shell with the selected version on PATH\n  rig run --rscript ...      # run `Rscript` instead of `R`\n  rig run -- --vanilla       # pass flags to R/Rscript\n\n\u{1b}[1m\u{1b}[34mSupported apps:\u{1b}[39m\u{1b}[22m\n  Currently supported apps are:\n\n  - Plumber APIs,\n  - Shiny apps,\n  - Quarto documents embedding Shiny apps,\n  - Quarto documents,\n  - Rmd documents,\n  - Rmd documents embedding Shiny apps,\n  - Static web sites.\n\n\u{1b}[1m\u{1b}[34mR arguments:\u{1b}[39m\u{1b}[22m\n  Anything after a literal \u{1b}[32m--\u{1b}[39m is passed straight to the R (or \u{1b}[32mRscript\u{1b}[39m)\n  process as its own command-line flags, e.g. \u{1b}[32mrig run -- --vanilla\u{1b}[39m.\n  This does not work for R scripts: everything after a script goes to the\n  script, see \"Scripts\" below.\n\n  Plain \u{1b}[32mrig run\u{1b}[39m (no \u{1b}[32m-e\u{1b}[39m/\u{1b}[32m-f\u{1b}[39m/app/\u{1b}[32m--cmd\u{1b}[39m) defaults to\n  \u{1b}[32m--no-save --no-restore\u{1b}[39m, so it never shows the \"Save workspace image?\"\n  prompt on exit. Override with \u{1b}[32mrig run -- --save --restore\u{1b}[39m.\n\n\u{1b}[1m\u{1b}[34mProjects:\u{1b}[39m\u{1b}[22m\n  If the current directory is inside a project, then \u{1b}[32mrig run\u{1b}[39m uses\n  the project's own environment instead of the default R version: it runs\n  \u{1b}[32m.rvenv/bin/R\u{1b}[39m. It also runs \u{1b}[32mrig proj lock\u{1b}[39m and \u{1b}[32mrig proj sync\u{1b}[39m as needed.\n\n  Use \u{1b}[32m--no-project\u{1b}[39m to ignore a project, or \u{1b}[32m--r-version\u{1b}[39m to select an R\n  version directly.\n\n\u{1b}[1m\u{1b}[34mScripts:\u{1b}[39m\u{1b}[22m\n  \u{1b}[32mrig run <script.R> [args...]\u{1b}[39m and \u{1b}[32mrig run -f <script> [args...]\u{1b}[39m pass\n  every argument after the script on to the script, unchanged, where\n  \u{1b}[32mcommandArgs(TRUE)\u{1b}[39m picks them up. This includes arguments that look like\n  rig's own flags, and \u{1b}[32m--\u{1b}[39m. rig's own flags go before the script:\n  \u{1b}[32mrig run -r 4.5 script.R --verbose\u{1b}[39m.\n\n  A script can start with a \u{1b}[32m#!/usr/bin/env -S rig run\u{1b}[39m line, and then you\n  can run it directly, after making it executable with \u{1b}[32mchmod +x\u{1b}[39m. A file\n  that starts with \u{1b}[32m#!\u{1b}[39m is a script for \u{1b}[32mrig run\u{1b}[39m, whatever its name, so\n  the script does not need an \u{1b}[32m.R\u{1b}[39m extension.\n\n\u{1b}[1m\u{1b}[34mScripts with inline dependencies:\u{1b}[39m\u{1b}[22m\n  \u{1b}[32mrig run -f script.R\u{1b}[39m runs an R script (the \u{1b}[32m-f\u{1b}[39m can be omitted). A\n  script can declare the packages and the R version it needs in a comment\n  block at its top, so it runs anywhere without a project:\n\n  # /// script\n  # [dependencies]\n  # R = \">= 4.4\"\n  # cli = \"*\"\n  # dplyr = \">= 1.1\"\n  #\n  # [tool.rig]\n  # exclude-newer = \"2026-06-01\"\n  # ///\n  library(dplyr)\n\n  The block starts with a \u{1b}[32m# /// script\u{1b}[39m line and ends with a \u{1b}[32m# ///\u{1b}[39m line.\n  In between, every line is a comment, and without the leading \u{1b}[32m#\u{1b}[39m they form\n  a TOML document. The block takes the \u{1b}[32m[dependencies]\u{1b}[39m, \u{1b}[32m[[repository]]\u{1b}[39m and\n  \u{1b}[32m[tool.rig]\u{1b}[39m tables of \u{1b}[32mrproj.toml\u{1b}[39m, with the same meaning.\n\n  rig creates an environment for the script in its cache directory, and runs\n  the script there, isolated from your own package library. It picks an\n  installed R version that fits the \u{1b}[32mR\u{1b}[39m requirement, or installs one, then\n  locks and installs the packages, the same way \u{1b}[32mrig proj sync\u{1b}[39m does for a\n  project. Later runs reuse the environment. Scripts with the same block\n  share one environment, and changing the block creates a new one. A script\n  with a block always uses its own environment, even inside a project.\n  \u{1b}[32m--r-version\u{1b}[39m selects the R version, which must fit the \u{1b}[32mR\u{1b}[39m requirement.\n\n  \u{1b}[32mrig cache clean --category scripts\u{1b}[39m deletes all script environments.\n\n\u{1b}[1m\u{1b}[34mProject scripts:\u{1b}[39m\u{1b}[22m\n  A project can give its own scripts a name, in the \u{1b}[32m[[bin]]\u{1b}[39m tables of its\n  \u{1b}[32mrproj.toml\u{1b}[39m:\n\n  [[bin]]\n  name = \"report\"\n  path = \"scripts/report.R\"\n  description = \"Build the report\"\n\n  \u{1b}[32mrig run report --format pdf\u{1b}[39m then runs \u{1b}[32mscripts/report.R\u{1b}[39m in the project's\n  environment, and passes \u{1b}[32m--format pdf\u{1b}[39m on to the script, where\n  \u{1b}[32mcommandArgs(TRUE)\u{1b}[39m picks it up. \u{1b}[32mpath\u{1b}[39m is relative to the project directory,\n  so a declared script works the same from anywhere within the project.\n  \u{1b}[32mrig run --list\u{1b}[39m lists the declared scripts, and \u{1b}[32m--json\u{1b}[39m prints them as JSON.\n\n  A declared name wins over a directory of the same name. Arguments that look\n  like a path rather than a name are never script names: anything containing\n  a slash or \u{1b}[32m::\u{1b}[39m, anything ending in \u{1b}[32m.R\u{1b}[39m, \u{1b}[32m.r\u{1b}[39m, \u{1b}[32m.Rmd\u{1b}[39m or \u{1b}[32m.qmd\u{1b}[39m, and \u{1b}[32m.\u{1b}[39m and \u{1b}[32m..\u{1b}[39m. Use\n  \u{1b}[32m./name\u{1b}[39m to run an app in a directory whose name a script has taken.\n\n\u{1b}[1m\u{1b}[34mActivation:\u{1b}[39m\u{1b}[22m\n  \u{1b}[32mrig run --activate\u{1b}[39m puts the selected R version's \u{1b}[32mbin\u{1b}[39m directory on\n  \u{1b}[32mPATH\u{1b}[39m for the R process it starts. \u{1b}[32m--shell\u{1b}[39m starts a shell instead of R,\n  with the same \u{1b}[32mPATH\u{1b}[39m change, so \u{1b}[32mR\u{1b}[39m and its subprocesses start the\n  activated R version.\n\n  Inside a project, both flags put the project's \u{1b}[32m.rvenv/bin\u{1b}[39m on\n  \u{1b}[32mPATH\u{1b}[39m rather than the raw R installation, so a nested \u{1b}[32mR\u{1b}[39m (started from\n  the shell \u{1b}[32m--shell\u{1b}[39m opens, or from R itself) picks up the project's package\n  library and repositories too, not just its version.\n\n\u{1b}[1m\u{1b}[34mRscript:\u{1b}[39m\u{1b}[22m\n  \u{1b}[32mrig run --rscript\u{1b}[39m runs the selected R version's \u{1b}[32mRscript\u{1b}[39m instead of \u{1b}[32mR\u{1b}[39m.\n  Unlike \u{1b}[32mR -e\u{1b}[39m/\u{1b}[32mR -f\u{1b}[39m, \u{1b}[32mRscript\u{1b}[39m never echoes back the code it runs, which\n  fits scripts and pipelines better than \u{1b}[32mR\u{1b}[39m's interactive-style echo.\n\n  \u{1b}[32m--rscript\u{1b}[39m works with \u{1b}[32m-e\u{1b}[39m/\u{1b}[32m-f\u{1b}[39m, scripts, project scripts, apps and \u{1b}[32m--activate\u{1b}[39m,\n  but not with \u{1b}[32m--cmd\u{1b}[39m (\u{1b}[32mR CMD\u{1b}[39m only exists as part of the \u{1b}[32mR\u{1b}[39m front-end) or\n  \u{1b}[32m--shell\u{1b}[39m (which never runs the R binary at all).";
 const ABOUT_SELF_UNINSTALL: &str = "Remove the rig installation";
 const HELP_SELF_UNINSTALL: &str = "\u{1b}[1m\u{1b}[34mDescription:\u{1b}[39m\u{1b}[22m\n  Removes the \u{1b}[32mrig\u{1b}[39m binary, its shell completions, and the PATH entry the\n  install script added, then deletes itself.\n\n  This only works if rig was installed with the install script (\u{1b}[32minstall.sh\u{1b}[39m\n  on macOS/Linux, \u{1b}[32minstall.ps1\u{1b}[39m on Windows).\n\n  \u{1b}[32mrig self uninstall\u{1b}[39m only removes rig itself. It does not remove rig's\n  configuration, its download/build cache, or any R version it installed.\n  Use \u{1b}[32mrig rm\u{1b}[39m to remove R version and \u{1b}[32mrig cache clean\u{1b}[39m to clean the cache.\n\n  Without \u{1b}[32m--force\u{1b}[39m, it only prints what it would remove. Use \u{1b}[32m--dry-run\u{1b}[39m for\n  the same preview, or \u{1b}[32m--force\u{1b}[39m to actually remove rig.";
 const ABOUT_SELF_UPDATE: &str = "Update rig to the latest release";
diff --git a/src/help/run.md b/src/help/run.md
index 72f26c53..60154748 100644
--- a/src/help/run.md
+++ b/src/help/run.md
@@ -39,6 +39,8 @@ Currently supported apps are:
 
 Anything after a literal `--` is passed straight to the R (or `Rscript`)
 process as its own command-line flags, e.g. `rig run -- --vanilla`.
+This does not work for R scripts: everything after a script goes to the
+script, see "Scripts" below.
 
 Plain `rig run` (no `-e`/`-f`/app/`--cmd`) defaults to
 `--no-save --no-restore`, so it never shows the "Save workspace image?"
@@ -53,6 +55,19 @@ the project's own environment instead of the default R version: it runs
 Use `--no-project` to ignore a project, or `--r-version` to select an R
 version directly.
 
+## Scripts
+
+`rig run <script.R> [args...]` and `rig run -f <script> [args...]` pass
+every argument after the script on to the script, unchanged, where
+`commandArgs(TRUE)` picks them up. This includes arguments that look like
+rig's own flags, and `--`. rig's own flags go before the script:
+`rig run -r 4.5 script.R --verbose`.
+
+A script can start with a `#!/usr/bin/env -S rig run` line, and then you
+can run it directly, after making it executable with `chmod +x`. A file
+that starts with `#!` is a script for `rig run`, whatever its name, so
+the script does not need an `.R` extension.
+
 ## Scripts with inline dependencies
 
 `rig run -f script.R` runs an R script (the `-f` can be omitted). A
@@ -86,8 +101,7 @@ share one environment, and changing the block creates a new one. A script
 with a block always uses its own environment, even inside a project.
 `--r-version` selects the R version, which must fit the `R` requirement.
 
-`rig cache clean --category scripts` deletes all script environments. A
-script can start with `#!/usr/bin/env -S rig run`, to run it directly.
+`rig cache clean --category scripts` deletes all script environments.
 
 ## Project scripts
 
diff --git a/src/scrun.rs b/src/scrun.rs
index 04201d8e..4750db2f 100644
--- a/src/scrun.rs
+++ b/src/scrun.rs
@@ -9,6 +9,7 @@ use log::{error, info, trace, warn};
 use regex::Regex;
 use simple_error::*;
 
+use crate::args::is_r_script_file;
 use crate::common::*;
 use crate::output::OUTPUT;
 use crate::proj::{proj_read_manifest_opt, proj_sync, ProjSyncOptions};
@@ -392,15 +393,6 @@ fn project_r_binary(args: &ArgMatches, dry_run: bool) -> Result<Option<String>,
 // anything other than the file `report.R` would be a bad surprise.
 const NOT_BIN_NAME_EXTENSIONS: [&str; 4] = [".R", ".r", ".Rmd", ".qmd"];
 
-/// Whether `arg` is an existing `.R` file, which `rig run <arg>` runs as a
-/// script, same as `rig run -f <arg>`.
-fn is_r_script_file(arg: &str) -> bool {
-    let path = Path::new(arg);
-    path.extension()
-        .is_some_and(|ext| ext.eq_ignore_ascii_case("r"))
-        && path.is_file()
-}
-
 /// Whether `arg` can name a `[[bin]]` in `rproj.toml`. Anything that looks
 /// like a path or like a package script is not a name, so a declared script
 /// can never shadow the `rig run <path-to-app>` and `rig run <pkg>::<script>`
@@ -1239,24 +1231,6 @@ mod tests {
         assert_eq!(got, OsString::from(format!("/opt/R/4.4.1/bin{}", sep)));
     }
 
-    #[test]
-    fn test_is_r_script_file() {
-        let dir = tempfile::tempdir().unwrap();
-        let upper = dir.path().join("a.R");
-        let lower = dir.path().join("b.r");
-        let other = dir.path().join("c.Rmd");
-        for f in [&upper, &lower, &other] {
-            std::fs::write(f, "1\n").unwrap();
-        }
-        assert!(is_r_script_file(upper.to_str().unwrap()));
-        assert!(is_r_script_file(lower.to_str().unwrap()));
-        assert!(!is_r_script_file(other.to_str().unwrap()));
-        assert!(!is_r_script_file(
-            dir.path().join("missing.R").to_str().unwrap()
-        ));
-        assert!(!is_r_script_file(dir.path().to_str().unwrap()));
-    }
-
     #[test]
     fn test_is_bin_name() {
         for name in ["report", "build-site", "check_all", "r2d2"] {
diff --git a/tests/test-linux.sh b/tests/test-linux.sh
index 9702d960..4218b765 100644
--- a/tests/test-linux.sh
+++ b/tests/test-linux.sh
@@ -389,6 +389,14 @@ teardown() {
     [[ "$status" -eq 0 ]]
     echo "$output" | grep -q "^a b"
 
+    # a script with a #! line can have any name, and gets all arguments
+    # after it, even the ones that look like flags
+    printf '#!/usr/bin/env -S rig run\ncat(commandArgs(TRUE), "\\n")\n' > shebang
+    chmod +x shebang
+    run ./shebang --foo -- bar --help
+    [[ "$status" -eq 0 ]]
+    echo "$output" | grep -q -- "^--foo -- bar --help"
+
     cat > deps.R <<'SCRIPT'
 # /// script
 # [dependencies]
diff --git a/tests/test-macos.sh b/tests/test-macos.sh
index 2d6b279b..45bfe21a 100644
--- a/tests/test-macos.sh
+++ b/tests/test-macos.sh
@@ -518,6 +518,14 @@ teardown() {
     [[ "$status" -eq 0 ]]
     echo "$output" | grep -q "^a b"
 
+    # a script with a #! line can have any name, and gets all arguments
+    # after it, even the ones that look like flags
+    printf '#!/usr/bin/env -S rig run\ncat(commandArgs(TRUE), "\\n")\n' > shebang
+    chmod +x shebang
+    run ./shebang --foo -- bar --help
+    [[ "$status" -eq 0 ]]
+    echo "$output" | grep -q -- "^--foo -- bar --help"
+
     cat > deps.R <<'SCRIPT'
 # /// script
 # [dependencies]