From a983ec713feef13f82a60b981103b3bc94db8085 Mon Sep 17 00:00:00 2001
From: Colin McDonnell <colinmcd94@gmail.com>
Date: Thu, 14 Sep 2023 15:30:14 -0700
Subject: Improve run.md

---
 docs/cli/run.md | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

(limited to 'docs/cli/run.md')

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:
-- 
cgit v1.2.3