bun-workspacesbun-workspaces
1.0.0-alpha.36
CLI
API
Config
Concepts

CLI Commands

Quick StartGlobal OptionsCommands

Run the CLI via bunx bun-workspaces or alias it to bw, such as via alias bw="bunx bun-workspaces", which can be placed in your shell configuration file, like .bashrc, .zshrc, or similar. You can also invoke bw in your rootpackage.json scripts regardless.

Examples use an implied bw alias for brevity instead of bunx bun-workspaces.

Note that you need to run bun install in your project forbun-workspaces to find your project's workspaces, and you likely must run this again after you've updated your workspaces.

See the Glossary for more fundamental concepts.

Required Bun version: ^1.2.0

List Workspaces

Usage: list-workspaces [workspacePatterns...]

Aliases: lslist

List all workspaces found in the project. This uses the "workspaces" field in your root package.json file.

Options:

-W | --workspace-patterns <patterns>

Workspace patterns to match, separated by spaces

-n | --name-only

Only show workspace names

-j | --json

Output as JSON

-p | --pretty

Pretty print JSON

Examples:
# Default output. Shows metadata about workspaces found in all workspaces
bw list-workspaces

# Output only the list of workspace names
bw list-workspaces --name-only

# Output as JSON
bw list-workspaces --json

# Output as formatted JSON
bw list-workspaces --json --pretty

# Filter workspaces by pattern
bw list-workspaces my-workspace "my-name-pattern-*" "path:packages/**/*"

# Filter workspaces by pattern using the --workspace-patterns|-W option
bw list-workspaces --workspace-patterns="my-name-pattern-* path:packages/**/*"

More Info

See more on workspace patterns.


Workspace Info

Usage: workspace-info <workspaceName>

Aliases: info

Show metadata about a workspace

Options:

-j | --json

Output as JSON

-p | --pretty

Pretty print JSON

Examples:
# Default output. Shows metadata about a workspace
bw workspace-info my-workspace

# Output as JSON
bw workspace-info --json

# Output as formatted JSON
bw workspace-info --json --pretty

List Scripts

Usage: list-scripts

Aliases: ls-scripts

List all scripts available with their workspaces

Options:

-n | --name-only

Only show script names

-j | --json

Output as JSON

-p | --pretty

Pretty print JSON

Examples:
# Default output. Shows metadata about scripts found in all workspaces
bw list-scripts

# Output only the list of script names
bw list-scripts --name-only

# Output as JSON
bw list-scripts --json

# Output as formatted JSON
bw list-scripts --json --pretty

Script Info

Usage: script-info <script>

Show metadata about a script

Options:

-w | --workspaces-only

Only show script's workspace names

-j | --json

Output as JSON

-p | --pretty

Pretty print JSON

Examples:
# Default output. Shows metadata about a script
bw script-info my-script

# Output only the list of workspaces that have the script
bw script-info my-script --workspaces-only

# Output as JSON
bw script-info --json

# Output as formatted JSON
bw script-info --json --pretty

Run Script

Usage: run-script [script] [workspacePatterns...]

Aliases: run

Run a script in all workspaces that have it in their "scripts" field in their respective package.json, or run an inline script.

Options:

-S | --script <script>

The script to run.

-W | --workspace-patterns <patterns>

Workspace patterns to match, separated by spaces.

-P | --parallel [max]

Run the scripts in parallel. Pass an optional number, percentage, or keyword: default | auto | unbounded

-a | --args <args>

Args to append to the script command

-N | --no-prefix

Do not prefix the workspace name to the script output

-i | --inline

Run the script as an inline command from the workspace directory

-I | --inline-name <name>

An optional name for the script when --inline is passed

-s | --shell <shell>

When using --inline, the shell to use to run the script

(Values: bun | system | default)

-j | --json-outfile <file>

Output results in a JSON file

Examples:
# Run my-script for all workspaces with it in their package.json "scripts" field
bw run my-script

