CLI: Commands

See the Getting Started or Glossary pages for more starting info.

Stale workspace data: Note that you need to run your package manager's install for Pacwich to have current workspace data available, e.g. via bun install, pnpm install, ornpm install. If you've added/removed/updated any workspace package.json, you'll likely need to run this again.

All Commands

List Workspaces

Usage: list-workspaces [workspacePatterns...]

Aliases: lslist

Description: List workspaces in the project.

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
pacwich list-workspaces

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

# Output as JSON
pacwich list-workspaces --json

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

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

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

More Info

See more on workspace patterns.

Workspace Info

Usage: workspace-info <workspaceName>

Aliases: info

Description: Show metadata about a workspace

Options:

-j | --json :Output as JSON

-p | --pretty :Pretty print JSON

Examples:

# Default output. Shows metadata about a workspace
pacwich workspace-info my-workspace

# Output as JSON
pacwich workspace-info my-workspace --json

# Output as formatted JSON
pacwich workspace-info my-workspace --json --pretty

List Scripts

Usage: list-scripts

Aliases: ls-scripts

Description: 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
pacwich list-scripts

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

# Output as JSON
pacwich list-scripts --json

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

Script Info

Usage: script-info <script>

Description: 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
pacwich script-info my-script

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

# Output as JSON
pacwich script-info my-script --json

# Output as formatted JSON
pacwich script-info my-script --json --pretty

Usage: list-tags

Aliases: ls-tags

Description: 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
pacwich list-tags

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

# Output as JSON
pacwich list-tags --json

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

Tag Info

Usage: tag-info <tag>

Description: 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
pacwich tag-info my-tag

# Output as JSON
pacwich tag-info my-tag --json

# Output as formatted JSON
pacwich tag-info my-tag --json --pretty

Verify

Usage: verify [workspacePatterns...]

Description: Validate your project. Potentially useful as a "prepare" root package.json script or pre-commit hook

Options:

-s | --strict :Exit non-zero when any implicit workspace dependency is found (default: warn-only)

-j | --json :Output the verify result as JSON

-p | --pretty :Pretty print JSON

Examples:

# Default output. Shows metadata about the project
pacwich verify

# Fails the command if explicit workspace dependencies are missing in package.json
pacwich verify --strict

# Scope verification of missing dependencies to specific workspaces
pacwich verify --strict my-workspace-a "path:my-pattern/**/*"

# Output as JSON
pacwich verify --json

# Output as formatted JSON
pacwich verify --json --pretty

Run Script

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

Aliases: run

Description: 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 per workspace: a number, "auto" (fit to terminal height, default), or "all"

-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
pacwich run my-script

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

# By default, the system shell (sh in POSIX systems, cmd in Windows) is used
# You can also use the Bun shell if Bun is available, which is
# a cross-platform bash-like shell.
pacwich run "echo 'this is my Bun shell script'" --inline --shell=bun

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

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

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

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

# Output results to a JSON file
pacwich 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

Description: 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)
pacwich list-affected
# Alias for list-affected
pacwich ls-affected

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

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

# Output as JSON
pacwich ls-affected --json --pretty

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

# Configure the base or head git refs for comparison (branch, commit, tag, etc.)
pacwich 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
pacwich ls-affected --files="packages/a/src/index.ts packages/b/src/index.ts"

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

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

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

Run Affected

Usage: run-affected [script]

Description: 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.