r — run-package-scripts

Fuzzy script picker for npm/pnpm/yarn/bun workspaces. Type r to browse and run any script across your entire monorepo — no need to remember package names, cd into subdirectories, or type pnpm --filter commands.

Install

Global install is recommended — r is an interactive tool meant to be used anywhere.

# pnpm or bun (recommended — PATH is configured automatically)
pnpm add -g @tigerbook/run-scripts
bun add -g @tigerbook/run-scripts

# npm
npm install -g @tigerbook/run-scripts

npm PATH note: If r is not found after npm install -g, run npm config get prefix to find the global bin directory and add <prefix>/bin to your PATH.

Requirements: Node >= 22 or Bun >= 1.0

Picker: Uses fzf when available (with command preview), otherwise falls back to the built-in interactive prompt — no extra setup needed.

Install fzf (optional, recommended)

# macOS
brew install fzf

# Linux
sudo apt install fzf

# Windows (winget)
winget install fzf

Quick start

cd your-project

r          # open picker — browse and run any script (fzf shows full command in preview)
r build    # filter to "build" scripts; runs directly if exactly one match
r api/dev  # run the "dev" script in the "api" workspace package

Usage

r                                # open picker with all scripts
r <query>                        # filter scripts; run directly if exactly one match
r <query> <args>                 # pass extra args through to the matched script
r -p <query>                     # print the resolved command instead of running it
r --list                         # list all available scripts, grouped by package
r --package-name <name> <query>  # scope the picker/query to a single package ("root" or a workspace package name)
r --help                         # show help

Before executing, r always prints the full command it will run:

Running: pnpm --filter @my/app run dev

Use -p / --print-command to resolve a script without executing it:

r -p build                # prints: pnpm --filter @my/app run build

Monorepo support

Scripts from all workspace packages are collected and prefixed by package name:

api/build       → "build" script in the "api" workspace
web/dev         → "dev" script in the "web" workspace
root/lint       → "lint" script at the repo root

In a single-package repo, scripts are listed without a prefix.

Use --list to print all available scripts without opening the picker, grouped by package:

$ r --list
root:
  lint

api:
  build
  dev

web:
  dev

In a single-package repo, --list prints a flat list without any prefix.

Scoping to a single package

Use --package-name <name> to limit the picker/query/--list to one package — either root or a workspace package's short name:

r --package-name api          # open picker with only "api" scripts
r --package-name api build    # run "build" in the "api" package directly
r --package-name root --list  # list only the root package.json scripts

rr — root scripts only

rr is a shortcut for r --package-name root, installed as its own command for running root-level scripts without typing the root/ prefix or --package-name root:

rr          # open picker with root scripts only
rr build    # run the root "build" script directly
rr --list   # list root scripts only

Fallback behavior

If the query matches no scripts, it is forwarded to the package manager as-is:

r tsc          # no script named "tsc" → runs: pnpm tsc
r -p tsc       # no script named "tsc" → prints: pnpm tsc
r add lodash   # → runs: pnpm add lodash

Auto-detection

r automatically detects the package manager by checking for lock files:

| Lock file | Package manager | | ------------------- | --------------- | | pnpm-lock.yaml | pnpm | | bun.lock | bun | | yarn.lock | yarn | | package-lock.json | npm |

Must be run from the project root (directory containing package.json).

Configuration

Config is stored in .bun-scripts/setting.toml (local) and ~/.bun-scripts/setting.toml (global). Local takes priority.

Initialize with r --init-config:

r --init-config          # create local .bun-scripts/setting.toml
r --init-config --global # create ~/.bun-scripts/setting.toml

Then edit the file directly — TOML supports comments, so each option is documented inline:

[run-scripts]
# Preferred picker: "fzf" (default, falls back to built-in if not on PATH) | "node" (always built-in)
picker = "fzf"

| Field | Values | Default | Description | | -------------------- | ------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- | | run-scripts.picker | "fzf" | "node" | "fzf" | Preferred picker. "fzf" falls back to the built-in prompt if fzf is not on PATH. "node" always uses the built-in prompt. |

License

MIT