CLI Commands

Try the Web CLI demo right here in your browser!

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

Usage: list-tags

Aliases: ls-tags

List all tags available with their workspaces. Tags are defined in a workspace's configuration file.

Options:

-n | --name-only

Only show tag names

-j | --json

Output as JSON

-p | --pretty

Pretty print JSON

Examples:

# Default output. Shows metadata about tags found in all workspaces
# Tags are defined in a workspace's configuration file
bw list-tags

# Output only the list of tag names
bw list-tags --name-only

# Output as JSON
bw list-tags --json

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

Tag Info

Usage: tag-info <tag>

Show metadata about a tag. Tags are defined in a workspace's configuration file.

Options:

-j | --json

Output as JSON

-p | --pretty

Pretty print JSON

Examples:

# Default output. Shows metadata about a tag
bw tag-info my-tag

# Output as JSON
bw tag-info --json

# Output as formatted JSON
bw tag-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 "false" for series, or a concurrency limit as a number, percentage ("50%"), "auto", "default", or"unbounded"

-a | --args <args>

Args to append to the script command

-o | --output-style <style>

The output style to use

(Values: grouped | prefixed | plain | none)

-L | --grouped-lines <count>

With grouped output, the max preview lines (number or "auto", default "auto")

-N | --no-prefix

(DEPRECATED) Use --output-style=plain instead

-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)

-d | --dep-order

Scripts for dependent workspaces run only after their dependencies

-f | --ignore-dep-failure

In dependency order, continue running scripts even if a dependency fails

-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

# A workspace's script will wait until any workspaces it depends on have completed
bw run my-script --dep-order

# Continue running scripts even if a dependency fails
bw run my-script --dep-order --ignore-dep-failure

# Scripts run in parallel by default
bw run my-script --parallel=false # Run in series

bw run my-script --parallel=auto # Default, number of available logical CPUs

# 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

# Use the grouped output style (default when on a TTY)
bw run my-script --output-style=grouped

# Set the max preview lines for script output in grouped output style
bw run my-script --output-style=grouped --grouped-lines=auto
bw run my-script --output-style=grouped --grouped-lines=10

# Use simple script output with workspace prefixes (default when not on a TTY)
bw run my-script --output-style=prefixed

# Use the plain output style (no workspace prefixes)
bw run my-script --output-style=plain

# Silence all output of the run command
bw --log-level=silent run my-script --output-style=none

# 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 POSIX systems, 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

See more on workspace patterns for selecting workspaces to run.
See more on workspace dependencies for running scripts in dependency order.
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",
          "isRoot": false,
          "matchPattern": "packages/**/*",
          "path": "packages/my-workspace-a",
          "scripts": [
            "my-script"
          ],
          "tags": [
            "my-tag"
          ],
          "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"
          ],
          "tags": [
            "my-tag"
          ],
          "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

CLI Commands#

List Workspaces#

Options:

Examples:

More Info#

Workspace Info#

Options:

Examples:

List Scripts#

Options:

Examples:

Script Info#

Options:

Examples:

List Tags#

Options:

Examples:

Tag Info#

Options:

Examples:

Run Script#

Options:

Examples:

More Info#

JSON Output#

Example Output:#

Doctor#

Options:

Examples:

CLI Commands

List Workspaces

More Info

Workspace Info

List Scripts

Script Info

List Tags

Tag Info

Run Script

More Info

JSON Output

Example Output:

Doctor