run: add npm's --workspace flag and use it for a script's npm run -w

docs/guides/install/from-npm-install-to-bun-install.mdx

@@ -82,6 +82,12 @@ bun --filter 'lib-*' my-script
 # npm run --workspace lib-foo --workspace lib-bar my-script
 ```
 
+`bun run` also takes npm's `-w` / `--workspace` flag, with a package name or a folder. Put the flag before the script name:
+
+```sh terminal icon="terminal"
+bun run --workspace lib-foo --workspace lib-bar my-script
+```
+
 ---
 
 ## Update dependencies

docs/pm/filter.mdx

@@ -142,7 +142,7 @@ bun run --filter foo myscript
 
 ### Parallel and sequential mode
 
-Combine `--filter` or `--workspaces` with `--parallel` or `--sequential` to run scripts across workspace packages with Foreman-style prefixed output:
+Combine `--filter`, `--workspace` or `--workspaces` with `--parallel` or `--sequential` to run scripts across workspace packages with Foreman-style prefixed output:
 
 ```bash terminal icon="terminal"
 # Run "build" in all matching packages concurrently
@@ -161,9 +161,9 @@ bun run --parallel --no-exit-on-error --filter '*' test
 bun run --parallel --filter '*' build lint
 ```
 
-Bun prefixes each line of output with the package and script name (`pkg-a:build | ...`). Without `--filter`/`--workspaces`, the prefix is only the script name (`build | ...`). When a package's `package.json` has no `name` field, Bun uses the relative path from the workspace root instead.
+Bun prefixes each line of output with the package and script name (`pkg-a:build | ...`). Without a flag that selects packages (`--filter`, `--workspace`, `--workspaces`), the prefix is only the script name (`build | ...`). When a package's `package.json` has no `name` field, Bun uses the relative path from the workspace root instead.
 
-Use `--if-present` with `--workspaces` to skip packages that don't have the requested script instead of erroring.
+Use `--if-present` with `--workspace` or `--workspaces` to skip packages that don't have the requested script instead of erroring.
 
 ### Dependency Order
 

docs/runtime/index.mdx

@@ -162,6 +162,26 @@ executes `<script>` in both `bar` and `baz`, but not in `foo`.
 
 See [`--filter`](/pm/filter#running-scripts-with-filter).
 
+### npm's `--workspace`
+
+`bun run` also takes npm's `-w` / `--workspace <value>` flag. Bun matches the value against the workspace packages as npm does. The value is the name of a package, the path of its folder, or the path of a folder that holds packages:
+
+```bash terminal icon="terminal"
+# the package named "api" and the package in the folder ./api
+bun run --workspace api build
+
+# every workspace package directly inside ./packages
+bun run -w packages build
+```
+
+Put the flag before the script name, like `--filter`. npm's `npm run build -w api` is `bun run -w api build`. Bun passes the words after the script name to the script, so `bun run build -w api` gives `-w api` to the `build` script of the current package.
+
+- A name must match exactly, because the value is not a pattern. A package without a `name` is selected by its path.
+- With several `--workspace` flags, the packages run one after another, in the order of the flags.
+- If a selected package does not have the script, the run fails before a script starts. Pass `--if-present` to skip that package.
+- `--workspace` combines with `--filter` like one more positive pattern. `--workspaces` adds no packages to the ones that `--workspace` selects.
+- Bun finds the workspace root and its packages as it does for `--filter`.
+
 ## `bun run -` to pipe code from stdin
 
 `bun run -` reads JavaScript, TypeScript, TSX, or JSX from stdin and executes it without writing to a temporary file first.

docs/snippets/cli/run.mdx

@@ -36,6 +36,10 @@ bun run <file or script>
   Run a script in all workspace packages matching the pattern. Alias: <code>-F</code>
 </ParamField>
 
+<ParamField path="--workspace" type="string">
+  Run a script in the workspace packages with this name or in this folder, as in npm. Alias: <code>-w</code>
+</ParamField>
+
 <ParamField path="--workspaces" type="boolean">
   Run a script in all workspace packages (from the <code>workspaces</code> field in <code>package.json</code>)
 </ParamField>

src/clap/comptime.rs

@@ -547,6 +547,7 @@ impl<Id> ComptimeClap<Id> {
             unknown_long_flags_are_positional: opt.unknown_long_flags_are_positional,
             unknown_long_flags_are_errors: opt.unknown_long_flags_are_errors,
             ignored_long_flags: opt.ignored_long_flags,
+            param_rules: opt.param_rules,
         };
 
         while let Some(arg) = stream.next()? {

src/clap/lib.rs

@@ -388,6 +388,17 @@ pub struct ParseOptions<'a> {
     /// command.
     pub unknown_long_flags_are_errors: bool,
     pub ignored_long_flags: IgnoredLongFlags,
+    /// Rules of this parse for params of the table, each named by its long name without the dashes.
+    pub param_rules: &'static [(&'static [u8], ParamRule)],
+}
+
+/// How one command reads a param of a table that it shares with other commands.
+#[derive(Clone, Copy, PartialEq, Eq)]
+pub enum ParamRule {
+    /// The command does not have the param. Its flags are read like the flags of no param.
+    Absent,
+    /// The short flag takes no glued value: `-w client` and `-w=client` parse, `-wclient` fails.
+    SeparateValue,
 }
 
 /// Long flags, written without the dashes, that are skipped instead of failing the parse when
@@ -492,6 +503,7 @@ pub fn parse<Id: 'static>(
             unknown_long_flags_are_positional: opt.unknown_long_flags_are_positional,
             unknown_long_flags_are_errors: opt.unknown_long_flags_are_errors,
             ignored_long_flags: opt.ignored_long_flags,
+            param_rules: opt.param_rules,
         },
     )?;
     Ok(Args { clap })
@@ -515,6 +527,7 @@ pub fn parse_with_table<Id: 'static>(
             unknown_long_flags_are_positional: opt.unknown_long_flags_are_positional,
             unknown_long_flags_are_errors: opt.unknown_long_flags_are_errors,
             ignored_long_flags: opt.ignored_long_flags,
+            param_rules: opt.param_rules,
         },
     )?;
     Ok(Args { clap })

src/clap/streaming.rs

@@ -66,6 +66,7 @@ pub struct StreamingClap<'p, 'a, Id, ArgIterator> {
     pub(crate) unknown_long_flags_are_positional: bool,
     pub(crate) unknown_long_flags_are_errors: bool,
     pub(crate) ignored_long_flags: clap::IgnoredLongFlags,
+    pub(crate) param_rules: &'static [(&'static [u8], clap::ParamRule)],
 }
 
 // ArgIterator is the
@@ -116,7 +117,7 @@ where
                 // Copy the slice ref so `&mut self` is free inside the loop.
                 let params = self.params;
                 for param in params {
-                    if !param.names.matches_long(name) {
+                    if !param.names.matches_long(name) || self.is_absent(param) {
                         continue;
                     }
 
@@ -254,7 +255,7 @@ where
             let Some(short) = param.names.short else {
                 continue;
             };
-            if short != arg[index] {
+            if short != arg[index] || self.is_absent(param) {
                 continue;
             }
 
@@ -306,6 +307,11 @@ where
                 }));
             }
 
+            if self.rule_of(param) == Some(clap::ParamRule::SeparateValue) {
+                let word = [b"-".as_slice(), arg].concat();
+                return Err(self.err(&word, None, None, ArgError::InvalidArgument));
+            }
+
             return Ok(Some(Arg {
                 param,
                 value: Some(&arg[next_index..]),
@@ -373,7 +379,7 @@ where
                 if !self
                     .params
                     .iter()
-                    .any(|param| param.names.matches_long(name))
+                    .any(|param| param.names.matches_long(name) && !self.is_absent(param))
                 {
                     return Ok(Some(ArgInfo {
                         arg: full_arg,
@@ -399,6 +405,15 @@ where
         }))
     }
 
+    fn rule_of(&self, param: &clap::Param<Id>) -> Option<clap::ParamRule> {
+        let long = param.names.long?;
+        (self.param_rules.iter()).find_map(|(name, rule)| (*name == long).then_some(*rule))
+    }
+
+    fn is_absent(&self, param: &clap::Param<Id>) -> bool {
+        self.rule_of(param) == Some(clap::ParamRule::Absent)
+    }
+
     fn err(&mut self, arg: &[u8], short: Option<u8>, long: Option<&[u8]>, e: ArgError) -> ArgError {
         if let Some(d) = self.diagnostic.as_deref_mut() {
             // `Diagnostic` owns
@@ -429,6 +444,7 @@ mod tests {
             unknown_long_flags_are_positional: false,
             unknown_long_flags_are_errors: false,
             ignored_long_flags: Default::default(),
+            param_rules: &[],
             params,
             iter: &mut iter,
             state: State::Normal,
@@ -465,6 +481,7 @@ mod tests {
             unknown_long_flags_are_positional: false,
             unknown_long_flags_are_errors: false,
             ignored_long_flags: Default::default(),
+            param_rules: &[],
             params,
             iter: &mut iter,
             state: State::Normal,
@@ -940,6 +957,7 @@ mod tests {
             unknown_long_flags_are_positional: true,
             unknown_long_flags_are_errors: false,
             ignored_long_flags: Default::default(),
+            param_rules: &[],
             params: &params,
             iter: &mut iter,
             state: State::Normal,
@@ -992,6 +1010,7 @@ mod tests {
             unknown_long_flags_are_positional: true,
             unknown_long_flags_are_errors: false,
             ignored_long_flags: Default::default(),
+            param_rules: &[],
             params: &params,
             iter: &mut iter,
             state: State::Normal,
@@ -1039,6 +1058,7 @@ mod tests {
                 unknown_long_flags_are_positional: false,
                 unknown_long_flags_are_errors: true,
                 ignored_long_flags: Default::default(),
+                param_rules: &[],
                 params: &params,
                 iter: &mut iter,
                 state: State::Normal,
@@ -1061,4 +1081,77 @@ mod tests {
         assert_eq!(parse(&[b"x", b"--q", b"y"]), Some(b"q".to_vec()));
         assert_eq!(parse(&[b"--q=1"]), Some(b"q".to_vec()));
     }
+
+    #[test]
+    fn param_rules() {
+        let params: [clap::Param<u8>; 2] = [
+            clap::Param {
+                id: 0,
+                names: clap::Names {
+                    short: Some(b'c'),
+                    long: Some(b"cc"),
+                    ..Default::default()
+                },
+                takes_value: clap::Values::One,
+                ..Default::default()
+            },
+            clap::Param {
+                id: 1,
+                takes_value: clap::Values::Many,
+                ..Default::default()
+            },
+        ];
+        // The values that the parse read, or the word that it refused.
+        let parse = |rule: clap::ParamRule, args: &[&[u8]]| {
+            let mut diag = clap::Diagnostic::default();
+            let mut iter = args::SliceIterator { remain: args };
+            let mut c = StreamingClap::<u8, args::SliceIterator> {
+                short_aliases: &[],
+                unknown_long_flags_are_positional: false,
+                unknown_long_flags_are_errors: false,
+                ignored_long_flags: Default::default(),
+                param_rules: match rule {
+                    clap::ParamRule::Absent => &[(b"cc", clap::ParamRule::Absent)],
+                    clap::ParamRule::SeparateValue => &[(b"cc", clap::ParamRule::SeparateValue)],
+                },
+                params: &params,
+                iter: &mut iter,
+                state: State::Normal,
+                positional: None,
+                diagnostic: Some(&mut diag),
+            };
+            let mut seen: Vec<(u8, Vec<u8>)> = Vec::new();
+            loop {
+                match c.next() {
+                    Ok(Some(arg)) => seen.push((arg.param.id, arg.value.unwrap().to_vec())),
+                    Ok(None) => return Ok(seen),
+                    Err(err) => {
+                        assert_eq!(err, ArgError::InvalidArgument);
+                        break;
+                    }
+                }
+            }
+            Err(match diag.short {
+                Some(short) => vec![b'-', short],
+                None => diag.arg,
+            })
+        };
+
+        let separate = clap::ParamRule::SeparateValue;
+        assert_eq!(
+            parse(separate, &[b"-c", b"x"]),
+            Ok(vec![(0, b"x".to_vec())])
+        );
+        assert_eq!(parse(separate, &[b"-c=x"]), Ok(vec![(0, b"x".to_vec())]));
+        assert_eq!(parse(separate, &[b"--cc=x"]), Ok(vec![(0, b"x".to_vec())]));
+        assert_eq!(parse(separate, &[b"-cx"]), Err(b"-cx".to_vec()));
+
+        // An absent param is like no param: the short flag is refused, the long flag is skipped.
+        let absent = clap::ParamRule::Absent;
+        assert_eq!(parse(absent, &[b"-c", b"x"]), Err(b"-c".to_vec()));
+        assert_eq!(
+            parse(absent, &[b"--cc", b"x"]),
+            Ok(vec![(1, b"x".to_vec())])
+        );
+    }
 }

src/install/PackageManager/workspace_selection.rs

@@ -61,7 +61,8 @@ struct Selector {
     base: Base,
 }
 
-fn strip_negations(raw: &[u8]) -> (&[u8], bool) {
+/// The pattern without its leading `!`s, and whether they negate it.
+pub fn strip_negations(raw: &[u8]) -> (&[u8], bool) {
     let mut remain = raw;
     let mut negated = false;
     while let Some(rest) = remain.strip_prefix(b"!") {

src/install/lifecycle_script_runner.rs

@@ -222,7 +222,12 @@ pub fn replace_package_manager_run(
             }
             b'p' => {
                 if delimiter > 0 {
-                    if strings::has_prefix_comptime(&script[start..], b"pnpm run ") {
+                    // pnpm's `-w` is `--workspace-root`. `bun run` has npm's `-w`, which takes a value.
+                    if strings::has_prefix_comptime(&script[start..], b"pnpm run ")
+                        && !strings::tokenize_any(&script[start + b"pnpm run ".len()..], b" \t")
+                            .take_while(|word| word[0] == b'-')
+                            .any(|word| word == b"-w")
+                    {
                         append_bun_run(copy_script);
                         copy_script.push(b' ');
                         entry_i += b"pnpm run ".len();
@@ -269,8 +274,9 @@ fn append_npm_run_in_workspaces(out: &mut Vec<u8>, args: &[u8]) -> usize {
     let mut selects_workspaces = false;
     let mut tokens = strings::tokenize_any(command, b" \t");
     while let Some(token) = tokens.next() {
-        let workspace = match token {
-            b"-w" | b"--workspace" => tokens.next(),
+        // The `=` stays: a shell expands `-w={a,b}` to two flags, and `-w {a,b}` to a value and a script name.
+        let (workspace, separator): (Option<&[u8]>, &[u8]) = match token {
+            b"-w" | b"--workspace" => (tokens.next(), b" "),
             b"--workspaces" | b"--ws" => {
                 selects_workspaces = true;
                 flags.extend_from_slice(b" --workspaces");
@@ -291,7 +297,7 @@ fn append_npm_run_in_workspaces(out: &mut Vec<u8>, args: &[u8]) -> usize {
                 .strip_prefix(b"--workspace=")
                 .or_else(|| token.strip_prefix(b"-w="))
             {
-                Some(workspace) => Some(workspace),
+                Some(workspace) => (Some(workspace), b"="),
                 None => {
                     rest.push(b' ');
                     rest.extend_from_slice(token);
@@ -308,12 +314,9 @@ fn append_npm_run_in_workspaces(out: &mut Vec<u8>, args: &[u8]) -> usize {
             return 0;
         };
         selects_workspaces = true;
-        flags.extend_from_slice(b" --filter=");
-        // npm also accepts the workspace's folder. `--filter` tells a path from a name by the
-        // leading dot.
-        if strings::contains_char(workspace, b'/') && !matches!(workspace[0], b'@' | b'.' | b'/') {
-            flags.extend_from_slice(b"./");
-        }
+        // The short flag: a `bun` in `PATH` from before the flag refuses `-w`, but skips `--workspace` and runs this package's script.
+        flags.extend_from_slice(b" -w");
+        flags.extend_from_slice(separator);
         flags.extend_from_slice(workspace);
     }
 

src/options_types/context.rs

@@ -35,7 +35,7 @@ pub struct ContextData {
     pub bundler_options: BundlerOptions,
     pub runtime_options: RuntimeOptions,
 
-    pub filters: Vec<Box<[u8]>>,
+    pub filters: Vec<PackageFilter>,
     pub workspaces: bool,
     pub if_present: bool,
     pub parallel: bool,
@@ -46,6 +46,23 @@ pub struct ContextData {
     pub has_loaded_global_config: bool,
 }
 
+/// Which workspace packages `bun run` runs a script in.
+pub enum PackageFilter {
+    /// `--filter <pattern>`
+    Pattern(Box<[u8]>),
+    /// `--workspace <value>`: a package's name, its folder or the parent of its folder, as in npm.
+    Workspace(Box<[u8]>),
+}
+
+impl PackageFilter {
+    /// The value as it was given.
+    pub fn text(&self) -> &[u8] {
+        match self {
+            PackageFilter::Pattern(text) | PackageFilter::Workspace(text) => text,
+        }
+    }
+}
+
 impl Default for ContextData {
     // ── Startup .text page-fault reduction ───────────────────────────────
     // `--version` perf showed `ContextData::default` (1 638 B) plus its