Improve run.md

1 files changed, 17 insertions, 1 deletions

diff --git a/docs/cli/run.md b/docs/cli/run.md
index dcd7edd52..6d490e8da 100644
--- a/docs/cli/run.md
+++ b/docs/cli/run.md
@@ -67,7 +67,7 @@ Your `package.json` can define a number of named `"scripts"` that correspond to
 }
 ```
 
-Use `bun <script>` to execute these scripts.
+Use `bun <script>` or `bun run <script>` to execute these scripts.
 
 ```bash
 $ bun clean
@@ -105,6 +105,22 @@ quickstart scripts:
 
 Bun respects lifecycle hooks. For instance, `bun run clean` will execute `preclean` and `postclean`, if defined. If the `pre<script>` fails, Bun will not execute the script itself.
 
+### `--bun`
+
+It's common for `package.json` scripts to reference locally-installed CLIs like `vite` or `next`. These CLIs are often JavaScript files marked with a [shebang](<https://en.wikipedia.org/wiki/Shebang_(Unix)>) to indicate that they should be executed with `node`.
+
+```js
+#!/usr/bin/env node
+
+// do stuff
+```
+
+By default, Bun respects this shebang and executes the script with `node`. However, you can override this behavior with the `--bun` flag. For Node.js-based CLIs, this will run the CLI with Bun instead of Node.js.
+
+```bash
+$ bun run --bun vite
+```
+
 ## Environment variables
 
 Bun automatically loads environment variables from `.env` files before running a file, script, or executable. The following files are checked, in order: