package-scripts

package-scripts

CLI to interactively select and run package scripts using any package manager.

• Installation
• Usage
  • Arguments
  • Bypassing the selection prompt
  • Running the first matched script
  • Pass-through arguments
• Package Manager
  • Default package manager
  • Project's package manager

Installation

Step 1. Run the following command using npx from any directory.

npx package-scripts

Step 2. Follow the prompts to set up the command name and select your default package manager.

Step 3. Once the installation process is complete, add the following lines to your shell configuration file.

• For POSIX-compatible shells like bash or zsh

# ~/.bashrc or ~/.zshrc

if test -d ~/.package-scripts/bin; then
  export PATH=~/.package-scripts/bin:$PATH
fi

• For PowerShell

# C:\Program Files\PowerShell\7\profile.ps1

if (Test-Path -Path "$env:HOMEPATH\.package-scripts\bin") {
  $env:Path = "$env:HOMEPATH\.package-scripts\bin;$env:Path"
}

💡 To get the path of your PowerShell configuration file, type $PROFILE. and tab through the available options to choose the necessary profile.

Step 4. Restart your shell. The command should now be available.

How it works

The installation process creates a ~/.package-scripts directory where it installs the core library and creates a shell script that acts as the program's main entry point. The script's directory (bin) is added to your PATH, making the script accessible from anywhere in your shell. By giving the script a name that you prefer (or sticking to the default), you control how to invoke the program.

Renaming the command

You can rename the command later by providing the --rename option with the new command name. If the name is not provided, you will be prompted to enter one.

scripts --rename <new-name>

📚 All following examples will assume the command name is scripts

Usage

To interactively select and run a script in your current project, run the command you created during the installation. Calling without any arguments or options will display all scripts (except for lifecycle scripts). You can type in the selection menu to filter down your search.

For example:

scripts

{
  "scripts": {
    "prepack": "npm run build",
    "build": "npm run compile",
    "prebuild": "npm run ci && rimraf ./dist",
    "ci": "npm run check-style && npm run check-build",
    "check-style": "npm run format:check && npm run lint",
    "check-build": "npm run compile -- --noEmit",
    "format": "prettier --write \"*.{js,cjs,mjs,ts,cts,mts}\" \"{src,test}/**/*.ts\"",
    "format:check": "prettier --check \"*.{js,cjs,mjs,ts,cts,mts}\" \"{src,test}/**/*.ts\"",
    "lint": "eslint \"{src,test}/**/*.{js,ts}\"",
    "lint:fix": "npm run lint -- --fix",
    "style": "npm run format && npm run lint:fix",
    "compile": "tsc -p tsconfig.json",
    "prepare": "husky"
  }
}

Arguments

Supplying command arguments will filter the initial list of displayed scripts. However, you are not limited to the suggested list - you can still type in the prompt menu and select a different script.

For example:

scripts arg1 arg2 ...

Bypassing the selection prompt

There are cases when the CLI will run a matched script without displaying the selection prompt.

• When a single argument is provided that matches a script exactly even if there are other scripts containing that argument in their names.
• When a single script is matched based on the provided arguments.

💡 The --select option can override this behavior and force the display of the selection menu.

For example:

{
  "scripts": {
    "build": "npm run compile",
    "prebuild": "npm run ci && rimraf ./dist",
    "check-build": "npm run compile -- --noEmit"
  }
}

scripts build

👆 runs the build script (exact match)

scripts build check

👆 runs the check-build script

Running the first matched script

If there are multiple matched scripts, the --first option can be used to run the first script without displaying the selection prompt.

For example:

{
  "scripts": {
    "check-style": "npm run format:check && npm run lint",
    "check-build": "npm run compile -- --noEmit",
    "format:check": "prettier --check \"*.{js,cjs,mjs,ts,cts,mts}\" \"{src,test}/**/*.ts\""
  }
}

scripts check --first

👆 runs the check-style script

Pass-through arguments

To pass arguments directly to the underlying script, provide them after the double-dash --. All arguments passed after -- will be treated as pass-through arguments.

⚠️ If double-dash is not working in your shell, you can also use triple-dash ---.

For example:

{
  "scripts": {
    "hello": "echo hello"
  }
}

scripts hello -- world

Passing arguments to the script also works with the selection prompt:

Package Manager

The CLI allows you to run scripts by using one of the following package managers:

• npm
• pnpm
• yarn
• bun

💡 Use the --which option to view which package manager is currently being used.

Default package manager

To set the default package manager for all projects, provide the --default option with a package manager name. If no name is provided, you will be prompted to select one.

For example:

scripts --default pnpm

Project's package manager

Some projects include a packageManager property in their package.json. The CLI honors it and will run scripts using this property instead of your default package manager.

You can override this behavior by supplying the package manager that you want to use as a flag. It will be applied for the current script run only and not override the project's package manager completely.

For example, if the project defines that it uses yarn, you can run a script with pnpm as follows:

scripts --pnpm [SCRIPT]

💡 If there is no packageManager property in package.json, you can still use this pattern to override your default package manager.