CLI: Commands

Try the Web CLI demo right here in your browser!

Running the CLI

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 root package.json scripts directly even without an alias set up.

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

Using bunx is preferred over a global install, because it ensures version consistency within projects that have installed it.

Stale Workspace Data

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, such as changing a name or adding/removing one. This is because bun.lock lists workspaces and is used as the source of truth.

Required Bun version: ^1.2.0

All Commands

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 whitespace. Use backslashes to escape spaces if needed.

-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. (Alternative to positional argument)

-W | --workspace-patterns <patterns>:Workspace patterns to match, separated by spaces. (Alternative to positional arguments)

-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 workspace script 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 tags for grouping workspaces together.
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": [],
          "externalDependencies": []
        }
      }
    },
    {
      "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": [],
          "externalDependencies": []
        }
      }
    }
  ]
}

List Affected

Usage: list-affected

Aliases: ls-affected

List all workspaces that are affected by a change

Options:

-B | --base <ref>:Git base ref to diff against (default is main if not configured). Cannot be used with --files

-H | --head <ref>:Git head ref to diff against (default: HEAD). Cannot be used with --files

-F | --files <files>:Changed files (paths/dirs/globs, '!' to exclude), separated by spaces. Use backslashes to escape spaces if needed. Bypasses git, so cannot be used with --base or --head.

-S | --script <script>:Resolve inputs for the named script

--ignore-untracked:Exclude untracked files

--ignore-unstaged:Exclude unstaged files

--ignore-staged:Exclude staged files

--ignore-uncommitted:Exclude all uncommitted changes (staged, unstaged, untracked)

--ignore-workspace-deps:Ignore workspace dependencies derived from package.json files

--ignore-external-deps:Ignore changes to external dependencies (e.g. npm packages) versions in bun.lock

-e | --explain:Include changed-file counts and dependency reasons. With --json, outputs the full result object

-D | --detailed:With --explain, render full per-file data and dependency edge chains

-j | --json:Output as JSON

-p | --pretty:Pretty print JSON

Examples:

# Default output. Shows metadata about workspaces affected
# by a change against the default git base (main when not configured)
bw list-affected
# Alias for list-affected
bw ls-affected

# Outputs reasons for affected workspaces
bw ls-affected --explain

# More detailed output about every changed file and dependency
bw ls-affected --explain --detailed

# Output as json
bw ls-affected --json --pretty

# See affected workspaces for a specific script's inputs
bw ls-affected --script=my-script

# Configure the base or head git refs for comparison (branch, commit, tag, etc.)
bw ls-affected --base=my-branch-a --head=my-branch-b

# Specify changed files instead of using git (paths/dirs/globs, '!' to exclude)
# Separate by whitespace, using backslashes to escape spaces if needed
bw ls-affected --files="packages/a/src/index.ts packages/b/src/index.ts"

# Ignore specific git changes that are considered by default
bw ls-affected --ignore-untracked
bw ls-affected --ignore-unstaged
bw ls-affected --ignore-staged
# Ignores staged, unstaged, and untracked changes
bw ls-affected --ignore-uncommitted

# Ignore changes to workspace dependencies
bw ls-affected --ignore-workspace-deps

# Ignore changes to external dependencies (e.g. npm packages)
bw ls-affected --ignore-external-deps

Run Affected

Usage: run-affected [script]

Run a script across the workspaces affected by a change

Options:

-S | --script <script>:The script to run. (Alternative to positional argument)

-B | --base <ref>:Git base ref to diff against (default is main if not configured). Cannot be used with --files

-H | --head <ref>:Git head ref to diff against (default "HEAD"). Cannot be used with --files

-F | --files <files>:Changed files (paths/dirs/globs, '!' to exclude), separated by whitespace. Use backslashes to escape spaces if needed. Bypasses git, so cannot be used with --base or --head.