# Run a script for a specific workspace
bw run my-script my-workspace

# Run a script for multiple workspaces
bw run my-script my-workspace-a my-workspace-b

# Run a script for workspaces using alias
bw run my-script my-alias

# Run a script for workspaces using wildcard that matches the workspace name
bw run my-script "my-workspace-*"

# Run a script for workspaces using matching specifiers
bw run my-script "alias:my-alias-*" "path:packages/**/*"

# Run a script for workspaces using the --workspace-patterns|-W option
bw run my-script --workspace-patterns="my-workspace-* my-workspace-b"

# Run a script for workspaces using the --script|-S option
bw run "my-workspace-*" my-workspace-b --script=my-script

# Run a scripts in parallel (logs are prefixed with the workspace name by default)
bw run my-script --parallel

# Run a scripts in parallel with a max of 2 concurrent scripts
bw run my-script --parallel=2

# Run a scripts in parallel with a max of 50% of the available CPUs
bw run my-script --parallel=50%

# Run a scripts in parallel with no concurrency limit (use with caution)
bw run my-script --parallel=unbounded

# Disable the workspace name prefix in the script output
bw run my-script --no-prefix

# Run an inline command from each workspace's directory
bw run "echo 'this is my inline script for <workspaceName>'" --inline

# By default, the Bun shell executes inline scripts.
# --shell=system uses the native shell (sh in Unix, cmd in Windows)
bw run "echo 'this is my native inline script'" --inline --shell=system

# Set a name for an inline command
bw run "echo 'this is my inline script'" --inline --inline-name=my-inline-script

# Append args to each script call
bw run my-script --args="--my args"

# Append args to each script call using the -- terminator
bw run my-script -- --my-arg --another-arg

# Use the workspace name in args
bw run my-script --args="--my --arg=<workspaceName>"

# Output results to a JSON file
bw run my-script --json-outfile=results.json

More Info

JSON Output

Using the --json-outfile=path/to/results.json option will output the results of all script runs to a JSON file. The file will be written relative to the project root, so it is affected by the --cwd global option. This is the same data as would be returned by the equivalent API, FileSystemProject.runScriptAcrossWorkspaces().

Example Output:
{
  "totalCount": 2,
  "successCount": 1,
  "failureCount": 1,
  "allSuccess": false,
  "startTimeISO": "1999-12-31T23:59:59.999Z",
  "endTimeISO": "2000-01-01T00:00:05.135Z",
  "durationMs": 5136,
  "scriptResults": [
    {
      "exitCode": 0,
      "signal": null,
      "success": true,
      "startTimeISO": "1999-12-31T23:59:59.999Z",
      "endTimeISO": "2000-01-01T00:00:01.283Z",
      "durationMs": 3852,
      "metadata": {
        "workspace": {
          "name": "my-workspace-a",
          "isRoot": false,
          "matchPattern": "packages/**/*",
          "path": "packages/my-workspace-a",
          "scripts": [
            "my-script"
          ],
          "aliases": [
            "mwa"
          ],
          "dependencies": [],
          "dependents": []
        }
      }
    },
    {
      "exitCode": 1,
      "signal": null,
      "success": false,
      "startTimeISO": "2000-01-01T00:00:03.851Z",
      "endTimeISO": "2000-01-01T00:00:05.134Z",
      "durationMs": 1283,
      "metadata": {
        "workspace": {
          "name": "my-workspace-b",
          "isRoot": false,
          "matchPattern": "packages/**/*",
          "path": "packages/my-workspace-b",
          "scripts": [
            "my-script"
          ],
          "aliases": [
            "mwb"
          ],
          "dependencies": [],
          "dependents": []
        }
      }
    }
  ]
}

Doctor

Usage: doctor

Print diagnostic information for bug reports etc.

Options:

-j | --json

Output as JSON

-p | --pretty

Pretty print JSON

Examples:
bw doctor
bw doctor --json --pretty # Output as formatted JSON
ON THIS PAGE