CLI Commands

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.

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

See the Glossary for more fundamental concepts.

Required Bun version: ^1.2.x

List Workspaces

Usage: list-workspaces [pattern]

Aliases: lslist

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

Options:

-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

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> [workspaces...]

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:

-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 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 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 wildcard
# (does not take into account workspace aliases)
bw run my-script "my-workspace-*"

# 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"

# 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

See more on running inline scripts.
See more on script runtime metadata, such as environment variables available in scripts and interpolating values in inline scripts and args such as <workspaceName>.
See more on workspace aliases for referencing workspaces via shorthands.
See more on running parallel scripts.

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",
          "matchPattern": "packages/**/*",
          "path": "packages/my-workspace-a",
          "scripts": [
            "my-script"
          ],
          "aliases": [
            "mwa"
          ]
        }
      }
    },
    {
      "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",
          "matchPattern": "packages/**/*",
          "path": "packages/my-workspace-b",
          "scripts": [
            "my-script"
          ],
          "aliases": [
            "mwb"
          ]
        }
      }
    }
  ]
}

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

CLI Commands#

List Workspaces#

Options:

Examples:

Workspace Info#

Options:

Examples:

List Scripts#

Options:

Examples:

Script Info#

Options:

Examples:

Run Script#

Options:

Examples:

More Info#

JSON Output#

Example Output:#

Doctor#

Options:

Examples:

CLI Commands

List Workspaces

Workspace Info

List Scripts

Script Info

Run Script

More Info

JSON Output

Example Output:

Doctor