---
url: /intro/overview/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /intro/overview/index.md.

# Overview

`pacwich` is an npm package that works with your package manager's workspace functionality.
`pacwich` supports [Bun](https://bun.sh/docs/pm/workspaces), [npm](https://docs.npmjs.com/cli/v11/using-npm/workspaces), and [pnpm](https://pnpm.io/workspaces) workspaces.

We take [package security](/security.md) seriously.

This page focuses on the overall motivations and design philosophy of `pacwich`. See
the [getting started guide](/intro/getting-started.md) to jump straight in.

## What does it do?

`pacwich` gives you means of getting metadata about your monorepo in human-readable
CLI output or JSON.

You can orchestrate [running scripts](/cli/commands.md#run-script) from workspaces' package.json files.

The optional configuration enriches workspaces with additional metadata and can
define [rules](/config/workspace.md) for enforcing code sharing restrictions between workspaces.


---


## Easy, Zero-Config

`pacwich`'s main goal is to provide a straightforward monorepo tooling layer that
uses as much data from your package manager as it can, not requiring special configuration to get started,
though accepting [optional config](/config.md) for more advanced usage.

It works with your workspaces' `package.json` scripts directly instead of defining a new mental model for
your processes.


---


## A CLI and TS/JS API

`pacwich` provides both a [CLI](/cli.md) and a [TS/JS API](/api.md) for interacting with your monorepo.

Since the CLI is developed via TypeScript, providing the API is natural, since the
CLI needs a TypeScript core underneath it anyway.

The API is held in close parity with the CLI. This means that you can write scripts
for your repo's automation tasks that involve `pacwich` for getting metadata or running
scripts in either shell code or TypeScript/JavaScript.


---


## Decoupling from Your Package Manager

The top package managers for JavaScript provide their own monorepo functionality, but there are several reasons to decouple your monorepo tooling from your package manager of choice.

### Scope and Development Process of PMs

Every package manager comes with various advantages and disadvantages. Package manager directions can change, and
they compete on a variety of fronts, not just monorepo features. One can be the hot favorite one day and fall out
of favor the next. One may have the best monorepo support but stall its progress as priorities shift.

Package managers' surfaces are large and cover many different concerns, which can often mean
that monorepo features are more expensive to add, especially if a CLI is already crowded with various concerns,
and some advanced monorepo features may never be in scope for these tools.

### `pacwich`'s Answer

`pacwich` has the advantage of being able to focus scope entirely on monorepo features and develop quickly
as a straightforward TypeScript package, free of package managers' red tape.

`pacwich` seeks to provide a unified layer for your monorepo tooling, so that you're free to swap package managers
without losing your monorepo metadata or script orchestration, with little to no friction when doing so.


---


## A Lightweight Project Graph

`pacwich` is aware of how your [workspaces depend on each other](/concepts/workspace-dependencies.md), opting to read dependencies from
package.json files instead of relying on analysis your JavaScript/TypeScript files. This makes
analyzing your project graph simple and fast.

Since declaring workspaces as dependencies in package.json files isn't required in all package managers,
`pacwich` includes a [`verify` feature](/concepts/verify.md) to help detect missing dependencies via simple code analysis.

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /cli/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /cli/index.md.

# CLI


<CliInstall />


Alt install instructions for .md page in place of <CliInstall /> above:

Installing:

### npm:

Global install: `npm install -g pacwich
# Print help for installing completions
pacwich completion
# Attempt to automatically install completions for your shell
pacwich completion install
`
Local install: `npm install -D pacwich`
Local/one-off execution: `npx pacwich`

### pnpm:

Global install: `pnpm add -g pacwich
# Print help for installing completions
pacwich completion
# Attempt to automatically install completions for your shell
pacwich completion install
`
Local install: `pnpm add -D pacwich`
Local/one-off execution: `pnpm exec pacwich`

### bun:

Global install: `bun add -g pacwich
# Print help for installing completions
pacwich completion
# Attempt to automatically install completions for your shell
pacwich completion install
`
Local install: `bun add -d pacwich`
Local/one-off execution: `bunx pacwich`

Note that the global install will delegate to the local install when available.




See the [Getting Started](/intro/getting-started) or [Glossary](/concepts/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`, or `npm install`. If you've added/removed/updated any workspace package.json, you'll likely need to run this again.


## Quick Start

See full [global options](/cli/global-options.md) or [commands](/cli/commands.md) documentation.


````
##########
# Global #
##########

# Show usage (you can pass --help to any command)
pacwich --help

# Show version
pacwich --version

# Pass --cwd to any command
pacwich --cwd=/path/to/your/project ls
pacwich --cwd=/path/to/your/project run my-script

# Specify package manager, if you have multiple lockfiles
pacwich --pm=pnpm ls

# Pass --log-level to any command (debug, info, warn, error, or silent)
# A default can also be set with the PACWICH_LOG_LEVEL env var (the flag overrides it)
pacwich --log-level=debug ls

# Suppress specific warning messages (can also be set by project config)
# Warning IDs can be seen in warning log prefixes (full list: https://pacwich.dev/config/warnings)
pacwich --suppress-warnings=MultiplePackageManagerLockfiles ls
pacwich --suppress-warnings=MultiplePackageManagerLockfiles,ParallelExceedsAvailableCpus run lint

####################
# Getting metadata #
####################

# List all workspaces in your project
pacwich list-workspaces

# ls is an alias for list-workspaces
pacwich ls --json --pretty # Output as formatted JSON

# Get info about a workspace
pacwich workspace-info my-workspace
pacwich info my-workspace --json --pretty # info is alias for workspace-info

# Get info about a script, such as the workspaces that have it
pacwich script-info my-script

##########
# Verify #
##########

# Check for issues with your project
# Can be useful as your root package.json "prepare" script
# or as a pre-commit hook
pacwich verify

# Fails if workspaces detected that import/export from each other
# without explicit dependency declared in package.json
pacwich verify --strict

###################
# Running scripts #
###################

# Run the lint script for all workspaces in parallel
# that have it in their package.json "scripts" field
pacwich run lint
pacwich run lint my-workspace # Run for a single workspace
pacwich run lint my-workspace-a my-workspace-b # Run for multiple workspaces
pacwich run lint my-alias-a my-alias-b # Run by alias (set by optional config)

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

# Workspace patterns
pacwich run lint "my-workspace-*" # Run for matching workspace names
pacwich run lint "alias:my-alias-*" "path:my-glob/**/*" "tag:my-tag"
pacwich run lint "re:my-name-regex.*" "path:re:my-path-regex.*"
pacwich run lint "*" "not:path:my-path/*" # Run for all workspaces not in my-path/

pacwich run lint --args="--my-appended-args" # Add args to each script call
pacwich run lint --args="--my-arg=<workspaceName>" # Use the workspace name in args

pacwich run "cat package.json" --inline # Run an inline shell command

# Inline scripts can use the Bun shell if Bun is available,
# which is a cross-platform Bash-like shell
# This can be helpful for multi-OS support
pacwich run "cat package.json" --inline --shell=bun

# Scripts run in parallel by default
pacwich run lint --parallel=auto # Default, based on available logical CPUs
pacwich run lint --parallel=false # Run sequentially
pacwich run lint --parallel=2 # 2 max scripts run concurrently
pacwich run lint --parallel=50% # half of available logical CPUs

# Set the max preview lines for script output
# when "grouped" output style is used (the default on TTY)
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

# Run an interactive script with full stdio, for user input etc.
# Requires a script and one workspace name or alias
# A script only gets a TTY if the caller is a TTY (i.e. not piped or redirected)
pacwich run-interactive my-interactive-script my-workspace-name-or-alias

# ri is an alias for run-interactive
pacwich ri my-interactive-script my-workspace-name-or-alias

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

#####################
# Affected Features #
#####################

# List affected workspaces based on git diff (main vs. HEAD by default)
pacwich affected list

# Set the git base and head for comparison
pacwich affected list --base=my-branch-a --head=my-branch-b

# See detailed reasons for affected workspaces
pacwich affected list --explain --detailed

# Run a script across the workspaces affected by a change
pacwich affected run my-script
pacwich affected run my-script --base=my-branch-a --head=my-branch-b

# Aliases
pacwich affected ls
pacwich af ls
pacwich af run

##########
# Config #
##########

# Commands for pacwich's optional configuration

# Print project and all workspace configs as JSON
pacwich config debug
pacwich config debug --pretty # pretty print JSON

# Print just the project config as JSON
pacwich config debug --project

# Print a single workspace config as JSON
pacwich config debug --workspace=name-or-alias

# Print workspace configs matching a pattern as JSON
pacwich config debug --workspace-patterns="my-pattern-*"
````

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /cli/global-options/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /cli/global-options/index.md.

# CLI: Global Options


See the [Getting Started](/intro/getting-started) or [Glossary](/concepts/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`, or `npm install`. If you've added/removed/updated any workspace package.json, you'll likely need to run this again.


See also [all CLI commands here](/cli/commands.md) or the [CLI quick start](/cli.md).

## All Global Options

### Working Directory


**Usage**: `--cwd` | `-d`

**Description:** Get the project root from a specific directory. This should be where the root package.json of your project is located.

##### *Examples:*


````
pacwich --cwd=/path/to/your/project list-workspaces
pacwich -d /path/to/your/project list-workspaces
````


---


### Package Manager


**Usage**: `--pm`

**Values**: `auto``bun``pnpm``npm`

**Description:** Expect a specific package manager. This overrides config and environment variable settings.

##### *Examples:*


````
pacwich --pm=pnpm list-workspaces
````


---


### Include Root


**Usage**: `--include-root` | `-r`

**Description:** Include the root workspace as a normal workspace. This overrides config and environment variable settings.

##### *Examples:*


````
pacwich --include-root list-workspaces
pacwich -r list-workspaces

pacwich --no-include-root list-workspaces # disable (to override config/env)
````

See more on the [Root Workspace](/concepts/root-workspace.md).


---


### Disable Executable Configs


**Usage**: `--disable-executable-configs`

**Description:** Disable loading of executable config files (written in TS/JS) for untrusted contexts. This can be set by default using the environment variable PACWICH_DISABLE_EXECUTABLE_CONFIGS_DEFAULT=true.

##### *Examples:*


````
pacwich --disable-executable-configs list-workspaces
````


---


### Suppress Warnings


**Usage**: `--suppress-warnings`

**Description:** Suppress warning logs by id, in addition to the PACWICH_SUPPRESS_WARNINGS env var

##### *Examples:*


````
pacwich --suppress-warnings=MissingWorkspacesHint,MultipleConfigsFound ls
````

See the [warning page](/config/warnings.md) for a list of all IDs and means of setting suppression.


---


### Log Level


**Usage**: `--log-level` | `-l`

**Values**: `debug``info``warn``error``silent`

**Default Value**: `info`

**Description:** Set the logging level. For the run-script (run) command, silence output with --output-style=none. A default can be set with the PACWICH_LOG_LEVEL env var, which this flag overrides when passed.

##### *Examples:*


````
pacwich --log-level=debug list-workspaces
pacwich -l error list-workspaces
````


---


### Help


**Usage**: `--help` | `-h`

**Description:** Print help. Available on the CLI itself and on every command to show its usage and options. 

##### *Examples:*


````
# Help for the CLI overall
pacwich --help

# Help for a specific command
pacwich run --help
pacwich affected list -h
````

Also available as the [help command](/cli/commands.md#cli-command-help).


---


### Version


**Usage**: `--version` | `-V`

**Description:** Print pacwich's version.

##### *Examples:*


````
pacwich --version
pacwich -V
````

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /cli/commands/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /cli/commands/index.md.

# CLI: Commands


See the [Getting Started](/intro/getting-started) or [Glossary](/concepts/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`, or `npm install`. If you've added/removed/updated any workspace package.json, you'll likely need to run this again.


See also [all CLI global options here](/cli/global-options.md) or the [CLI quick start](/cli.md).

## All Commands

### List Workspaces


**Usage**: `list-workspaces [workspacePatterns...]`

**Aliases**: `ls``list`

**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](/concepts/workspace-patterns.md).


---


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


---


### List Tags


**Usage**: `list-tags`

**Aliases**: `ls-tags`

**Description**: List all [tags](/config/workspace#tags) available with their workspaces. Tags are defined in a workspace's [configuration file](/config/workspace).

##### 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](/config/workspace#tags). Tags are defined in a workspace's [configuration file](/config/workspace).

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

#### More Info

See more on the [verify concept](/concepts/verify.md).


---


### 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](/concepts/workspace-patterns.md) for selecting workspaces to run.
- See more on [workspace dependencies](/concepts/workspace-dependencies.md) for running scripts in dependency order.
- See more on running [inline scripts](/concepts/inline-scripts.md).
- See more on [workspace script metadata](/concepts/workspace-script-metadata.md), such as environment variables available in scripts and interpolating values in inline scripts and args such as `<workspaceName>`.<br />
- See more on [workspace aliases](/concepts/workspace-aliases.md) for referencing workspaces via shorthands.
- See more on [tags](/config/workspace.md#tags) for grouping workspaces together.
- See more on running [parallel scripts](/concepts/parallel-scripts.md).

#### 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](/cli/global-options.md#working-directory).
This is the same data as would be returned by the equivalent API, [`FileSystemProject.runScriptAcrossWorkspaces()`](/api/reference.md#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": []
        }
      }
    }
  ]
}
````


---


### Run Interactive


**Usage**: `run-interactive [script] [workspace]`

**Aliases**: `ri`

**Description**: Run a single script in a single workspace with stdio inherited, so the script can read user input

##### Options:

`-W | --workspace <workspace>` :The workspace to run the script in, resolved by name or alias (required). (Alternative to second positional argument)

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

`-a | --args <args>` :Args to append to the script command

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

##### *Examples:*


````
# Run a script interactively in a single workspace (resolved by name or
# alias). stdio is inherited so the script can read user input, and the
# script's own exit code is surfaced as pacwich's.
pacwich run-interactive my-script -W my-workspace

# The short alias `ri` works too
pacwich ri my-script -W my-workspace

# The workspace can also be passed as the second positional argument
pacwich run-interactive my-script my-workspace

# The script can be a positional arg or the --script option, and the
# workspace likewise via the second positional or the --workspace option
pacwich run-interactive --script=my-script --workspace=my-workspace

# Forward args to the script with --args or after --
pacwich run-interactive my-script -W my-workspace --args='--watch'
pacwich run-interactive my-script -W my-workspace -- --watch

# Run an inline command instead of a named script
pacwich run-interactive "echo my-inline-script" \
  --workspace=my-workspace \
  --inline \
  --inline-name=my-inline-script \
  --shell=system
````

#### More Info

- A script only gets a TTY if the caller is a TTY (i.e. not piped or redirected).
- See more on running [inline scripts](/concepts/inline-scripts.md).
- See more on [workspace script metadata](/concepts/workspace-script-metadata.md).
- The API equivalent is [`FileSystemProject.runWorkspaceScript()`](/api/reference.md#runworkspacescript) using option `interactive: true`.


---


### Affected: List


**Usage**: `affected list`

**Aliases**: `ls`

**Description**: List all workspaces that are affected by a change. Same as the deprecated list-affected/ls-affected command.

##### 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 affected list

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

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

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

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

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

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

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

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


---


### Affected: Run


**Usage**: `affected run [script]`

**Description**: Run a script across the workspaces affected by a change. Same as the deprecated run-affected command.

##### 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 spaces. Use backslashes to escape spaces if needed. Bypasses git, so cannot be used with --base or --head.

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

`-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 a script for all workspaces affected by a change
# using the default git base (main when not configured)
pacwich affected run my-script

# Script can be a positional arg or an option
pacwich affected run --script=my-script

# Takes most options as affected list

# Configure the base or head git refs for comparison
pacwich affected run my-script --base=my-branch-a --head=my-branch-b

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

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

# Ignore changes to workspace dependencies
pacwich affected run my-script --ignore-workspace-deps

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

# Other than specifying workspaces, takes all options as run-script
pacwich affected run "echo my-inline-script" \
  --parallel=false \
  --output-style=grouped \
  --grouped-lines=10 \
  --inline \
  --inline-name=my-inline-script \
  --shell=system \
  --dep-order \
  --ignore-dep-failure \
  --args='--my-arg --another-arg=<workspaceName>' \
  --json-outfile=results.json
````


---


### Config: Debug


**Usage**: `config debug`

**Description**: Print project and workspace configuration as JSON

##### Options:

`--project` :Only print the resolved project config

`-w | --workspace <workspace>` :Only print the resolved config for a single workspace, resolved by name or alias

`-W | --workspace-patterns <patterns>` :Only print the resolved config for workspaces matching these patterns, separated by whitespace

`-p | --pretty` :Pretty print JSON

##### *Examples:*


````
# Print all project and workspace configs
pacwich config debug

# Pretty-print JSON output
pacwich config debug --pretty

# Print only project configuration
pacwich config debug --project

# Print only workspace configuration by name/alias
pacwich config debug --workspace=my-name-or-alias

# Print workspace configs by workspace pattern
pacwich config debug --workspace-patterns="my-pattern-* my-workspace"
````


---


### Add Skills


**Usage**: `add-skills`

**Description**: Add skill files to your project. These contain docs about Pacwich for an agent.

##### Options:

`--dir <path>` :Target directory for the skills, relative to --cwd (default: .agents/skills)

`--dry-run` :Print what would be written without writing any files

##### *Examples:*


````
# Writes to .agents/skills by default
pacwich add-skills

# Claude skills location
pacwich add-skills --dir=.claude/skills

# Print files to be written only
pacwich add-skills --dir=./my-custom-dir --dry-run
````


---


### MCP Server


**Usage**: `mcp-server`

**Description**: Start the pacwich MCP (Model Context Protocol) server over stdio. Set this up with your tooling of choice.

##### *Examples:*


````
pacwich mcp-server
````


---


### Completion


**Usage**: `completion [shell]`

**Description**: By default, print completion help for bash, zsh, or fish, or run install subcommand to auto-write user shell config.

##### *Examples:*


````
# Print help for completion setup:
pacwich completion

# Attempt to automatically install completion for your shell
pacwich completion install

# Specify a shell explicitly
pacwich completion install zsh

# Print the completion script for a specific shell
pacwich completion zsh
````


---


### Completion: Install


**Usage**: `completion install [shell]`

**Description**: Wire completions into your shell's config, auto-detecting the current shell when none is given

##### *Examples:*


````
# Auto-detect your shell and install
pacwich completion install

# Specify a shell explicitly
pacwich completion install zsh
````


---


### Doctor


**Usage**: `doctor`

**Description**: Print diagnostic information for bug reports etc.

##### Options:

`-j | --json` :Output as JSON

`-p | --pretty` :Pretty print JSON

##### *Examples:*


````
pacwich doctor
pacwich doctor --json --pretty # Output as formatted JSON
````


---


### Help


**Usage**: `help [command]`

**Description**: Print help for the CLI or for a specific command. Equivalent to passing the --help option.

##### *Examples:*


````
# Same as pacwich --help
pacwich help

# Help for a specific command (same as pacwich run --help)
pacwich help run

# Command aliases work too
pacwich help ls
````

`pacwich help <command>` is equivalent to `pacwich <command> --help`. See [--help](/cli/global-options.md#cli-global-option-help).

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /web-cli/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /web-cli/index.md.

# 

# Web CLI

Try the CLI right here in your browser!
This uses a demo project you can view in the Project Files below.

You may have a better experience with the Web CLI on desktop.

###### Notes:

- See the full CLI documentation [here](/cli).
- This isn't a full bash shell, so shell operations beyond providing args to `pacwich` aren't supported.
-  Features **not** supported:- [Inline scripts](/concepts/inline-scripts)
- appending args to scripts (`--args` or `-- [args]`)
- changing the working directory via `--cwd`
- git-based affected diffs, which `affected list`/`affected run` use by default (with or without `--base`/`--head`). Pass `--files` instead to provide a list of changed files manually.



© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /api/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /api/index.md.

# TS/JS API


<ApiInstall />


Alt install instructions for .md page in place of <ApiInstall /> above:

Installing:

### bun:

Install: `bun add -d pacwich`

### pnpm:

Install: `pnpm add -D pacwich`

### npm:

Install: `npm install -D pacwich`




See the [Getting Started](/intro/getting-started) or [Glossary](/concepts/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`, or `npm install`. If you've added/removed/updated any workspace package.json, you'll likely need to run this again.


## Quick Start

See the [full API reference here](/api/reference.md).


````
import { createFileSystemProject } from "pacwich";

// A Project contains the core functionality of pacwich.
// Below defaults to process.cwd() for the project root directory
// Pass { rootDirectory: "path/to/your/project" } to use a different root directory
const project = createFileSystemProject();

// A Workspace that matches the name or alias "my-workspace"
const myWorkspace = project.findWorkspaceByNameOrAlias("my-workspace");

// Array of workspaces whose names match the wildcard pattern
const wildcardWorkspaces = project.findWorkspacesByPattern("my-workspace-*");

// Array of workspaces that have "my-script" in their package.json "scripts"
const workspacesWithScript = project.listWorkspacesWithScript("my-script");

// Run a script in a workspace
const runSingleScript = async () => {
  const { output, exit } = project.runWorkspaceScript({
    workspaceNameOrAlias: "my-workspace",
    script: "my-script",

    // Optional. Arguments to add to the command
    // Can be a string or an array of strings
    // If string, the argv will be parsed POSIX-style
    args: ["--my", "--appended", "--args"],

    // Optional (default false). Whether to ignore all output from the script.
    // This saves memory when you don't need script output.
    ignoreOutput: false,

    // Optional (default false). Run the script interactively to accept user input.
    // When true, the script will have access to stdin, stdout, and stderr,
    // and script output cannot be captured. Note that a script only gets a TTY
    // if the caller is a TTY (i.e. not piped or redirected)
    interactive: false,
  });

  // Get a stream of the script subprocess's output
  for await (const { chunk, metadata } of output.text()) {
    // console.log(chunk); // The output chunk's content (string)
    // console.log(metadata.streamName); // "stdout" or "stderr"
    // console.log(metadata.workspace); // The target Workspace
  }

  // Get data about the script execution after it exits
  const exitResult = await exit;

  // exitResult.exitCode // The exit code (number)
  // exitResult.signal // The exit signal (string), or null
  // exitResult.success // true if exit code was 0
  // exitResult.startTimeISO // Start time (string)
  // exitResult.endTimeISO // End time (string)
  // exitResult.durationMs // Duration in milliseconds (number)
  // exitResult.metadata.workspace // The target workspace (Workspace)
};

// Run a script in all workspaces that have it in their package.json "scripts"
const runManyScripts = async () => {
  const { output, summary } = project.runScriptAcrossWorkspaces({
    // Optional. This will run in all matching workspaces that have my-script
    // Accepts same values as the CLI run-script command's workspace patterns
    // When not provided, all workspaces that have the script will be used.
    workspacePatterns: ["my-workspace", "my-name-pattern-*"],

    // Required. The package.json "scripts" field name to run
    script: "my-script",

    // Optional. Arguments to add to the command (same as for runWorkspaceScript)
    args: ["--my", "--appended", "--args"],

    // Optional (default true). Whether to run the scripts in parallel
    parallel: true,

    // Optional (default false). When true, a workspace's script will wait
    // until any workspaces it depends on have completed
    dependencyOrder: false,

    // Optional. When true and dependencyOrder is true,
    // continue running scripts even if a dependency fails
    ignoreDependencyFailure: false,

    // Optional (default false). Whether to ignore all output from the scripts.
    // This saves memory when you don't need script output.
    ignoreOutput: false,

    // Optional, callback when script starts, skips, or exits
    onScriptEvent: (event, { workspace, exitResult }) => {
      // event: "start", "skip", "exit"
    },
  });

  // Get a stream of script output
  for await (const { chunk, metadata } of output.text()) {
    // console.log(chunk); // the output chunk's content (string)
    // console.log(metadata.streamName); // "stdout" or "stderr"
    // console.log(metadata.workspace); // the Workspace of the output
  }

  // Get final summary data and script exit details
  const summaryResult = await summary;

  // summaryResult.totalCount // Total number of scripts
  // summaryResult.allSuccess // true if all scripts succeeded
  // summaryResult.successCount // Number of scripts that succeeded
  // summaryResult.failureCount // Number of scripts that failed
  // summaryResult.startTimeISO // Start time (string)
  // summaryResult.endTimeISO // End time (string)
  // summaryResult.durationMs // Total duration in milliseconds (number)

  // The exit details of each workspace script
  for (const exitResult of summaryResult.scriptResults) {
    // exitResult.exitCode // The exit code (number)
    // exitResult.signal // The exit signal (string), or null
    // exitResult.success // true if exit code was 0
    // exitResult.startTimeISO // Start time (ISO string)
    // exitResult.endTimeISO // End time (ISO string)
    // exitResult.durationMs // Duration in milliseconds (number)
    // exitResult.metadata.workspace // The target workspace (Workspace)
  }
};
````

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /api/reference/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /api/reference/index.md.

# TS/JS API: Reference


See the [Getting Started](/intro/getting-started) or [Glossary](/concepts/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`, or `npm install`. If you've added/removed/updated any workspace package.json, you'll likely need to run this again.


See the [API quick start here](/api.md).

## createFileSystemProject

`createFileSystemProject(options: CreateFileSystemProjectOptions): FileSystemProject`

Create a [FileSystemProject](/api/reference.md#filesystemproject), the core of `pacwich`'s functionality, based on a given root directory.

This will walk up to find the nearest project root if ran from a project's subdirectory.

It will also detect and utilize any [project configuration](/config/project.md) and [workspace configurations](/config/workspace.md) found.


````
import { createFileSystemProject } from "pacwich";

// Root directory defaults to process.cwd()
// Package manager is auto-detected if a lockfile is found
const defaultProject = createFileSystemProject();

const pathProject = createFileSystemProject({
  // relative from process.cwd()
  rootDirectory: "./path/to/project/root",

  // Specify a package manager, mainly if multiple lockfiles are present
  packageManager: "bun",

  // (default false) Include the root workspace as a normal workspace
  includeRootWorkspace: false,

  // Disable executable configuration files (TS/JS) for untrusted contexts
  disableExecutableConfigs: true,
});
````

## Workspace

An object representing a workspace in a [Project](/api/reference.md#project).

Set [workspace aliases](/concepts/workspace-aliases.md) in the [workspace configuration](/config/workspace.md) to make it easier to reference workspaces.

The `dependencies` and `dependents` fields are names of other workspaces that are [dependencies](/concepts/workspace-dependencies.md) or dependents of this workspace, respectively.

See more on the [root workspace](/concepts/root-workspace.md).


````
{
  // The name of the workspace from its package.json
  name: "my-workspace",

  // Whether the workspace is the root workspace
  isRoot: false,

  // The relative path to the workspace from the project root
  path: "my/workspace/path",

  // The glob pattern from the root package.json "workspaces" field
  // that this workspace was matched from
  matchPattern: "my/workspace/pattern/*",

  // The scripts available in the workspace's package.json
  scripts: ["my-script"],

  // Aliases defined in workspace configuration (see the Configuration section)
  aliases: ["my-alias"],

  // Tags defined in workspace configuration (see the Configuration section)
  tags: ["my-tag"],

  // Names of other workspaces that this workspace depends on
  dependencies: ["my-dependency"],

  // Names of other workspaces that depend on this workspace
  dependents: ["my-dependent"],

  // Other external dependencies, e.g. lodash, react
  externalDependencies: [
    {
      "name": "lodash",
      "version": "^4.17.21",
      "source": "devDependencies"
    },
  ],
}
````

## Project

The core of `pacwich`'s functionality.
It contains a list of [Workspaces](/api/reference.md#workspace) and provides
several useful methods for working with them. A Project is typically initialized at a git repository's root directory.
The Project root should contain the `package.json` file in which `"workspaces"` are defined.

Usually created via [createFileSystemProject](/api/reference.md#createfilesystemproject).


````
import { createFileSystemProject } from "pacwich";

const project = createFileSystemProject();
````

### .name

`type: string`

The name of the project. This is typically the name found in the root `package.json` unless otherwise provided.


---


### .rootDirectory

`type: string`

The given root directory of the project.


---


### .workspaces

`type: Workspace[]`

The list of all [Workspaces](/api/reference.md#workspace) in the project.


---


### .rootWorkspace

`type: Workspace`

The [root workspace](/concepts/root-workspace.md) of the project.


---


### .findWorkspaceByName

`findWorkspaceByName(workspaceName: string): Workspace | null`

Find a [Workspace](/api/reference.md#workspace) by its package.json name.


````
// Find a workspace by its package.json name (or returns null)
const workspace = project.findWorkspaceByName("my-workspace");
````


---


### .findWorkspaceByAlias

`findWorkspaceByAlias(alias: string): Workspace | null`

Find a [Workspace](/api/reference.md#workspace) by its [alias](/concepts/workspace-aliases.md), if set in its [workspace configuration](/config/workspace.md).


````
// Find a workspace by its alias (or returns null)
const workspace = project.findWorkspaceByAlias("my-alias");
````


---


### .findWorkspaceByNameOrAlias

`findWorkspaceByNameOrAlias(nameOrAlias: string): Workspace | null`

Find a [Workspace](/api/reference.md#workspace) by its package.json name or [alias](/concepts/workspace-aliases.md), if set in its [workspace configuration](/config/workspace.md).

Since [aliases](/concepts/workspace-aliases.md) are validated to be unique to each workspace
and not clash with other workspaces' package.json names,
this method can still unambiguously find a workspace.


````
// Find a workspace by its package.json name or alias (or returns null)
const workspace = project.findWorkspaceByNameOrAlias("my-workspace");
````


---


### .findWorkspacesByPattern

`findWorkspacesByPattern(workspacePattern: string): Workspace[]`

Find a list of [Workspaces](/api/reference.md#workspace) by their name, using a wildcard pattern.

See more on the syntax of [workspace patterns](/concepts/workspace-patterns.md).


````
// An array of workspaces whose names match the wildcard pattern
const workspaces = project.findWorkspacesByPattern(
  "my-name-pattern-*",
  "alias:my-alias-*",
  "path:packages/**/*",
);
````


---


### .listWorkspacesWithScript

`listWorkspacesWithScript(scriptName: string): Workspace[]`

Get an array of all [Workspaces](/api/reference.md#workspace) that have a given script in their package.json "scripts" field.


````
// An array of workspaces that have "my-script" 
// in their package.json "scripts" field
const workspaces = project.listWorkspacesWithScript("my-script");
````


---


### .listWorkspacesWithTag

`listWorkspacesWithTag(tag: string): Workspace[]`

Get an array of all [Workspaces](/api/reference.md#workspace) that have a given [tag](/config/workspace.md#tags). Tags are defined in a workspace's [configuration](/config/workspace.md).


````
// An array of workspaces that have the tag "my-tag".
// Tags are defined in a workspace's configuration file.
const workspaces = project.listWorkspacesWithTag("my-tag");
````


---


### .scriptMap

`scriptMap: Record<string, ScriptDetails>`

Get a mapping of all project script names to the [Workspaces](/api/reference.md#workspace) that have them in their package.json "scripts" field.


````
// An array of Workspaces
const { workspaces } = project.scriptMap["my-script"];
````


---


### .tagMap

`tagMap: Record<string, TagDetails>`

Get a mapping of all [tags](/config/workspace.md#tags) to the [Workspaces](/api/reference.md#workspace) that have them in their respective [workspace configuration](/config/workspace.md).


````
// An array of Workspaces
const { workspaces } = project.tagMap["my-tag"];
````


---


## FileSystemProject

Inherits from [Project](/api/reference.md#project). Used to represent a project in the file system. Created via [createFileSystemProject](/api/reference.md#createfilesystemproject).

Includes methods for running scripts in the workspaces of the project.

### .runWorkspaceScript

`runWorkspaceScript(options: RunWorkspaceScriptOptions): RunWorkspaceScriptResult`

Run a script in a given workspace.


````
const { output, exit } = project.runWorkspaceScript({
  workspaceNameOrAlias: "my-workspace",
  script: "my-script",

  // Optional. Arguments to add to the command
  // Can be a string or an array of strings
  // If string, the argv will be parsed POSIX-style
  args: ["--my", "--appended", "--args"],

  // Optional (default false). Whether to ignore all output from the script.
  // This saves memory when you don't need script output.
  ignoreOutput: false,

  // Optional (default false). Run the script interactively to accept user input.
  // When true, the script will have access to stdin, stdout, and stderr,
  // and script output cannot be captured. Note that a script only gets a TTY
  // if the caller is a TTY (i.e. not piped or redirected)
  interactive: false,
});

// Get a stream of the script subprocess's output
for await (const { chunk, metadata } of output.text()) {
  // console.log(chunk); // The output chunk's content (string)
  // console.log(metadata.streamName); // "stdout" or "stderr"
  // console.log(metadata.workspace); // The target Workspace
}

// Get data about the script execution after it exits
const exitResult = await exit;

// exitResult.exitCode // The exit code (number)
// exitResult.signal // The exit signal (string), or null
// exitResult.success // true if exit code was 0
// exitResult.startTimeISO // Start time (string)
// exitResult.endTimeISO // End time (string)
// exitResult.durationMs // Duration in milliseconds (number)
// exitResult.metadata.workspace // The target workspace (Workspace)
````


---


### .runScriptAcrossWorkspaces

`runScriptAcrossWorkspaces(options: RunScriptAcrossWorkspacesOptions): RunScriptAcrossWorkspacesResult`

Run a script in all workspaces that have it in their package.json "scripts" field.


````
const { output, summary } = project.runScriptAcrossWorkspaces({
  // Optional. This will run in all matching workspaces that have my-script
  // Accepts same values as the CLI run-script command's workspace patterns
  // When not provided, all workspaces that have the script will be used.
  workspacePatterns: ["my-workspace", "my-name-pattern-*"],

  // Required. The package.json "scripts" field name to run
  script: "my-script",

  // Optional. Arguments to add to the command (same as for runWorkspaceScript)
  args: ["--my", "--appended", "--args"],

  // Optional (default true). Whether to run the scripts in parallel
  parallel: true,

  // Optional (default false). When true, a workspace's script will wait
  // until any workspaces it depends on have completed
  dependencyOrder: false,

  // Optional. When true and dependencyOrder is true,
  // continue running scripts even if a dependency fails
  ignoreDependencyFailure: false,

  // Optional (default false). Whether to ignore all output from the scripts.
  // This saves memory when you don't need script output.
  ignoreOutput: false,

  // Optional, callback when script starts, skips, or exits
  onScriptEvent: (event, { workspace, exitResult }) => {
    // event: "start", "skip", "exit"
  },
});

// Get a stream of script output
for await (const { chunk, metadata } of output.text()) {
  // console.log(chunk); // the output chunk's content (string)
  // console.log(metadata.streamName); // "stdout" or "stderr"
  // console.log(metadata.workspace); // the Workspace of the output
}

// Get final summary data and script exit details
const summaryResult = await summary;

// summaryResult.totalCount // Total number of scripts
// summaryResult.allSuccess // true if all scripts succeeded
// summaryResult.successCount // Number of scripts that succeeded
// summaryResult.failureCount // Number of scripts that failed
// summaryResult.startTimeISO // Start time (string)
// summaryResult.endTimeISO // End time (string)
// summaryResult.durationMs // Total duration in milliseconds (number)

// The exit details of each workspace script
for (const exitResult of summaryResult.scriptResults) {
  // exitResult.exitCode // The exit code (number)
  // exitResult.signal // The exit signal (string), or null
  // exitResult.success // true if exit code was 0
  // exitResult.startTimeISO // Start time (ISO string)
  // exitResult.endTimeISO // End time (ISO string)
  // exitResult.durationMs // Duration in milliseconds (number)
  // exitResult.metadata.workspace // The target workspace (Workspace)
}
````

#### More Info

- See more on the syntax of [workspace patterns](/concepts/workspace-patterns.md) for selecting workspaces to run.
- See more on [workspace dependencies](/concepts/workspace-dependencies.md) for running scripts in dependency order.
- See more on running [inline scripts](/concepts/inline-scripts.md).
- See more on running [parallel scripts](/concepts/parallel-scripts.md).
- See more on [workspace script metadata](/concepts/workspace-script-metadata.md), such as environment variables available in scripts and interpolating values in inline scripts and args such as `<workspaceName>`.<br />

### .determineAffectedWorkspaces

`determineAffectedWorkspaces(options: DetermineAffectedWorkspacesOptions): Promise<AffectedWorkspacesResult>`

Determine the workspaces that are affected by a change. The return object
is the same as the CLI's output for `list-affected --explain --json`.

Using git diff to determine affected workspaces:


````
// Workspace results contain details about each workspace,
// including whether it is affected and why
const { workspaceResults } = await project.determineAffectedWorkspaces({
  // Optional, the script to run to determine affected workspaces
  // When not provided, based on workspaces' default inputs
  script: "my-script",
  diffSource: "git",
  diffOptions: {
    // Optional, defaults to main if default base ref not configured
    baseRef: "my-branch-a",
    // Optional, defaults to current HEAD if not provided
    headRef: "my-branch-b",

    // Optional means of ignoring uncommitted changes
    // gitignored files are never included in a diff
    ignoreUntracked: false, // files that may be tracked but aren't
    ignoreStaged: false,
    ignoreUnstaged: false,
    // Ignores untracked, staged, and unstaged
    ignoreUncommitted: false,
  },
  // Ignore workspace dependencies when determining affected workspaces
  ignoreWorkspaceDependencies: false,
  // Ignore changes external dependencies (e.g. react, lodash) lock versions
  ignoreExternalDependencies: false,
});
````

Using a list of changed files to determine affected workspaces:


````
const { workspaceResults } = await project.determineAffectedWorkspaces({
  // Bypass git and pass a list of changed files that match inputs
  diffSource: "fileList",
  changedFiles: ["src/**/*.ts", "something.txt"],
});
````

#### More Info

- See more on [affected workspaces](/concepts/affected.md).
- See more on [inputs](/concepts/inputs.md) that determine if a workspace is affected.


---


### .runAffectedWorkspaceScript

`runAffectedWorkspaceScript(options: RunAffectedWorkspaceScriptOptions): Promise<RunScriptAcrossWorkspacesResult>`

Run a script in the workspaces that are affected by a change.

This behaves similarly to [runScriptAcrossWorkspaces](/api/reference.md#runscriptacrossworkspaces),
while also taking similar options to [determineAffectedWorkspaces](/api/reference.md#determineaffectedworkspaces).


````
// Returns the same output and summary as project.runScriptAcrossWorkspaces
const { output, summary } = await project.runAffectedWorkspaceScript({
  // About the same options as project.determineAffectedWorkspaces
  affectedOptions: {
    diffSource: "git",
    diffOptions: {
      baseRef: "my-branch-a",
      headRef: "my-branch-b",
    },
  },
  // About the same options as project.runScriptAcrossWorkspaces
  scriptOptions: {
    script: "my-script",
  },
});
````

#### More Info

- See more on [affected workspaces](/concepts/affected.md).
- See more on [inputs](/concepts/inputs.md) that determine if a workspace is affected.


---


### .verify

`verify(options: VerifyOptions): Promise<VerifyResult>`

Verify the project for issues. The result is the same
as the CLI [`verify`](/cli/commands.md#verify) command's JSON output.

You can read more about the verify feature [here](/concepts/verify.md).


````
// Analog to the CLI verify command
const results = await project.verify({
  // Optional: (default false) When true,
  // treat warnings as errors
  strict: false,
  // Optional: workspace patterns to scope verification to
  workspacePatterns: ["*"],
});
````

## createMemoryProject

Experimental

`createMemoryProject(options: CreateMemoryProjectOptions): MemoryProject`

Create a [Project](/api/reference.md#project) from a given array of [Workspaces](/api/reference.md#workspace).

Usually used  only for testing purposes to do without the need for a real project
in the file system.

Since it doesn't read anything from the file system,
it isn't affected by [project configuration](/config/project.md) or [workspace configurations](/config/workspace.md).

A `MemoryProject` currently does not support running scripts directly, though a means of mocking script execution may be added later, considering demand.


````
import { createMemoryProject } from "pacwich";

const testProject = createMemoryProject({
  packageManager: "npm", // required
  rootDirectory: "test-project-directory", // optional
  name: "test-project", // optional
  workspaces: [
    {
      name: "my-test-workspace",
      isRoot: false,
      path: "my/test/workspace/path",
      matchPattern: "my/test/workspace/pattern/*",
      scripts: ["my-test-script"],
      aliases: ["test-alias"],
      dependencies: [],
      dependents: [],
      externalDependencies: [],
    }
  ]
});
````

## setLogLevel

`setLogLevel(level: LogLevelSetting)`

Set the global logging level. Defaults to "info" or "error" when `NODE_ENV`
 is "test".
The default log level can be set with the `PACWICH_LOG_LEVEL` environment variable.

````
import { setLogLevel } from "pacwich";

setLogLevel("debug");
setLogLevel("info") // default
setLogLevel("warn");
setLogLevel("error") // default when NODE_ENV is "test"
setLogLevel("silent");
````

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /config/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /config/index.md.

# Configuration: Overview

Configuration is set by JSON. Config files can be written in TypeScript, JavaScript, JSON, or JSONC.

See [Project Configuration](/config/project.md) and [Workspace Configuration](/config/workspace.md) for more information on the purpose of each field.

## Quick Examples

### Project Configuration

The [project configuration](/config/project.md) is for project-wide settings.


````
// path/to/your/project/pacwich.project.ts

import { defineProjectConfig } from "pacwich/config";

export default defineProjectConfig({
  defaults: {
    parallelMax: 4,
    affectedBaseRef: "my-branch"
  },
  workspacePatternConfigs: [
    {
      patterns: [
        "path:libraries/frontend/**/*"
      ],
      config: {
        tags: [
          "frontend",
          "library"
        ]
      }
    }
  ]
});
````

### Workspace Configuration

[Workspace configurations](/config/workspace.md) are defined in the directory of a workspace.


````
// path/to/your/project/workspace/pacwich.workspace.ts

import { defineWorkspaceConfig } from "pacwich/config";

export default defineWorkspaceConfig({
  alias: "myApp",
  tags: [
    "my-tag"
  ],
  scripts: {
    start: {
      order: 10
    },
    test: {
      order: 20
    }
  },
  rules: {
    workspaceDependencies: {
      allowPatterns: [
        "my-workspace-a",
        "tag:my-tag",
        "path:my-path/**/*",
        "not:tag:my-excluded-tag"
      ]
    }
  }
});
````

## Config Locations / File Types

### Configuration locations

Configuration files can be read from the following location. The first to be resolved in this order will be used:


1. **TypeScript file**: `pacwich.<name>.ts`
1. **JavaScript file**: `pacwich.<name>.js`
1. **JSONC file**: `pacwich.<name>.jsonc`
1. **JSON file**: `pacwich.<name>.json`
1. **package.json key**: `package.json["<key>"]`


### Value Resolution

Values related to configuration are resolved in the following order of precedence:

1. An explicit CLI or API argument/option passed to a method/function/command
2. A value provided in a configuration file
3. A value provided via an [environment variable](/config/env-vars.md), if applicable
4. The generic default value, if applicable


---


## Debugging Configuration

You can use the CLI command `pacwich config debug` to print all resolved JSON for configuration.

See the [CLI reference](/cli/commands.md#config-debug) for more information.


---


## Security and Performance of TypeScript/JavaScript configs

Keep in mind that TypeScript and JavaScript config files offer the most power and flexibility but both execute code and
can affect `pacwich`'s performance if configs are slow to resolve.

### Performance

The average `pacwich` project that uses config straightforwardly should not experience performance issues due to TS/JS config,
unless very heavy processing or `async` logic is used within them. Keep in mind that slow config files will slow down all `pacwich` operations, including shell completions that are project-aware.

If you happen to need dynamic configs that slow down `pacwich`, consider using a separate process to generate JSON/JSONC configs dynamically
to take the load off of `pacwich`'s resolution.

### Security

If you may be interacting with `pacwich`
 monorepos that are untrusted, you can set [environment variable](/config/env-vars.md)
 `PACWICH_DISABLE_EXECUTABLE_CONFIGS_DEFAULT`
to `true`
 to disable loading TS/JS config files altogether. There is also the CLI [global flag](/cli/global-options.md#disable-executable-configs)
 for this.
Of course, a malicious repository already has a large variety of attack vectors beyond just a `pacwich`
 config, but
this exists as an optional guard against arbitrary code execution.

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /config/workspace/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /config/workspace/index.md.

# Configuration: Workspace Config File

The optional configuration for a workspace is defined in a file such as `pacwich.workspace.ts` in its directory or in its `package.json`
 file.
You can also use the project config to set workspace configs in bulk by using workspace patterns.
See the [**workspace pattern configs**](/config/workspace-pattern-configs.md) page for more information.

## Type Definition


````
{
  // Must be unique across other aliases and workspace names
  alias?: string | string[],
  // Tags can be used to group workspaces together
  tags?: string[],
  // Inputs for affected workspace resolution
  defaultInputs?: {
    // Default is all git-trackable files in the workspace directory
    files?: string[],
    // Workspaces to treat like dependencies
    workspacePatterns?: string[],
    // Dependency names (e.g. "react") to treat as dependencies (default: all)
    externalDependencies?: string[]
  },
  scripts?: {
    [script: string]: {
      // Optional sorting order for running scripts
      order?: number,
      // Inputs for affected workspace resolution
      inputs?: {
        // Default is all git-trackable files in the workspace directory
        files?: string[],
        // Workspaces to treat like dependencies
        workspacePatterns?: string[],
        // Dependency names (e.g. "react") to treat as dependencies (default: all)
        externalDependencies?: string[]
      }
    }
  },
  verify?: {
    workspaceDependencies?: {
      // Ignore these input files for verification of workspace dependencies.
      // These are relative to the workspace directory.
      // Using a leading slash will match from the project root.
      ignoreInputFiles?: string[],
      // Ignore imports/exports from these workspaces
      ignoreImportsFromWorkspacePatterns?: string[],
      // When true, treat workspace dependencies that are only declared by an ancestor workspace as an error in strict verify mode
      strictDisallowAncestorWorkspaceDeps?: boolean
    }
  },
  rules?: {
    workspaceDependencies?: {
      // Use workspace patterns to match workspaces to allow as dependencies
      allowPatterns?: string[],
      // Workspace patterns to forbid as dependencies.
      // When combined with allowPatterns, filters within that allowed subset.
      denyPatterns?: string[]
    }
  }
}
````


---


### Alias

**Aliases** are an alternate name or names for a workspace. See the [workspace aliases](/concepts/workspace-aliases.md) page for more information.


---


### Tags

**Tags** are simple strings that can be used to group workspaces together. They can be used
in [workspace patterns](/concepts/workspace-patterns.md).


---


### Default Inputs

The `defaultInputs` used to determine which files are considered inputs for the workspace,
such as for [affected workspaces](/concepts/affected.md) resolution. These are applied to all
scripts in the workspace that don't configure their own inputs (see below).

See the [inputs](/concepts/inputs.md) page for more information.


---


### Scripts

A map of script names to config specific to any respective script.
Inline workspaces can use an [optional name](/concepts/inline-scripts.md#script-name) to be matched.

#### Order

The `scripts[name].order` option is used to set the [script execution order](/concepts/script-execution-order.md) for scripts.

#### Inputs

The `scripts[name].inputs` option is used to set the inputs for the script, such as for [affected workspaces](/concepts/affected.md) resolution.

See the [inputs](/concepts/inputs.md) page for more information.


---


### Verify

See the [verify](/concepts/verify.md) page for more information on this feature.

- `verify.workspaceDependencies.ignoreInputFiles`: Ignore these [input files](/concepts/inputs.md) for verification of workspace dependencies.
- `verify.workspaceDependencies.ignoreImportsFromWorkspacePatterns`: Ignore imports/exports from these workspaces, using [workspace patterns](/concepts/workspace-patterns.md).
- `verify.workspaceDependencies.strictDisallowAncestorWorkspaceDeps`: When `true`, strict mode will fail on ancestor workspace dependencies instead of just warning.

The same options can be used in the [project config](/config/project.md). Workspace verify configuration
is additive with the project-level config.


---


### Workspace Dependency Rules

Using the `rules.workspaceDependencies` field, you can define rules for which workspaces are allowed to be dependencies,
using `allowPatterns`, `denyPatterns`, or both.

[Workspace patterns](/concepts/workspace-patterns.md) are used to match workspaces.

`allowPatterns` defines the permitted subset of dependencies. `denyPatterns` forbids specific dependencies.
When both are present, `denyPatterns` further filters within the subset permitted by `allowPatterns`.
You can also use [negated](/concepts/workspace-patterns.md#negation) workspace patterns to exclude workspaces from the allowed or denied list.

For example, you may disallow dependencies with the [tag](/config/workspace.md#tags) "backend" for a frontend workspace with `denyPatterns: ["tag:backend"]`.

[Workspace dependencies](/concepts/workspace-dependencies.md) are explicitly defined in workspaces' `package.json` files.


---


## Examples:

### 1. TypeScript/JavaScript file

`path/to/your/workspace/
pacwich.workspace.ts`
or
`path/to/your/workspace/
pacwich.workspace.js`

````
import { defineWorkspaceConfig } from "pacwich/config";

export default defineWorkspaceConfig({
  alias: "myApp",
  tags: [
    "my-tag"
  ],
  scripts: {
    start: {
      order: 10
    },
    test: {
      order: 20
    }
  },
  rules: {
    workspaceDependencies: {
      allowPatterns: [
        "my-workspace-a",
        "tag:my-tag",
        "path:my-path/**/*",
        "not:tag:my-excluded-tag"
      ]
    }
  }
});
````

#### `mergeWorkspaceConfig` Utility

You can use the `mergeWorkspaceConfig` function to merge multiple workspace configurations left to right, with each subsequent config taking precedence.
Arrays are concatenated while keeping items unique, while inputs (`defaultInputs` and `scripts[name].inputs`) are replaced entirely rather than merged.


````
import { mergeWorkspaceConfig } from "pacwich/config";

export default mergeWorkspaceConfig(
  {
    alias: "a",
    tags: ["x"],
    defaultInputs: { files: ["src/**/*.ts", "package.json"] },
    scripts: {
      build: { order: 1, inputs: { files: ["src/**/*.ts"] } },
      test: { order: 2 },
    },
    rules: { workspaceDependencies: { allowPatterns: ["tag:lib"] } },
    verify: { workspaceDependencies: { ignoreInputFiles: ["scripts/**/*"] } },
  },
  {
    alias: "b", // concatenated with "a"
    tags: ["x", "y"], // "x" deduplicated
    // whole object replaces the first config's defaultInputs
    defaultInputs: { files: ["src/**/*.ts", "!src/**/*.test.ts"] },
    scripts: {
      // build.order kept from the first config, but inputs is replaced
      // as a whole object ("src/**/*.ts" is gone unless restated)
      build: { inputs: { files: ["src/index.ts"] } },
    },
    rules: { workspaceDependencies: { denyPatterns: ["tag:app"] } },
    verify: {
      workspaceDependencies: {
        ignoreInputFiles: ["scripts/**/*", "legacy/**/*"], // concat + dedupe
        ignoreImportsFromWorkspacePatterns: ["tag:internal"],
      },
    },
  },
  // factory form reads the accumulated config so far
  (prevConfig) => ({
    tags: prevConfig.tags?.includes("y") ? ["frontend"] : [],
  }),
);

// result: {
//   alias: ["a", "b"],
//   tags: ["x", "y", "frontend"],
//   defaultInputs: { files: ["src/**/*.ts", "!src/**/*.test.ts"] },
//   scripts: {
//     build: { order: 1, inputs: { files: ["src/index.ts"] } },
//     test: { order: 2 },
//   },
//   rules: {
//     workspaceDependencies: {
//       allowPatterns: ["tag:lib"],
//       denyPatterns: ["tag:app"],
//     },
//   },
//   verify: {
//     workspaceDependencies: {
//       ignoreInputFiles: ["scripts/**/*", "legacy/**/*"],
//       ignoreImportsFromWorkspacePatterns: ["tag:internal"],
//     },
//   },
// }
````

### 2. JSON/JSONC file

`path/to/your/workspace/
pacwich.workspace.json`
or
`path/to/your/workspace/
pacwich.workspace.jsonc`

````
{
  "alias": "myApp",
  "tags": [
    "my-tag"
  ],
  "scripts": {
    "start": {
      "order": 10
    },
    "test": {
      "order": 20
    }
  },
  "rules": {
    "workspaceDependencies": {
      "allowPatterns": [
        "my-workspace-a",
        "tag:my-tag",
        "path:my-path/**/*",
        "not:tag:my-excluded-tag"
      ]
    }
  }
}
````

### 3. package.json

`path/to/your/workspace/package.json
`

````
{
  "name": "@my-organization/my-application",
  "description": "My app",
  "version": "1.0.0",
  "pacwich": {
    "alias": "myApp",
    "tags": [
      "my-tag"
    ],
    "scripts": {
      "start": {
        "order": 10
      },
      "test": {
        "order": 20
      }
    },
    "rules": {
      "workspaceDependencies": {
        "allowPatterns": [
          "my-workspace-a",
          "tag:my-tag",
          "path:my-path/**/*",
          "not:tag:my-excluded-tag"
        ]
      }
    }
  }
}
````

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /config/project/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /config/project/index.md.

# Configuration: Project Config File

The optional project configuration is the general configuration for a [project](/concepts/glossary.md#project)
 at a file such as `pacwich.project.json` or in its `package.json`
 file.
## Type Definition


````
type ProjectConfig = {
  // The package manager to use for the project
  packageManager?: "bun" | "pnpm" | "npm" | "auto",
  defaults?: {
    // The default output style for CLI scripts
    cliScriptOutputStyle?: "grouped" | "prefixed" | "plain" | "none",
    // The default maximum number of scripts that can run in parallel
    parallelMax?: number | `${number}%` | "auto" | "unbounded" | "default",
    // The default shell to use for inline scripts
    shell?: "bun" | "system" | "default",
    // Whether to include the root workspace in the workspace list
    includeRootWorkspace?: boolean,
    // The default git base ref for affected workspaces (default: main)
    affectedBaseRef?: string
  },
  verify?: {
    workspaceDependencies?: {
      // Ignore these input files for verification of workspace dependencies
      ignoreInputFiles?: string[],
      // Ignore imports/exports from these workspaces
      ignoreImportsFromWorkspacePatterns?: string[],
      // When true, treat workspace dependencies that are only declared by an ancestor workspace as an error in strict verify mode
      strictDisallowAncestorWorkspaceDeps?: boolean
    }
  },
  // Apply workspace configs in bulk by using workspace patterns
  workspacePatternConfigs?: {
    patterns?: string[],
    config?: WorkspaceConfig | WorkspacePatternConfigFactory
  }[]
}
````


---


### Defaults

The values in `config.defaults` can also be set by [environment variables](/config/env-vars.md)
. Configuration values take precedence over environment variables.
- <code>{ENV_VARS_METADATA.cliScriptOutputStyleDefault.projectConfigDefaultsKey}</code>: The [output style](/cli/commands.md#run-script) to use for workspace scripts. The default is "grouped" when on a TTY, which always falls back to "prefixed" on non-TTY terminals. Otherwise, it is "prefixed". Other options are "plain" and "none".
- <code>{ENV_VARS_METADATA.parallelMaxDefault.projectConfigDefaultsKey}</code>: The [parallel max value](/concepts/parallel-scripts.md#parallel-max-value)
- <code>{ENV_VARS_METADATA.scriptShellDefault.projectConfigDefaultsKey}</code>: The [shell option for inline scripts](/concepts/inline-scripts.md#shell)
- <code>{ENV_VARS_METADATA.includeRootWorkspaceDefault.projectConfigDefaultsKey}</code>: Whether to include the [root workspace](/concepts/root-workspace.md) in the project's workspaces list
- <code>{ENV_VARS_METADATA.affectedBaseRefDefault.projectConfigDefaultsKey}</code>: The default git base ref for [affected workspaces](/concepts/affected.md) resolution
  (this is <code>main</code> when not overridden)


---


### Verify

See the [verify](/concepts/verify.md) page for more information on this feature.

- `verify.workspaceDependencies.ignoreInputFiles`: Ignore these [input files](/concepts/inputs.md) for verification of workspace dependencies, relative to the project root.
- `verify.workspaceDependencies.ignoreImportsFromWorkspacePatterns`: Ignore imports/exports from these workspaces, using [workspace patterns](/concepts/workspace-patterns.md).
- `verify.workspaceDependencies.strictDisallowAncestorWorkspaceDeps`: When `true`, strict mode will fail on ancestor workspace dependencies instead of just warning.

The same options can be used in [workspace configs](/config/workspace.md). Workspace verify configuration
is additive with the project-level config.


---


### Workspace Pattern Configs

You can set workspace configs in bulk by using workspace patterns in `workspacePatternConfigs`.

See the [workspace pattern configs](/config/workspace-pattern-configs.md) page for more information.


---


## Examples:

### 1. TypeScript/JavaScript file

`path/to/your/project/
pacwich.project.ts`
or
`path/to/your/project/
pacwich.project.js`

````
import { defineProjectConfig } from "pacwich/config";

export default defineProjectConfig({
  defaults: {
    parallelMax: 4,
    affectedBaseRef: "my-branch"
  },
  workspacePatternConfigs: [
    {
      patterns: [
        "path:libraries/frontend/**/*"
      ],
      config: {
        tags: [
          "frontend",
          "library"
        ]
      }
    }
  ]
});
````

#### `mergeProjectConfig` Utility

You can use the `mergeProjectConfig` function to merge multiple project configurations left to right, with each subsequent config taking precedence.
Fields under `defaults` merge individually, `workspacePatternConfigs` entries are concatenated, and `verify` arrays are concatenated while keeping items unique.


````
import { mergeProjectConfig } from "pacwich/config";

export default mergeProjectConfig(
  {
    packageManager: "bun",
    defaults: { parallelMax: 4, shell: "system" },
    workspacePatternConfigs: [
      { patterns: ["path:packages/apps/**/*"], config: { tags: ["app"] } },
    ],
    verify: {
      workspaceDependencies: {
        ignoreInputFiles: ["scripts/codegen/**/*"],
        ignoreImportsFromWorkspacePatterns: ["tag:legacy"],
      },
    },
  },
  {
    // fields under defaults merge individually: parallelMax overridden, shell kept
    defaults: { parallelMax: 8 },
    // appended after the first config's entries
    workspacePatternConfigs: [
      { patterns: ["tag:app"], config: { tags: ["deployable"] } },
    ],
    verify: {
      workspaceDependencies: {
        // "scripts/codegen/**/*" deduplicated, "legacy/**/*.ts" appended
        ignoreInputFiles: ["scripts/codegen/**/*", "legacy/**/*.ts"],
        strictDisallowAncestorWorkspaceDeps: true,
      },
    },
  },
  // factory form reads the accumulated config so far
  (prevConfig) => ({
    defaults: { includeRootWorkspace: prevConfig.packageManager === "bun" },
  }),
);

// result: {
//   packageManager: "bun",
//   defaults: { parallelMax: 8, shell: "system", includeRootWorkspace: true },
//   workspacePatternConfigs: [<app entry>, <deployable entry>],
//   verify: {
//     workspaceDependencies: {
//       ignoreInputFiles: ["scripts/codegen/**/*", "legacy/**/*.ts"],
//       ignoreImportsFromWorkspacePatterns: ["tag:legacy"],
//       strictDisallowAncestorWorkspaceDeps: true,
//     },
//   },
// }
````

### 2. JSON/JSONC file

`path/to/your/project/
pacwich.project.json`
or
`path/to/your/project/
pacwich.project.jsonc`

````
{
  "defaults": {
    "parallelMax": 4,
    "affectedBaseRef": "my-branch"
  },
  "workspacePatternConfigs": [
    {
      "patterns": [
        "path:libraries/frontend/**/*"
      ],
      "config": {
        "tags": [
          "frontend",
          "library"
        ]
      }
    }
  ]
}
````

### 3. package.json

`path/to/your/project/package.json
`

````
{
  "name": "my-project",
  "description": "My project root",
  "workspaces": [
    "packages/*"
  ],
  "pacwich-project": {
    "defaults": {
      "parallelMax": "50%",
      "shell": "bun",
      "includeRootWorkspace": true,
      "affectedBaseRef": "my-branch"
    }
  }
}
````

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /config/workspace-pattern-configs/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /config/workspace-pattern-configs/index.md.

# Configuration: Workspace Pattern Configs

You can use the [project config](/config/project.md#workspace-pattern-configs) to set [workspace configs](/config/workspace.md) in bulk by using [workspace patterns](/concepts/workspace-patterns.md).

Entries' configs will be merged with any existing workspaces' local configs, and each subsequent entry's config will be merged with
the accumulated config from any similarly matching previous entries, using
the same behavior as [`mergeWorkspaceConfig`](/config/workspace.md#mergeworkspaceconfig-utility).

Since [workspace patterns](/concepts/workspace-patterns.md) are affected by config, such as using [tags](/config/workspace.md#tags),
each entry's patterns will match against the accumulated config from the previous entries.

### Example Project Config


````
// pacwich.root.ts

import { defineProjectConfig } from "pacwich/config";

export default defineProjectConfig({
  workspacePatternConfigs: [
    { 
      // Any matching workspaces under this path
      // will have their local config merged with this one
      patterns: ["path:libraries/frontend/**/*"],
      config: {
        tags: ["frontend"],
      },
    },
    {
      patterns: ["path:libraries/backend/**/*"],
      config: {
        tags: ["backend"],
      },
    },
    {
      // This tag can be matched thanks to the first entry,
      // merging the accumulated config with this one
      patterns: ["tag:frontend"],
      config: {
        rules: {
          workspaceDependencies: {
            denyPatterns: ["tag:backend"],
          },
        },
      },
    },
    {
      patterns: ["tag:backend"],
      // You can use the raw workspace data and
      // accumulated config for each workspace via callback
      config: (workspace, prevConfig) => ({
        rules: {
          workspaceDependencies: workspace.name.startsWith("@some-scope/")
          ? {
              denyPatterns: ["@some-other-scope/*"],
            }
          : {
              allowPatterns: ["@some-scope/*"],
            }
        },
      }),
    }
  ],
});
````

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /config/env-vars/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /config/env-vars/index.md.

# Configuration: Environment Variables

## Settable Environment Variables

Set these environment variables to override default values used. The [project configuration](/config/project.md) will take precedence over environment variables,
and any values set explicitly in CLI or API arguments will take precedence over both.


- `PACWICH_PACKAGE_MANAGER`The package manager to use. This overrides config and environment variable settings.
- `PACWICH_LOG_LEVEL`The default [log level](/cli/global-options#log-level) (`debug`, `info`, `warn`, `error`, or `silent`), used when the `--log-level` CLI flag is not passed. This is `info` when not overridden.
- `PACWICH_SUPPRESS_WARNINGS`Suppress warning logs by WarningId as a comma-separated list. See the [warnings page](/config/warnings) for a full list and other means of setting suppression.
- `PACWICH_CLI_SCRIPT_OUTPUT_STYLE_DEFAULT`The default output style for running scripts via the CLI, when no value is provided to the [CLI](/cli/commands#run-script) arguments. The "grouped" output is only available on a TTY and otherwise falls back to "prefixed". Otherwise "plain" and "none" are accepted.If `config.defaults.cliScriptOutputStyle` is set in the [project configuration](/config/project), it will take precedence.
- `PACWICH_PARALLEL_MAX_DEFAULT`The default [parallel max](/concepts/parallel-scripts#parallel-max-value) for running scripts, when no value is provided to the [CLI](/cli/commands#run-script) or [API](/api/reference#runscriptacrossworkspaces) arguments.If `config.defaults.parallelMax` is set in the [project configuration](/config/project), it will take precedence.
- `PACWICH_SHELL_DEFAULT`The default shell for running [inline scripts](/concepts/inline-scripts), when no value is provided to the [CLI](/cli/commands#run-script) or [API](/api/reference#runscriptacrossworkspaces) arguments.If `config.defaults.shell` is set in the [project configuration](/config/project), it will take precedence.
- `PACWICH_INCLUDE_ROOT_WORKSPACE_DEFAULT`Whether to include the [root workspace](/concepts/root-workspace) as a normal workspace.If `config.defaults.includeRootWorkspace` is set in the [project configuration](/config/project), it will take precedence.
- `PACWICH_AFFECTED_BASE_REF_DEFAULT`The default git base ref for affected workspace resolution. This is `main` when not overridden.If `config.defaults.affectedBaseRef` is set in the [project configuration](/config/project), it will take precedence.
- `PACWICH_DISABLE_EXECUTABLE_CONFIGS_DEFAULT`Whether to disable loading executable configs (TS/JS), mainly for untrusted contexts. This is `false` when not overridden.

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /config/warnings/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /config/warnings/index.md.

# Warnings

You can suppress warnings via:

- The [environment variable](/config/env-vars.md) <code>{getUserEnvVarName('suppressWarnings')}</code>, a comma-separated list of warning ids,
- The `--suppress-warnings` [CLI global option](/cli/global-options.md#suppress-warnings), which is unioned with the environment variable.

Warnings are a process-level concern rather than a project setting, so there is no project config or TS API option for suppression.

## All Warning IDs


- `BashLoginShellHint`
- `BunLockNewerVersion`
- `BunLockParseFailed`
- `DependencyCycleDetected`
- `DeprecatedBunWorkspacesFlag`
- `DeprecatedListAffectedCliCommand`
- `DeprecatedNoPrefixFlag`
- `DeprecatedProjectMapMethod`
- `DeprecatedRunAffectedCliCommand`
- `IgnoreInputFilesNegationNotHonored`
- `InputPatternOutsideProject`
- `InvalidCliScriptOutputStyleEnvVar`
- `InvalidPackageManagerEnvVar`
- `MissingWorkspacesHint`
- `MultipleConfigsFound`
- `MultiplePackageManagerLockfiles`
- `NpmLockNewerVersion`
- `NpmLockParseFailed`
- `ParallelExceedsAvailableCpus`
- `PnpmLockNewerVersion`
- `PnpmLockParseFailed`
- `PnpmWorkspacesFieldIgnored`
- `UnsupportedPackageManagerVersion`
- `UnsupportedRuntime`
- `VerifyIssue`
- `VerifyIssue.AncestorWorkspaceDependency`
- `VerifyIssue.ImplicitWorkspaceDependency`

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /concepts/glossary/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /concepts/glossary/index.md.

# Glossary

Learn some of the basic terms and primitives of `pacwich` here.

## Terms

The definitions of **workspace** and **project** differ between package managers and monorepo tooling.

### Workspace

In `pacwich`, the word **workspace** is closer to how it's used in **npm** and **Bun**, a **workspace** being a **nested package** in a monorepo.

Not necessarily all packages are workspaces, but all workspaces are packages.

A workspace must have its own `package.json` file with a unique `"name"`. It is matched via globs you declare with your package manager's config (e.g. the `"workspaces"` field
in your root package.json for [Bun](https://bun.sh/docs/pm/workspaces) or [npm](https://docs.npmjs.com/cli/v11/using-npm/workspaces), or [pnpm-workspace.yaml](https://pnpm.io/workspaces)).

### Project

The **project** is synonymous with your root where workspaces are defined, often the root of your git repository.

This is where your top-level `package.json` file is located and where you've defined workspaces for your package manager,
whether via the `"workspaces"` field in package.json (for Bun or npm) or `pnpm-workspace.yaml` (for pnpm).

`pacwich` recognizes a project by a root `package.json` living alongside a lockfile (`package-lock.json`, `bun.lock`, `pnpm-lock.yaml`), since the
lockfile is the best source of truth for workspace-related data, so a project and its workspace data aren't recognized or current until you run your install command.

### Script

In the context of `pacwich`, a **script** generally refers to an entry in the `"scripts"` field in a workspace's `package.json` file by default.

However, pacwich also supports running ["inline scripts"](/concepts/inline-scripts.md), one-off shell commands executed from a respective workspace's directory.

### Inputs

Inputs define what items are considered to affect the state of a workspace or the result of a script
and are used in [determining affected workspaces](/concepts/affected.md) and the [`verify` feature](/concepts/verify.md).

Read more on the [Inputs](/concepts/inputs.md) page.

## Terms in Action

This is a minimal example of a project structure for a monorepo. As advertised, `pacwich` would
be able to work in this project without additional setup.

Placing workspaces in the `packages/` directory is a common convention but not required.

#### File Tree


````
my-project/
├── package.json
└── packages/
    ├── my-workspace-a/
    |   ├── index.ts
    |   └── package.json
    └── my-workspace-b/
        ├── index.ts
        └── package.json
````

#### Top-level files

The root `package.json`, using the `"workspaces"` field if using **Bun** or **npm**:


````
{
  "name": "my-project",
  "workspaces": [
    "packages/*"
  ]
}
````

If using **pnpm**, you would have a `pnpm-workspace.yaml` file instead of using the `"workspaces"` field in the root `package.json` above:


````
# pnpm-workspace.yaml
packages:
  - 'packages/*'
````

#### Workspaces

##### my-workspace-a


````
{
  "name": "my-workspace-a",
  "type": "module",
  "main": "index.ts",
  "scripts": {
    "my-script": "echo 'My script for workspace A'"
  }
}
````

`my-workspace-a`'s default [**inputs**](/concepts/inputs.md) would be its `package.json`
file, and its `index.ts` file. If it [depended on another workspace](/concepts/workspace-dependencies.md),
that workspace's inputs would be inherited, and if it had external dependencies (e.g. npm packages),
those dependencies' installed versions would be inputs as well.

##### my-workspace-b


````
{
  "name": "my-workspace-b",
  "type": "module",
  "main": "index.ts",
  "scripts": {
    "my-script": "echo 'My script for workspace B'"
  }
}
````

`my-workspace-b`'s default [**inputs**](/concepts/inputs.md) would be its `package.json`
file, and its `index.ts` file. If it [depended on another workspace](/concepts/workspace-dependencies.md),
that workspace's inputs would be inherited, and if it had external dependencies (e.g. npm packages),
those dependencies' installed versions would be inputs as well.

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /concepts/verify/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /concepts/verify/index.md.

# Verify

The `verify` feature exists to help detect issues with a project.

## Detecting Missing Workspace Dependencies

`pacwich` uses workspaces' `package.json` files to detect when a workspace depends on another workspace.

`pacwich` is relatively unopinionated, but it is **highly encouraged** for workspaces to always declare
other workspaces as dependencies explicitly in their own `package.json`. The `verify` feature exists to help catch instances where this can be dodged.

The `verify` feature performs simple analysis to detect imports/exports in JS/TS files from other workspaces not listed in a workspace's `package.json`.

Analysis is only performed on workspace [input files](/concepts/inputs.md). You can further configure the verify
command's behavior at the [project level](/config/project.md#verify) or [workspace level](/config/workspace.md#verify).

### Types of Issues

In **Bun** and **pnpm**, explicit dependencies are required to import/export from another workspace, by adding `"my-workspace": "workspace:*"` to `package.json` dependencies. **npm** workspaces do not require explicit `package.json` dependencies at all, so undeclared workspace imports simply work.

Nested workspaces also create a gap in explicit dependencies. A dependency declared by an ancestor workspace, most commonly the root `package.json`, resolves for every workspace beneath it through recursive parent-directory `node_modules` lookup, whether or not the importing workspace declares it.

The `verify` feature performs simple analysis of imports/exports in JS/TS files to catch both cases:

- **Implicit workspace dependencies**: a workspace imports another workspace that neither it nor any ancestor declares. Generally only possible with npm workspaces.
- **Ancestor workspace dependencies**: the import resolves only because an ancestor workspace declares it. Possible with any package manager.

Adding `pacwich verify` to a `"prepare"` script, pre-commit hook, CI pipeline, or similar can be especially helpful to catch issues.

`pacwich verify --strict` will fail on implicit workspace dependencies. Ancestor findings warn by default, and the `strictDisallowAncestorWorkspaceDeps` [config option](/config/project.md#verify) makes strict mode fail on those as well.

## Usage

Adding `pacwich verify` to your root `package.json` `"prepare"` script, a pre-commit hook, or a CI pipeline can be especially helpful to catch issues.

`pacwich verify --strict` will fail if implicit workspace dependencies are detected or ancestor workspace dependencies are detected and disallowed via the `strictDisallowAncestorWorkspaceDeps` [config option](/config/project.md#verify).

See the [CLI reference](/cli/commands.md#verify) or the [API reference](/api/reference.md#verify) for more information.

**Example output**:

```
$ pacwich verify
[pacwich WARN: VerifyIssue.AncestorWorkspaceDependency]: Workspace "a" imports "b" 
but does not declare it as a dependency (packages/a/hello.ts:1). It only resolves 
because ancestor workspace "my-root" declares it.
Add "b": "workspace:*" to the "dependencies" field of packages/a/package.json.
Alternatively, if this is intentional, add "b" to 
"verify.workspaceDependencies.ignoreImportsFromWorkspacePatterns".
Verify finished with 1 warning.
```

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /concepts/inputs/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /concepts/inputs/index.md.

# Inputs

## What is an Input?

**Inputs** are values considered to affect the state of a [**workspace**](/concepts/glossary.md#workspace) or the result of a [**script**](/concepts/glossary.md#script).

These can be configured via [workspace config](/config/workspace.md) options, which can be set at
the workspace level (`defaultInputs`) or at the script level (`scripts[name].inputs`).

Inputs are used for determining [affected workspaces](/concepts/affected.md) and the [verify](/concepts/verify.md) feature.

A workspace's inputs can include its **files**, **other workspaces**, or **external dependencies**,
defined in depth below:

### Files

A **file** can be an input, which **must be git-trackable** (not ignored and within your repo).

**Default**: All git-trackable files in a workspace's directory

Notes:

Files that are staged, unstaged, or untracked (but not ignored) are inputs by default but can usually be selectively excluded in features.

If a workspace is nested within another workspace, the parent workspace's input files cannot be in the nested workspace.
This is usually relevant when including the [root workspace](/concepts/root-workspace.md) as a normal workspace.

#### Configuring Files

Files are specified as paths relative to the workspace's directory.
Paths with a leading `/` are relative to the project root. Prefix with `!` to exclude.

[Workspace configuration](/config/workspace.md) example:


````
// /path/to/your/project/workspace/pacwich.workspace.ts

import { defineWorkspaceConfig } from "pacwich/config";

export default defineWorkspaceConfig({
  // workspace's defaults
  "defaultInputs": {
    "files": [
      "src/**/*.ts", 
      "!src/**/*.test.ts", // ignore test files
      "/tsconfig.json" // relative to project root
    ],
  },
  // per-script
  "scripts": {
    "test": {
      "inputs": {
        "files": [
          "src/**/*.ts"
        ],
      },
    },
  },
});
````

### Other Workspaces

Another **workspace** may be an input.

**Default**: All workspaces declared as dependencies in `package.json`

A workspace input may be a dependency on another workspace declared in `package.json`,
or a workspace explicitly configured to be an input (see below).

A workspace is affected if one of its workspace inputs is affected. You can also think of this as a workspace inheriting the inputs of any workspaces it depends on.

#### Configuring Workspace Inputs

In features using inputs, you can generally ignore the automatic inclusion
of `package.json` dependencies if needed.

When you need to treat other workspaces like dependencies,
you can also specify [workspace patterns](/concepts/workspace-patterns.md) to be considered inputs to a workspace via the inputs.

[Workspace configuration](/config/workspace.md) example:


````
// /path/to/your/project/workspace/pacwich.workspace.ts

import { defineWorkspaceConfig } from "pacwich/config";

export default defineWorkspaceConfig({
  // workspace's defaults
  "defaultInputs": {
    "workspacePatterns": ["tag:my-tag"],
  },
  // per-script
  "scripts": {
    "build": {
      "inputs": {
        "workspacePatterns": ["path:my-path/**/*"],
      },
    },
  },
});
````

### External Dependencies

The installed version of an **external dependency** (e.g. an npm package)
is considered an input.

**Default**: All external dependencies declared in `package.json`

The resolved version in your package manager lockfile (e.g. `bun.lock`, `package-lock.json`, `yarn.lock`)
is used to determine if an external dependency has changed.

#### Configuring External Dependencies

You can configure a list of specific external package names to consider inputs.

When not provided, all external dependencies are considered inputs. When provided, only the specified dependencies are considered inputs,
so an empty array means no external dependencies are considered inputs.

[Workspace configuration](/config/workspace.md) example:


````
// /path/to/your/project/workspace/pacwich.workspace.ts

import { defineWorkspaceConfig } from "pacwich/config";

export default defineWorkspaceConfig({
  // workspace's defaults
  "defaultInputs": {
    "externalDependencies": ["lodash"],
  },
  // per-script
  "scripts": {
    "build": {
      "inputs": {
        "externalDependencies": ["lodash", "react"],
      },
    },
  },
});
````

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /concepts/workspace-aliases/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /concepts/workspace-aliases/index.md.

# Concept: Workspace Aliases

## Overview

A workspace alias is an alternative name for a workspace that can be used in commands such as [run-script](/cli/commands.md#run-script).

Aliases are validated to be unique to each workspace and to not clash with other workspaces' `package.json` names, so that every
workspace name or alias is an unambiguous reference.

### Example Configuration

Workspace aliases are defined in the [workspace configuration](/config/workspace.md).

In the below examples, `"myApp"` may make a simpler reference to a workspace named `"@my-organization/my-application"`.


````
{
  "alias": "myApp"
}
````

A workspace can have multiple aliases:


````
{
  "alias": [
    "myApp",
    "my-app"
  ]
}
````

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /concepts/workspace-patterns/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /concepts/workspace-patterns/index.md.

# Concept: Workspace Patterns

## Overview

Workspace patterns are used to match workspaces when running commands such as [run-script](/cli/commands.md#run-script) or [list-workspaces](/cli/commands.md#list-workspaces),
and they are also used in some [configuration](/config.md) options.

[Negation](#negation) is supported by prefixing any pattern with `not:` or `!`, the former suggested to avoid shell operator issues. These exclude workspaces from any other patterns provided.

[Regular expressions](#regex-modifier) are supported by prefixing any pattern value with `re:`.

The [`@root` special selector](/concepts/root-workspace.md#referencing-the-root-workspace) matches the [root workspace](/concepts/root-workspace.md).


````
Workspace Pattern Syntax:
[not:][(name|alias|path|tag):][re:]<value>
````

### Quick Examples:


````
"my-name-or-alias" # matches workspace name or alias
"my-name-pattern-*" # matches workspace names only by wildcard
"alias:my-alias-pattern-*" # matches workspace aliases by wildcard
"path:packages/**/*" # matches workspace paths by glob
"tag:my-tag" # matches workspaces with tag
"not:my-name-or-alias" # excludes workspace name or alias
"not:tag:my-tag-pattern-*" # excludes workspace tag matching wildcard
"re:^my-regex-pattern$" # matches workspace name or alias by regex
"not:tag:re:^my-tag-regex-pattern$" # excludes workspace tag by regex
"@root" # matches the root workspace
````

**Workspace patterns are always accepted as a list, and every list is resolved the same way to prevent ambiguity: You need to provide a set of workspaces, and negation only subtracts from the given set.**

This means that `["not:my-workspace"]` on its own matches **nothing**, but `["*", "not:my-workspace"]` would match **all workspaces except "my-workspace"**.

## Default Matching

By default, normal strings match a workspace name or alias.

However, if a wildcard is provided, it will only match against workspace names, to prevent ambiguity.


````
pacwich run lint my-name-or-alias "my-name-pattern-*"
````

See below for how you can use wildcards with aliases.

## Matching Specifiers

Matching specifiers give you more control and options for how you match workspaces.

### Name


Match by the workspace name (from package.json). Accepts wildcards.


````
pacwich ls name:my-workspace "name:my-workspace-*"
pacwich run lint "name:my-workspace-*"
````

### Alias


Match by the [workspace alias](/concepts/workspace-aliases). Accepts wildcards.


````
pacwich ls "alias:my-alias-*"
pacwich run lint "alias:my-alias-b"
````

### Path


Match by the relative workspace path, with glob syntax supported.


````
pacwich ls "path:packages/**/*"
pacwich run lint "path:packages/**/*"
````

### Tag


Match workspaces that have the given [tag](/config/workspace#tags). Tags are defined in a workspace's [configuration file](/config/workspace).


````
pacwich ls "tag:my-tag"
pacwich run lint "tag:my-tag-pattern-*"
````

## Negation

You can negate a pattern by prefixing it with `not:` or `!`.
`not:` is preferred over `!` to avoid shell operator issues.
These exclude workspaces from any other patterns provided.

Negated patterns are removed from the set of matched workspaces, so
a "all workspaces except my-workspace" requires two patterns: `"*"` and `"not:my-workspace"`.


````
# All workspaces except the name or alias "my-name-or-alias"
pacwich ls "*" "not:my-name-or-alias"

# All workspaces except those with the tag "my-tag"
pacwich ls "*" "not:tag:my-tag"
````

## Regex Modifier

You can use the `re:` modifier to match patterns using regular expressions.


````
# All workspaces with names that start with "app-"
pacwich ls "re:^app-.*"

# All workspaces except those with tags that start with "my-tag-"
pacwich ls "*" "not:tag:re:^my-tag-.*"
````

## In the API

These same matching patterns can be used in the API.


````
import { createFileSystemProject } from "pacwich";

const project = createFileSystemProject();

project.findWorkspacesByPattern(
  "my-name-or-alias",
  "name:my-workspace-*", 
  "alias:my-alias-*", 
  "path:packages/**/*",
  "tag:my-tag",
);

project.runScriptAcrossWorkspaces({
  workspacePatterns: [
    "my-name-or-alias",
    "name:my-workspace-*",
    "alias:my-alias-*",
    "path:packages/**/*",
    "tag:my-tag",
  ],
  script: "lint",
});
````

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /concepts/workspace-dependencies/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /concepts/workspace-dependencies/index.md.

# Concept: Workspace Dependencies

## Overview

[Workspaces](/concepts/glossary.md#workspace) can depend on other workspaces and import/export code between them.

**`pacwich` does not perform source code analysis to determine dependencies.** This makes creating
the graph of workspaces computationally fast and cheap, relying instead on explicit
`package.json` dependencies (using `"workspace:*"` for `bun` and `pnpm` or `"*"` for `npm`).

In **Bun** and **pnpm**, workspaces must declare each other as dependencies to share code, which is ideal,
but **npm** does not require this. The [`verify` feature](/concepts/verify.md) can help identify missing dependencies
for **npm** by attempting to find imports/exports that reference other workspaces.

### Setting up Dependencies - Example

Here is the basic structure of workspace dependencies:

<WorkspaceDependencyExample />


Alt workspace dependency examples for .md page in place of <WorkspaceDependencyExample /> above:

### bun:

Root `package.json`: `{ "name": "my-project-root", "workspaces": ["packages/*"] }`

`packages/workspace-a/package.json`, where `workspace-a` exports some code from its `index.ts`: `{ "name": "workspace-a", "type": "module", "main": "index.ts" }`

`packages/workspace-b/package.json`: JS/TS files in this workspace can import from `"workspace-a"`: `{ "name": "workspace-b", "dependencies": { "workspace-a": "workspace:*" } }`

### pnpm:

Root `pnpm-workspace.yaml`: `packages: ["packages/*"]`

`packages/workspace-a/package.json`, where `workspace-a` exports some code from its `index.ts`: `{ "name": "workspace-a", "type": "module", "main": "index.ts" }`

`packages/workspace-b/package.json`: JS/TS files in this workspace can import from `"workspace-a"`: `{ "name": "workspace-b", "type": "module", "dependencies": { "workspace-a": "workspace:*" } }`

### npm:

Root `package.json`: `{ "name": "my-project-root", "workspaces": ["packages/*"] }`

`packages/workspace-a/package.json`, where `workspace-a` exports some code from its `index.ts`: `{ "name": "workspace-a", "type": "module", "main": "index.ts" }`

`packages/workspace-b/package.json`: JS/TS files in this workspace can import from `"workspace-a"`. When using npm, placing `{ "workspace-a": "*" }` in dependencies is not necessary, but this is how `pacwich` determines dependencies. Use the `verify` feature to detect dependencies not declared in a workspace's package.json. `{ "name": "workspace-b", "type": "module", "dependencies": { "workspace-a": "*" } }`

## Workspace Dependency Rules

You can set rules to allow or deny other workspaces as dependencies in a workspace's [configuration](/config/workspace.md),
set by [workspace patterns](/concepts/workspace-patterns.md).

Use `allowPatterns` to define which dependencies are permitted or `denyPatterns` to forbid specific ones. When both are present,
`denyPatterns` will further filter the subset already permitted by `allowPatterns`.

For example, you may disallow dependencies with the [tag](/config/workspace.md#tags) "backend" for a frontend workspace with `denyPatterns: ["tag:backend"]`.

## Running Scripts in Dependency Order

When running scripts via the [CLI](/cli/commands.md#run-script) or [API](/api/reference.md#runscriptacrossworkspaces), workspaces can be run in dependency order.

This means that a workspace's script will wait until any workspaces it depends on have completed.
This is similar to how Bun's [`--filter` flag](https://bun.com/docs/pm/filter#dependency-order) works, though for `pacwich`,
this behavior is opt-in.

This can be useful in situations where one workspace depends on another workspace's output, such as a build script's output.

### CLI Example


````
pacwich run my-script --dep-order

# Run all scripts even if a dependency fails
pacwich run my-script --dep-order --ignore-dep-failure
````

### API Example


````
import { createFileSystemProject } from "pacwich";

const project = createFileSystemProject();

project.runScriptAcrossWorkspaces({
  script: "my-script",
  dependencyOrder: true,
  ignoreDependencyFailure: true,
});
````

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /concepts/root-workspace/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /concepts/root-workspace/index.md.

# Concept: Root Workspace

## Overview

The root workspace is simply a [Workspace](/concepts/glossary.md#workspace) based on the root `package.json` of your project.

By default, this is not included in the project's workspaces list, but there
are ways to either modify or override the default, and it is always possible to directly reference it explicitly.

## Including in the Project's workspaces list

### Including by Default

You can set the default value to include the root workspace to `true`
 in the [project configuration](/config/project.md)
 defaults or [environment variable](/config/env-vars.md)
 `PACWICH_INCLUDE_ROOT_WORKSPACE_DEFAULT` to include the root workspace by default.
### Including Explicitly

Use the CLI [global option](/cli/global-options.md#include-root)
 `--include-root` to include the root workspace explicitly for a command.
In the API, use the `includeRootWorkspace` option for [createFileSystemProject](/api/reference.md#createfilesystemproject) to include the root workspace explicitly in the project's workspaces.

## Referencing the Root Workspace

There are ways you can always reference the root workspace, regardless of whether it is included in the project's normal workspaces list or not.

For example, in the API, you can always reference the root workspace by using the `.rootWorkspace` [property](/api/reference.md#rootworkspace) of a `Project`.

You can also use the selector defined below:

### The Root Selector: @root
When passing workspace patterns to the CLI for the [run-script](/cli/commands.md#run-script) command, you can use the `@root` alias to reference the root workspace.


````
# Run the lint script from the root package.json
pacwich run lint @root

# Get workspace information for the root workspace
pacwich workspace-info @root
````

This can also be used similarly in the API:


````
import { createFileSystemProject } from "pacwich";

const project = createFileSystemProject();

// A way to directly get the root workspace object (always available)
const rootWorkspace = project.rootWorkspace;

// Match the root workspace by the special selector (always available)
project.runScriptAcrossWorkspaces({
  workspacePatterns: ["@root"],
  script: "lint",
});
````

Note that in the off chance you have a workspace named `@root`, you can more explicitly reference it via name using the [workspace pattern](/concepts/workspace-patterns.md#name)
 specifier
`"name:
@root"
`.

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /concepts/affected/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /concepts/affected/index.md.

# Concept: Affected Workspaces

## Overview

The idea of an **affected workspace** is simply a workspace that can be considered meaningfully changed.

If one can determine which workspaces are affected by some code change, that can be helpful for orchestrating
DevOps tasks, such as running builds for only those changed workspaces.

### What is considered a meaningful change?

By default, a workspace is considered to have a set of **inputs**, the sources of potential chang to a workspace.

When not [configured](/concepts/inputs.md), the default inputs are:

- All git-trackable files in the workspace's directory
- All [workspace dependencies](/concepts/workspace-dependencies.md). If a workspace dependency is affected for any reason, its dependents are also considered affected.
- The version resolved in your package manager's lockfile for all other dependencies in a workspace's `package.json`.

Inputs can be configured per script as well. See the [inputs](/concepts/inputs.md) page for more information.

### How is an affected workspace determined?

There are two main ways to determine affected workspaces:

#### Using git diff (default)

The default behavior of affected features is to use the git diff between the current HEAD and the default base ref in git.

The default base ref is `main` except when overridden via [project configuration](/config/project.md) or an [environment variable](/config/env-vars.md).

Uncommitted changes (staged, unstaged, untracked) are considered a part of the diff by default.
Files that are gitignored are never considered a part of the diff.


````
# Uses diff of current HEAD against the default base ref (main when not configured)
pacwich affected list

# Compare specific refs (can also pass commit SHA, tag, etc.)
pacwich affected list --base=my-branch-a --head=my-branch-b

# Ignore uncommitted changes
pacwich affected list --ignore-uncommitted # (staged, unstaged and untracked)
pacwich affected list --ignore-untracked
pacwich affected list --ignore-unstaged
pacwich affected list --ignore-staged

# Ignore changes to workspace dependencies derived from package.json files
pacwich affected list --ignore-workspace-deps

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

# Run script across affected workspaces with similar options
pacwich affected run my-script --base=my-branch --ignore-uncommitted
````

- See CLI docs for [affected list](/cli/commands.md#affected-list).
- See CLI docs for [affected run](/cli/commands.md#affected-run).

#### Using a list of changed files

You can bypass using git entirely and simply pass a list of changed files that match inputs.


````
pacwich affected list --files="tsconfig.json packages/example/**/*.ts"

# Paths with leading / are relative to the project root
pacwich affected run --files="/tsconfig.json packages/example/**/*.ts"
````

#### Debugging

You can use the `--explain` flag to get detailed reasoning for the affected workspaces.


````
# Summary for each affected workspaces
pacwich affected list --explain

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

## API features

The API and CLI have practical parity for affected features.

- [FileSystemProject.determineAffectedWorkspaces()](/api/reference.md#determineaffectedworkspaces)
- [FileSystemProject.runAffectedWorkspaceScript()](/api/reference.md#runaffectedworkspacescript)

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /concepts/inline-scripts/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /concepts/inline-scripts/index.md.

# Concept:  Inline Scripts

## Overview

Normally, a ["script"](/concepts/glossary.md#script) in pacwich references one of the entries found in a workspace's `"scripts"` field in its `package.json` file.

However, it's possible to run a one-off shell command from a workspace's directory, an "inline script", such as via `pacwich run "echo 'hello'" --inline` in the CLI.

## Using the Bun Shell

Normally, inline scripts are executed using your system shell. In POSIX systems (Linux, macOS, etc.), `sh -c` is called, while in Windows, `cmd /d /s /c` is called.

You can also use the [Bun shell](https://bun.com/docs/runtime/shell), a bash-like, cross-platform shell, the same as the utility `import { $ } from 'bun'` by passing `--shell=bun`,
if the `bun` command is available.

You can also set the [root](/config/project.md)
 `config.defaults.shell` or [environment variable](/config/env-vars.md)
 `PACWICH_SHELL_DEFAULT` to `"bun"`
 to use the Bun shell by default.
### Examples

#### CLI:


````
# This will use the system shell, 
# unless the project config.defaults.shell
# or process.env.PACWICH_SHELL_DEFAULT is set to "bun"
pacwich run "echo 'hello'" --inline

# Same as the above command
pacwich run "echo 'hello'" --inline --shell=default

# Explicitly run the Bun shell
pacwich run "echo 'hello'" --inline --shell=bun

# Explicitly run the system shell
pacwich run "echo 'hello'" --inline --shell=system
````

#### API:


````
import { createFileSystemProject } from "pacwich";

const project = createFileSystemProject();

// This will use the system shell (sh in POSIX or cmd in Windows), 
// unless the project config.defaults.shell
// or process.env.PACWICH_SHELL_DEFAULT is set to "bun"
project.runWorkspaceScript({
  workspaceNameOrAlias: "my-workspace",
  script: "echo 'this is my inline script'",
  inline: true,
});

// Use the Bun shell to execute a script, a cross-platform bash-like shell,
// if Bun is available
project.runWorkspaceScript({
  workspaceNameOrAlias: "my-workspace",
  script: "echo 'this is my inline script'",
  // Takes "bun", "system", or "default", same as the CLI --shell option
  inline: { shell: "bun" },
});
````

## Script Name

Scripts from `package.json` are named by the key in the `"scripts"` field.

This is used in output logs and [workspace script metadata](/concepts/workspace-script-metadata.md).

Inline scripts, however, have no name by default, but you can provide a name.

### Examples

#### CLI:


````
# Pass a name for an inline script
pacwich run "echo 'my script: <scriptName>'" --inline --inline-name=my-inline-script
````

#### API:


````
project.runWorkspaceScript({
  workspaceNameOrAlias: "my-workspace",
  script: "echo 'this is my inline script'",
  // The name will be empty by default
  inline: true,
});

// Pass a name for an inline script
project.runWorkspaceScript({
  workspaceNameOrAlias: "my-workspace",
  script: "echo 'my script: <scriptName>'",
  inline: { scriptName: "my-inline-script" },
});
````

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /concepts/parallel-scripts/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /concepts/parallel-scripts/index.md.

# Concept:  Parallel Scripts

## Overview

Scripts run in parallel by default (disabled via `--parallel=false` in the CLI or `parallel: false` in the API), and you have control over how many concurrent scripts can run at the same time.

## Parallel Max Value

You can pass a number value, a percentage value (e.g. `50%`), or one of the keywords `"auto"`, `"default"`, or `"unbounded"`
to the parallel max option.

#### Value Types

- A plain number sets the limit to the exact number of concurrent scripts. Setting the max to `2` then only allows two scripts to run at the same time.

- A value of `"auto"` sets the limit to [`os.availableParallelism()`](https://bun.com/reference/node/os/availableParallelism), which generally corresponds to the number of available logical CPUs.
  This is the default value when [configuration](/config/project.md) doesn't override a default.

- A value of `"unbounded"` allows all scripts to run in parallel, but use this with caution, as it can overwhelm a machine and cause instability.

- A percentage value sets the limit to the percentage of [`os.availableParallelism()`](https://bun.com/reference/node/os/availableParallelism). Setting the max to `50%` then sets the limit to roughly half of the available logical CPUs. Note that the limit is floored to the nearest integer above 0.

#### Default Limit

A value of `"default"` explicitly references the default limit.

When the [root](/config/project.md)
 `config.defaults.parallelMax` or [environment variable](/config/env-vars.md)
 `PACWICH_PARALLEL_MAX_DEFAULT` is not set, it is equal to `"auto"`
. You can set `config.defaults.parallelMax` or `PACWICH_PARALLEL_MAX_DEFAULT` to any of the valid values listed above.
## Examples

#### CLI:


````
# Scripts run in parallel by default
# This is the same as passing --parallel=default
pacwich run my-script

# Normally "auto" or the value set by configuration 
# or environment variable (see Default Limit above)
pacwich run my-script --parallel=default

# Explicitly run in parallel, limiting the max 
# concurrent scripts to the available logical CPUs.
#
# This is the default unless the project config.defaults.parallelMax
# or process.env.PACWICH_PARALLEL_MAX_DEFAULT is set to a different value.
pacwich run my-script --parallel=auto

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

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

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

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

# Run every script in parallel (use with caution)
pacwich run my-script --parallel=unbounded
````

#### API:


````
import { createFileSystemProject } from "pacwich";

const project = createFileSystemProject();

// Run in parallel with the default limit.
// Equal to "auto" or value of 
// the project config.defaults.parallelMax 
// or process.env.PACWICH_PARALLEL_MAX_DEFAULT
project.runScriptAcrossWorkspaces({
  script: "my-script"
});

// Same result as above
project.runScriptAcrossWorkspaces({
  script: "my-script",
  parallel: { max: "default" },
});

// Run sequentially by disabling parallel
project.runScriptAcrossWorkspaces({
  script: "my-script",
  parallel: false,
});

// Run in parallel with the number of available logical CPUs
project.runScriptAcrossWorkspaces({
  script: "my-script",
  parallel: { max: "auto" },
});

// Run in parallel with a max of 2 concurrent scripts
project.runScriptAcrossWorkspaces({
  script: "my-script",
  parallel: { max: 2 },
});

// Run in parallel with a max of 50% of the available logical CPUs
project.runScriptAcrossWorkspaces({
  script: "my-script",
  parallel: { max: "50%" },
});

// Run in parallel with no concurrency limit (use with caution)
project.runScriptAcrossWorkspaces({
  script: "my-script",
  parallel: { max: "unbounded" },
});
````

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /concepts/workspace-script-metadata/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /concepts/workspace-script-metadata/index.md.

# Concept:  Workspace Script Metadata

## Overview

When running scripts via the API or CLI, metadata is available via either environment variables within your scripts or interpolation
in an [inline script](/concepts/inline-scripts.md) or appended args.

The environment variables allow scripts to introspect metadata about the project, workspace, and script info to get
context about its execution by `pacwich`.

This same metadata can be referenced within inline script commands and/or appended script args.

## Examples

#### Interpolation via CLI:

In this command, all workspaces will run the same `my-script.ts` file found at the project root, thanks to using `<projectPath>` to interpolate the project root's path,
and the workspace name and path will be passed to the script as arguments.


````
pacwich run "bun <projectPath>/my-script.ts" --inline \
  --inline-name="my-script-name" \
  --args="<workspaceName> <workspacePath>"
````

The script itself could use metadata from the environment variables to dynamically change
its behavior based on the workspace context passed to it:

#### Interpolation via API:

The same as the above CLI example using the TypeScript API:


````
import { createFileSystemProject } from 'pacwich';

const project = createFileSystemProject();

project.runScriptAcrossWorkspaces({
  script: "bun <projectPath>/my-script.ts",
  args: "<workspaceName> <workspacePath>",
  inline: { scriptName: "my-script-name" },
});
````

#### Accessing in a script via environment variables

You can access metadata from within a script that was invoked via `pacwich` via
environment variables directly or the `getWorkspaceScriptMetadata` helper.


````
import { getWorkspaceScriptMetadata } from 'pacwich/script';

// Use the helper within a script that was invoked via pacwich
const projectPath = getWorkspaceScriptMetadata("projectPath");
const projectName = getWorkspaceScriptMetadata("projectName");
const workspaceName = getWorkspaceScriptMetadata("workspaceName");
const workspacePath = getWorkspaceScriptMetadata("workspacePath");
const workspaceRelativePath = getWorkspaceScriptMetadata("workspaceRelativePath");
const scriptName = getWorkspaceScriptMetadata("scriptName");

// Access via plain environment variables (same values as above)
console.log(process.env.PACWICH_PROJECT_PATH);
console.log(process.env.PACWICH_PROJECT_NAME);
console.log(process.env.PACWICH_WORKSPACE_NAME);
console.log(process.env.PACWICH_WORKSPACE_PATH);
console.log(process.env.PACWICH_WORKSPACE_RELATIVE_PATH);
console.log(process.env.PACWICH_SCRIPT_NAME);
````

## Available Metadata

#### Project Path

The absolute path to the project root.

In inline scripts and args: `<projectPath>`

Environment variable: `PACWICH_PROJECT_PATH`
#### Project Name

The name of the project (as in its `package.json`
 `"name"`
 field).

In inline scripts and args: `<projectName>`

Environment variable: `PACWICH_PROJECT_NAME`
#### Workspace Name

The name of the workspace (as in its `package.json`
 `"name"`
 field).

In inline scripts and args: `<workspaceName>`

Environment variable: `PACWICH_WORKSPACE_NAME`
#### Workspace Path

The absolute path to the workspace.

In inline scripts and args: `<workspacePath>`

Environment variable: `PACWICH_WORKSPACE_PATH`
#### Workspace Relative Path

The relative path to the workspace from the project root.

In inline scripts and args: `<workspaceRelativePath>`

Environment variable: `PACWICH_WORKSPACE_RELATIVE_PATH`
#### Script Name

The name of the script. This is an empty string when running as an inline script, unless a script name is [explicitly provided](/concepts/inline-scripts.md#script-name)
.

In inline scripts and args: `<scriptName>`

Environment variable: `PACWICH_SCRIPT_NAME`

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /concepts/script-execution-order/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /concepts/script-execution-order/index.md.

# Concept: Script Execution Order

## Overview

Using the [workspace configuration](/config/workspace.md), you can set an `"order"` value to sort the execution order of a script per workspace.

You may want to run scripts in series (`--parallel=false` in the CLI or option `parallel: false` in the API) instead of the default parallel so that
each script completes before the next one starts.

### Default Order

By default, workspaces are sorted in alphanumerical order of their relative path from the project root.

### Configured vs. Default Order

Workspace scripts with
an `"order"` value will be executed before workspaces with no `"order"` set for the same script, falling back to the default order.

## Example

In this example, any other workspaces in the project with an `"order"` for the `"start"` script less than `10` will be executed before this workspace,
and any workspaces with an `"order"` for the `"start"` script greater than `10` will be executed after this workspace.


````
{
  "alias": "myApp",
  "scripts": {
    "start": {
      "order": 10
    },
    "test": {
      "order": 20
    }
  }
}
````

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /concepts/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /concepts/index.md.

# Concepts

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /ai/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /ai/index.md.

# AI Integrations

`pacwich` provides several AI integrations that serve to provide agents
with documentation to understand how to use `pacwich`.

Most of these integrations provide the same sets of documentation,
but in different forms you can choose at your discretion.

## AGENTS.md

`pacwich` provides an **AGENTS.md** file that documents the package for AI agents,
which can be integrated into CLAUDE.md or other AI agent configuration files
to use in context.

When you [install](/intro/getting-started.md) `pacwich` locally, you can
find the file at `node_modules/pacwich/AGENTS.md`.

There are also split versions of this file under `node_modules/pacwich/agents/` for smaller
context usage.

See the [page on AGENTS.md](/ai/agents.md) for more information.

## Skills

The CLI includes an `add-skills` command to add skill files to your repo.

These skills have the same information as the `AGENTS.md` and `agents/` files above.
You own these files, and they are not included in ambient context automatically until
invoked.

Below is an example of how to use it:


````
pacwich add-skills --dir=.claude/skills
````

See the [page on skills](/ai/skills.md) for more information.

## MCP Server

The MCP server provides the same documentation as AGENTS.md and skills as
described above. With MCP, the docs are accessed as MCP resources.

The MCP server can be ran with:


````
pacwich mcp-server
````

See the [page on the MCP server](/ai/mcp.md) for more information.

## /llms.txt

This is an **experimental** feature of this documentation website.

Markdown files are generated via the [rspress](https://rspress.dev/) framework for agents to
have a streamlined access to the same docs as the website.

Instructing an agent to read `https://pacwich.dev/llms.txt` will provide a manifest for
consuming markdown files of the same content as this documentation website.

This is potentially a more token-heavy solution for providing docs to an agent, but may give the
most complete context about features and concepts.

See the [page on /llms.txt](/ai/llms-txt.md) for more information.

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /ai/agents/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /ai/agents/index.md.

# AI Integrations: AGENTS.md

`pacwich` provides an **AGENTS.md** file that can be used to provide context to AI tools about the package, which
can be found at `node_modules/pacwich/AGENTS.md` after you install `pacwich`.

The content of this file is the same as the the [skills](/ai/skills.md) files or [MCP](/ai/mcp.md) server's resources.

You can use this file to provide immediate knowledge of `pacwich` to an agent.

## Split files

You can also access partial files from `node_modules/pacwich/agents/` for more targeted context.

These include:

- `OVERVIEW.md` (encouraged to link first, includes a manifest of the other files below)
- `CLI.md`
- `API.md`
- `CONFIG.md`
- `CONCEPTS.md`


---


## Web-served Files

The documentation website serves the same files from latest found in the same structure at:

- `https://pacwich.dev/AGENTS.md`
- `https://pacwich.dev/agents/OVERVIEW.md`
- `https://pacwich.dev/agents/CLI.md`
- `https://pacwich.dev/agents/API.md`
- `https://pacwich.dev/agents/CONFIG.md`
- `https://pacwich.dev/agents/CONCEPTS.md`

## Example: Usage in CLAUDE.md

Since CLAUDE.md supports importing other files, you can easily integrate this file into your context by adding the following line to your CLAUDE.md file:


````
<!-- CLAUDE.md contents -->

@node_modules/pacwich/AGENTS.md
````

Using the split files:


````
@node_modules/pacwich/agents/OVERVIEW.md
@node_modules/pacwich/agents/CLI.md
````

Simply suggesting to read directly from the doc website in a prompt or AGENTS.md:

> This project uses the npm package pacwich for monorepo tooling
> that enhances native workspaces. Get the latest full docs
> from `https://pacwich.dev/AGENTS.md`, or read the shorter
> `https://pacwich.dev/agents/OVERVIEW.md` which includes
> a manifest of targeted slices of docs for more token efficiency.

## Other Tooling

If your tool does not support imports like CLAUDE.md, you can manually copy the contents of `node_modules/pacwich/AGENTS.md` into your tool's context
or create a symlink to the file in your tool's config.

You might also simply instruct your agent to read `node_modules/pacwich/AGENTS.md` via a prompt.

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /ai/skills/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /ai/skills/index.md.

# AI Integrations: Skills

You can create skill files that provide context to AI tools about the package.

These skills have the same information as the [`AGENTS.md` files](/ai/agents.md)
and [MCP](/ai/mcp.md) resources.

You own these files, and they are not included in ambient context automatically until
invoked.

## Adding to your project

The CLI includes an [`add-skills`](/cli/commands.md#add-skills) command to add skill files to your repo.

Below is an example of how to use it:


````
pacwich add-skills --dir=.claude/skills
````

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /ai/llms-txt/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /ai/llms-txt/index.md.

# AI Integrations: llms.txt

This is an experimental
 feature of this documentation website.
Markdown files are generated via the [rspress](https://rspress.dev/) framework for agents to
have a streamlined access to the same docs as the website.

Instructing an agent to read `https://pacwich.dev/llms.txt` will provide a manifest for
consuming markdown files of the same content as this documentation website, such as
with a prompt or addition to instructions:

> This project uses the npm package pacwich for monorepo tooling
> that enhances native workspaces. Get the latest full docs
> from `https://pacwich.dev/llms.txt`.

Note that the website also serves the [AGENTS.md files](/ai/agents.md) that are more optimized
for agent consumption.

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /ai/mcp/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /ai/mcp/index.md.

# AI Integrations: MCP Server

`pacwich` provides its own MCP server via `npx pacwich mcp-server`. This can be used with any tooling that supports MCP.

When you set up the MCP server with your tool, an agent has access to the server's **resources** that provide it complete documentation,
the same documentation also available via [AGENTS.md files](/ai/agents.md) or [skills](/ai/skills.md).

Agents that read the server instructions on initialization will automatically have knowledge of `pacwich`
as a package with a brief overview and introduction to the CLI, kept very brief due to tools' propensity to
truncate these instructions.

## Example Integration for Claude Code or Cursor

**Claude Code**: Add below to `.mcp.json`

**Cursor**: Add below to your `.cursor/mcp.json`


````
{
  "mcpServers": {
    "pacwich": {
      "command": "npx",
      "args": [
        "pacwich",
        "mcp-server"
      ]
    }
  }
}
````

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /how/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /how/index.md.

# How Are These Docs Maintained?

Hi, I'm Scott, creator of this package.

Up to this point, I've written the content for this documentation website myself. On top of this,
there is the documentation used in the various [AI integrations](/ai.md). I expand
upon my AI boundaries in [the page on package security](/security.md).

This might seem like a lot to manage as one developer, so I thought I'd explain
a bit about why the maintenance burden is reasonable for me.

Agent review is still powerful for catching issues, but I do take some other
specific measures to prevent drift described below.

## The Website

### Centralized Code Examples and Data

There are several instances where content is shared, such as the CLI and API quick start examples interpolated in
the website and the README. This is done to prevent drift.

The website also dynamically renders constants it pulls from the same metadata used by the real package,
like the latest version, supported runtime and package manager versions, env var names, etc.

Even with the help of AI review, DRY still guards against growing code and documentation that can otherwise
start to outgrow an agent's or person's reliable context. This is true beyond documentation.

### Enforced completeness via metadata

I have instances where I use metadata also consumed by the `pacwich` package source to require
features are documented.

For example, I capture all [CLI commands](/cli/commands.md) as JSON config with metadata about their usage,
so I use TypeScript and runtime checks to enforce every CLI command contributes to
componentized documentation, including a requirement for example code that covers every
option.

This helps prevent drift as CLI commands are added or features add options. Patterns like this are used
elsewhere, such as for documenting accepted [environment variables](/config/env-vars.md) or ensuring
[configuration](/config.md) properties are documented on each config file's main page.

### Static object examples verified by TypeScript

Generally, when static objects are needed for an example, such as for [config](/config.md), a TypeScript file is used to enforce
the type of an object used for an example, which is then dynamically rendered simply via `JSON.stringify()`
on an actual page.

### /llms.txt for free

The website also serves an experimental [llms.txt](/ai/llms-txt.md)
generated by the [`rspress`](https://rspress.rs) framework I use and love to make this.

This feature is simply an opt-in toggle that requires little to no maintenance burden for myself.

## The Agent Documents

Some insights into how I handle the documentation tailored to LLMs:

### Centralized Markdown

The [documentation skills](/ai/skills.md), [AGENTS.md file(s)](/ai/agents.md), and [MCP resources](/ai/mcp.md)
are all sourced from the same centralized set of files split by concerns that match the splits
of docs in each of these features.

This means that all agent-friendly documentation shares the same source of truth.

### Brief and Technical

This doc website is optimized to be used by people.

However, agent documentation can be more dry and brief, assuming a basic level
of trust in software terminology and idioms.

### A Good Starting Point

Thanks to the fact that these docs are often simpler to write and shorter,
they're the best place for me to start once it's time to document a change.

With this, I can gather the bare bones of how a change should be documented first,
which then lowers the effort of translating the fundamental information into
the potentially more involved website change.

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /index.md.

# Pacwich

## Monorepo tooling that works on top of **Bun**, **npm**, and **pnpm** workspaces.

[Overview](/intro/overview)[Getting Started](/intro/getting-started)

## Monorepo tooling that works on top of **Bun**, **npm**, and **pnpm** workspaces.

[Overview](/intro/overview)[Getting Started](/intro/getting-started)

[**Zero config
** required to get started


](/intro/getting-started)[**Orchestrate
** plain old package.json scripts in workspaces


](/cli/commands#run-script)[Includes a 
**TypeScript
** API


](/api)[**Decouple
** monorepo tooling from your package manager


](/intro/overview#decoupling-from-your-package-manager)[A 
**debuggable
**, configurable affected graph


](/concepts/affected)[Enforce 
**rules
** for workspace code sharing


](/config/workspace)[Write optional config files in 
**JSON or TypeScript/JavaScript
** 


](/config)[AI integrations: 
**Skills
**, 
**AGENTS.md
**, an 
**MCP Server
**, and 
**/llms.txt
**

](/ai)

[Try the CLI](/web-cli)

Get hands-on with a demo project, 
 right here in the browser!

This package is the continuation of the original,<span className="deprecated"> now <b>deprecated</b>, <code>bun-workspaces</code></span>
package. `bun-workspaces` users can expect minimal to no changes on average.


See the <Link className="inline-link" href="/intro/bun-workspaces-migration">migration guide</Link> or
<BlogLink path="pacwich-launch">read the launch blog post</BlogLink> covering the reasoning and development strategy.


<CliInstall docLinks />

Alt install instructions for .md page in place of <CliInstall /> above:

Installing:

### npm:

Global install: `npm install -g pacwich
# Print help for installing completions
pacwich completion
# Attempt to automatically install completions for your shell
pacwich completion install
`
Local install: `npm install -D pacwich`
Local/one-off execution: `npx pacwich`

### pnpm:

Global install: `pnpm add -g pacwich
# Print help for installing completions
pacwich completion
# Attempt to automatically install completions for your shell
pacwich completion install
`
Local install: `pnpm add -D pacwich`
Local/one-off execution: `pnpm exec pacwich`

### bun:

Global install: `bun add -g pacwich
# Print help for installing completions
pacwich completion
# Attempt to automatically install completions for your shell
pacwich completion install
`
Local install: `bun add -d pacwich`
Local/one-off execution: `bunx pacwich`

Note that the global install will delegate to the local install when available.

[Overview
](/intro/overview)[Getting Started
](/intro/getting-started)

## What's New


### Noteworthy recent updates


---

- You can try the new 
[Web CLI
](/web-cli) to demo 
`pacwich`
 here in the browser!

- [v0.6.0](https://github.com/smorsic/pacwich/releases/tag/pacwich-v0.6.0)
: Since 0.3, the CLI can debug config (
[`config debug
`](/cli/commands#config-debug)), specific 
[warning logs
](/config/warnings) are suppressible, and 
[ 
`verify
`](/concepts/verify) is more configurable

- [v0.3.0](https://github.com/smorsic/pacwich/releases/tag/pacwich-v0.3.0)
: Shell completions are here for the global CLI! See the install docs above.

- [v0.2.0](https://github.com/smorsic/pacwich/releases/tag/pacwich-v0.2.0)
: New 
[`run-interactive`](/cli/commands.md#run-interactive)
 feature for running a workspace script with full stdio support

- `pacwich`
 launches from the ashes of 
`bun-workspaces`
: 
[Read the blog post
](https://smorsic.io/blog/pacwich-launch)

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /intro/bun-workspaces-migration/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /intro/bun-workspaces-migration/index.md.

# Migrating from bun-workspaces

`pacwich` is essentially the direct continuation of the package `bun-workspaces`, a very similar package that was built only to work
on top of Bun as a package manager.

If you are a `bun-workspaces` user, you can expect minimal to no changes on average beyond the name change, thanks to the fact
that `pacwich` auto-detects Bun as your package manager from `bun.lock` and has almost the same CLI and API as `bun-workspaces`.

There's a high chance you can simply treat this as a name swap only without issue.

However, a few small breakages/removals have occurred, highlighted below, and config files have naming changes, including that "root config" will
now be generally referred to as "project config". [Jump to config changes](#config-changes)

This guide is maintained against the **current `pacwich` release**, so it covers every compatibility-related difference between the final
`bun-workspaces` release (1.12.0) and `pacwich` today, no matter which `pacwich` version you are jumping to. Per-version details for everything
else are in the [GitHub Releases changelog](https://github.com/smorsic/pacwich/releases), and a short list of [feature additions](#feature-additions) is at the bottom of this page.

## Install

You can globally and/or locally install `pacwich` with Bun, npm or pnpm. The global `pacwich` command provides a convenient binary that will run the CLI from a local install if found.

## General Changes

- <span className="deprecated"><b>Change</b> (potentially breaking)</span>: The [shell option for inline scripts](/concepts/inline-scripts.md#using-the-bun-shell) now defaults to `"system"` instead of `"bun"`, due to this no longer being a Bun-specific package. You can still
  use "bun" as your shell with any package manager, though it will fail if the `bun` command is not available.
- <span className="deprecated"><b>Change</b> (breaking)</span>: All [environment variables](/config/env-vars.md) used for settings which started with `BW_` now start with `PACWICH_`.
- <span className="deprecated"><b>Change</b> (potentially breaking)</span>: A workspace's [input files](/concepts/inputs.md) can no longer belong to a nested workspace's directory. This mainly matters when
  the root workspace is included in the project's workspace list, where it previously could be flagged as affected by changes in any nested workspace. Both the affected and verify features are subject to this.
- <span className="primary bold">Support</span>: `pacwich` runs via Node 22 or higher and Bun 1.2 or higher (including Bun 1.4's v2 lockfile). pnpm 10 through 12 are supported. `npx pacwich` and `bunx pacwich` can both be used to invoke the CLI.

## CLI Changes

- <span className="deprecated"><b>Fix</b> (potentially breaking)</span>: The `-d` short form of `--dep-order` for the `run` and `affected run` (formerly `run-affected`) commands clashed with the global option `-d` (short for `--cwd`). The `--dep-order` short form is now `-D`.
- <span className="deprecated"><b>Removal</b> (warning message temporarily logged)</span>: The global option `-w|--workspace-root` has been removed. This was a pnpm-inspired feature, but this is now `pacwich`'s default behavior, so the flag is not needed. `pacwich` always walks
  up your directory tree to find a project root.
- <span className="warning"><b>Change</b> (deprecation)</span>: The `run-affected` and `list-affected`/`ls-affected` commands are deprecated in favor of the new
  [`affected run`](/cli/commands.md#affected-run) and [`affected list`](/cli/commands.md#affected-list) subcommands (`af` is an alias for `affected`). The old commands still work with a
  warning, which can be silenced via the [`--suppress-warnings`](/cli/global-options.md#suppress-warnings) global option using the warning IDs `DeprecatedRunAffectedCliCommand` and `DeprecatedListAffectedCliCommand`.

## API Changes

- <span className="deprecated"><b>Removal</b> (breaking)</span>: `Project.createScriptCommand()` was removed. This was a lower level utility never alluded to in examples and was dependent on Bun-specific details.
- <span className="warning"><b>Change</b> (deprecation)</span>: `Project.config.root` is renamed to `Project.config.project` (reference to config such as defined in `pacwich.project.ts`).
- <span className="warning"><b>Change</b> (deprecation)</span>: `Project.mapScriptsToWorkspaces()` is deprecated in favor of the new `Project.scriptMap` property of the same type as the method's return value.
- <span className="warning"><b>Change</b> (deprecation)</span>: `Project.mapTagsToWorkspaces()` is deprecated in favor of the new `Project.tagMap` property of the same type as the method's return value.

## MCP Changes

- <span className="deprecated"><b>Removal (breaking)</b></span>. Project tools have been removed due to being redundant with the CLI.
  Agents should instead simply read the [documentation resources](/ai/mcp.md) provided and use the CLI for <code>pacwich</code> operations

## Config Changes

The names of your [config files](/config.md) have changed, but the new config files **are currently backwards compatible** with `bun-workspaces` config files,
though some utility names have been deprecated for the root config (see below).

Of course, for TS/JS files, you'll import utils from `"pacwich/config"` instead of `"bun-workspaces/config"`.

### Workspace Config

[Workspace config](/config/workspace.md) is **fully backwards compatible**, with only the optional `verify` property added.

- **Rename**: `bw.workspace.{ts,js,json,jsonc}` → `pacwich.workspace.{ts,js,json,jsonc}`

### Root Config, now "Project Config"

What was called "root config" in `bun-workspaces` is now called ["project config"](/config/project.md) in `pacwich`, to keep the naming simple and consistent
with the package's primitives.

**The actual config object value is backwards compatible, with only optional properties added** (`packageManager`, `defaults.cliScriptOutputStyle`, and `verify`).

- **Rename**: `bw.root.{ts,js,json,jsonc}` → `pacwich.project.{ts,js,json,jsonc}`
- <span className="warning"><b>Deprecation</b> (imported util)</span>: `defineRootConfig` is deprecated in favor of `defineProjectConfig`.
- <span className="warning"><b>Deprecation</b> (imported util)</span>: `mergeRootConfig` is deprecated in favor of `mergeProjectConfig`.
- <span className="warning"><b>Deprecation</b> (imported type)</span>: The `RootConfig` type is deprecated in favor of `ProjectConfig`. Similar types using "Root" have the same name change to use "Project".

##### Notes on Deprecated Utilities

When using a TS/JS file, utility and type names are temporarily backwards compatible, but you're encouraged to move to the new "project" names over
the deprecated
 "root" names:

````
// Old: bw.root.ts
import { defineRootConfig, type RootConfig } from 'bun-workspaces/config';

export default defineRootConfig({
  // ... your config
})
````


````
// New: pacwich.project.ts
import { defineProjectConfig, type ProjectConfig } from 'pacwich/config';

export default defineProjectConfig({
  // ... your config
})
````

## Feature Additions

None of these require changes to migrate, but they are new since `bun-workspaces`. See the [GitHub Releases changelog](https://github.com/smorsic/pacwich/releases) for full per-version notes.

- **Package manager selection**: the [`--pm` global option](/cli/global-options.md#package-manager), the `packageManager` option of [`createFileSystemProject()`](/api/reference.md#createfilesystemproject), and the `packageManager` [project config](/config/project.md) value, though default auto-detection is generally preferred.
- **Verify**: the [`verify` command](/cli/commands.md#verify) and [`Project.verify()`](/api/reference.md#verify) detect workspace dependencies that are imported but not declared in `package.json`, including ones declared only by an ancestor workspace. Configurable via the `verify` property of [project](/config/project.md#verify) and [workspace](/config/workspace.md#verify) config. [Read more](/concepts/verify.md)
- **Interactive scripts**: the [`run-interactive`/`ri` command](/cli/commands.md#run-interactive) and the `interactive` option of [`Project.runWorkspaceScript()`](/api/reference.md#runworkspacescript) run a single script with full stdio.
- **Shell completions**: the [`completion` command](/cli/commands.md#completion) sets up project-aware completions for the globally installed `pacwich` binary.
- **Config inspection**: the [`config debug` command](/cli/commands.md#config-debug) prints resolved project and workspace configs as JSON.
- **Logging control**: the [`--suppress-warnings`](/cli/global-options.md#suppress-warnings) global option and `PACWICH_SUPPRESS_WARNINGS` env var silence [specific warnings by ID](/config/warnings.md), and `PACWICH_LOG_LEVEL` sets the default [log level](/cli/global-options.md#log-level).
- **Default output style**: [project config](/config/project.md) `defaults.cliScriptOutputStyle` sets the default `--output-style` of the [`run` command](/cli/commands.md#run-script) (`"grouped"` only applies on a TTY, otherwise falling back to `"prefixed"`).
- **Diagnostics**: the [`doctor` command](/cli/commands.md#doctor) prints runtime, OS, shell, and package manager version info.
- **Agent docs**: the [`add-skills` command](/cli/commands.md#add-skills) adds agent skill files to your project, and `node_modules/pacwich/agents/` holds smaller per-topic agent docs alongside `node_modules/pacwich/AGENTS.md`. [Read more](/ai/agents.md)

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /intro/getting-started/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /intro/getting-started/index.md.

# Getting Started

<CliInstall />


Alt install instructions for .md page in place of <CliInstall /> above:

Installing:

### npm:

Global install: `npm install -g pacwich
# Print help for installing completions
pacwich completion
# Attempt to automatically install completions for your shell
pacwich completion install
`
Local install: `npm install -D pacwich`
Local/one-off execution: `npx pacwich`

### pnpm:

Global install: `pnpm add -g pacwich
# Print help for installing completions
pacwich completion
# Attempt to automatically install completions for your shell
pacwich completion install
`
Local install: `pnpm add -D pacwich`
Local/one-off execution: `pnpm exec pacwich`

### bun:

Global install: `bun add -g pacwich
# Print help for installing completions
pacwich completion
# Attempt to automatically install completions for your shell
pacwich completion install
`
Local install: `bun add -d pacwich`
Local/one-off execution: `bunx pacwich`

Note that the global install will delegate to the local install when available.




Version requirements:
**bun:** ^1.2.0 | **node:** >=22.0.0 <=26.x | **pnpm:** >=10.0.0 <=12.x 


**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`, or `npm install`. If you've
added/removed/updated any workspace `package.json`, you'll likely need to
run this again.

### Terminology

The definitions of **workspace** and **project** differ between package managers and monorepo tooling.

In `pacwich`, the word **workspace** is closer to how it's used in **npm** and **Bun**, a **workspace** being a **nested package** in a monorepo. Not necessarily all packages are workspaces, but all workspaces are packages.

The **project** is synonymous with your root where workspaces are defined, often the root of your git repository as well.

This means you have a root **project** that has some number of **workspaces**. The root package is not considered a workspace by default, but [it optionally can be](/concepts/root-workspace.md).

See: [Glossary page](/concepts/glossary.md)

## First commands

If you have a project with workspaces set up and dependencies installed, `pacwich` works right away.
Otherwise, [read below](#package-manager-selection) on package manager requirements.

Whether using the global install of the CLI `pacwich` or invoking it with `bunx pacwich` or `npx pacwich`,
you can run the following commands to get started:


````
# See usage
pacwich --help

# List workspace data
pacwich ls

# Get JSON metadata
pacwich ls --json

# Run all workspaces' package.json script "my-script" in parallel
pacwich run my-script

# Get help for a specific command
pacwich help run
````

See more starter code in the [CLI Quickstart](/cli.md) or [TS/JS API Quickstart](/api.md).


---


## Using the Verify Command

You can use the `verify` command just to check for issues with your project. This is especially useful for **npm** users but
can catch issues that affect `pacwich`'s workspace dependency graph detection with all package managers.

Read more [here](/concepts/verify.md).

Adding the [`verify` command](/cli/commands.md#verify) to your root `package.json`'s `"prepare"` script or as a pre-commit hook can help catch issues with your Project setup
and will attempt to detect workspaces that import/export other workspaces' code without declaring them as dependencies:


````
// your project's root package.json:
{
  "scripts": {
    "prepare": "pacwich verify --strict"
  }
}
````


---


## Package Manager Selection

`pacwich` supports Bun, npm, and pnpm as package managers.

### Auto Detect

`pacwich` attempts to automatically detect your package manager by looking for a lockfile in the project,
such as `package-lock.json`, `pnpm-lock.yaml`, or `bun.lock`.

#### When No Lockfile is Found

`pacwich` requires a lockfile to read workspace data, so you must run your install command
to use the package: `npm install`, `pnpm install`, or `bun install`.

#### Multiple Lockfiles

If you have multiple lockfiles in your project, such as both `bun.lock` and `pnpm-lock.yaml`,
`pacwich` will default automatically in the order of detection: Bun, pnpm, then npm.

### Specify with Config

To explicitly choose a package manager, add [`pacwich.project.ts`](/config/project.md) to your project root with the following content:


````
// pacwich.project.ts

import { defineProjectConfig } from "pacwich/config";

export default defineProjectConfig({
  packageManager: "pnpm", // or "bun" or "npm"
});
````

Note that you can also use a plain JSON file (`pacwich.project.json`) simply with the content `{ "packageManager": "bun" }` instead.

### Specify with Flag

With the CLI, it's also possible to pass a value to the global [`--pm` flag](/cli/global-options.md#package-manager) to explicitly choose a package manager or pass a `packageManager`
option to [`createFileSystemProject`](/api/reference.md#createfilesystemproject) when using the [TS API](/api.md).


---


## Note: Windows Support

`pacwich` is primarily supported for POSIX systems (Linux, macOS).

Windows users using cmd.exe are supported. Our CI runs tests
in Windows servers to help confirm support for all package managers
via Node or Bun. However, stability for cmd.exe is lowest priority.

Windows users are encouraged to use the Windows Subsystem for Linux (WSL)
for the best experience, which is generally encouraged for users of Bun and
Node anyway.

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /lore/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /lore/index.md.

# Who is Bwunster?


![Bwunster](/images/png/bwunster_64x70.png)

Bwunster's namesake remains unchanged from the original
`bun-workspaces` package that `pacwich` was built off of,
which was a similar tool that only worked with Bun.

Bwunster sees your workspaces with its unifying eye,
making them one with itself, while still allowing them their
independence and without requiring them to change for its own sake.
Some say this must be a sign of Bwunster's unconditional love for all workspaces.

Bwunster's burgers are actually made from black and pinto bean patties, seasoned with a southwestern spice blend that includes ancho chiles, smoked paprika, and a dash of cumin.

You can't see it from this angle, but underneath each bun is a generous dollop of spicy and sweet chipotle lime mayo, which acts as glue for a layer of fried shallots.


By the way, one of the greatest cooking hacks of the modern era is:
1. Slice shallots thin
2. Place in a microwave-safe bowl and cover with oil
3. Microwave on high for 5 minutes (give or take), stopping to stir about every minute or so
4. Strain and dry on paper towels, optionally seasoning while hot
The easiest fried shallots you ever made, thanks to underrated modern technology. Credit to 
[Lan Lam's recipe](https://www.youtube.com/watch?v=dJrdXRZ3PUE)
.
Also, congratulations, you now have very fragrant shallot-infused oil to save for other recipes.


Pixel art by Jorge Alejandro Valero Caicedo
[](https://j4vart.com/)[](https://www.instagram.com/j4vart/)

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /roadmap/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /roadmap/index.md.

# Roadmap

## Guiding Principles

We aim to preserve these goals and values for the life of this project.

#### Easy integration

- No special configuration files required to get started
- Simple, straightforward package structure
- Anti-lock-in philosophy: No complexity for the sake of user retention

#### Parity between the CLI and API

- What is possible with the CLI should be possible with the API, and vice versa, with minimal exception

#### Thorough documentation

- All functionality accounted for in this website
- Intellisense for all API features
- CLI usage/help documentation for all commands

#### Aggressive defense against regression

- Features aren't added without test additions
- Bugs aren't fixed without test additions

#### Core features remain free

- No artificial paywalls for the local features of the package

## Goals

#### A local cache

- The ability to cache the output and result of workspace scripts

#### More advanced script orchestration

- The ability to flexibly compose various workspace scripts into arbitrarily complex workflows,
  rather than only running one script across workspaces in parallel or series as currently is possible.

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.




---
url: /security/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /security/index.md.

# Security

Security is becoming an increasing concern with open source software, especially in this ecosystem.

Our goal is to be aware of the risks and attack vectors being used on npm packages and protect against
these as much as practically possible.

The latest pacwich version should:

- Have [provenance confirmation](https://www.npmjs.com/package/pacwich#provenance) on npm with [zero dependencies](https://www.npmjs.com/package/pacwich?activeTab=dependencies)
- Have a release tag with notes authored by a maintainer (ScottMorse) in the [changelog](https://github.com/smorsic/pacwich/releases)
- Be reflected in the header of this website and the top of the README

## Dependencies

On npm, `pacwich` reports having 0 dependencies. This is technically true but isn't the whole picture.

In reality, `pacwich` uses `commander` for CLI parsing, `jiti` and `sucrase`for loading TypeScript/JavaScript config
files, `yaml` for parsing **pnpm** config files, `shell-quote` for shell string parsing and preventing shell injection,
and `semver` for version string parsing. Of these, `sucrase` is the only of these that has sub-dependencies.

The code of these dependencies is bundled into `pacwich`, so they are not installed as separate dependencies
when `pacwich` is installed. This is why the package appears as having 0 dependencies.

### Why bundle?

One practical reason to bundle dependencies is so that they're isolated in the package so
that there's no chance of conflict with other dependencies in a project.

Security-wise, we've recently seen several attacks on npm packages that use [lifecycle scripts](https://docs.npmjs.com/cli/v8/using-npm/scripts?v=true#pre--post-scripts)
such as `postinstall` to run arbitrary code on install.

Bundled dependencies cannot introduce surprise lifecycle scripts to `pacwich` installers
and provide code locked to `pacwich`'s release. In general, this approach prevents
surprise attacks from a dependency's patch version bump.

#### Tradeoff Mitigation

The main tradeoff with bundling is that an insecure dependency bundled into `pacwich` does not trigger
something like `npm audit` in consumers that installed `pacwich`, and consumers can't just
receive a patch/minor bump for a bundled dependency directly, meaning `pacwich` itself would need
its own security issue declared and patched if one arises with a bundled dependency that
is relevant to users.

Due to this, care is put into choosing dependencies with positive reputation and maturity.
On top of this, these bundled dependencies are locked to a specific patch version.
Vetted upgrades are **only** performed on `pacwich`'s side if a fix or feature is needed
from one of these, so stability is prioritized over potential frequent bumps to latest.

Renovate is also used on the source repository to help catch issues with
the current dependencies, mitigating the risk of an insecure bundled dependency
going unnoticed.

#### Auditability:

- [See pacwich's "dependencies" field](https://github.com/smorsic/pacwich/blob/main/workspaces/packages/pacwich/package.json),
  before the rslib bundle process, all resolved from the `pacwich-prod` catalog  defined in the [root `package.json`](https://github.com/smorsic/pacwich/blob/main/package.json)
  where all versions are locked to specific patch versions.
- See the [package npm page](https://www.npmjs.com/package/pacwich?activeTab=dependencies) to confirm 0 dependencies.

## GitHub Actions

### Publishing to npm

`pacwich` is published with OIDC trusted publishing to npm for provenance attestation via Actions.

Long-lived legacy npm tokens are never used for publishing, something seen in recent attacks.

**Auditability**: [Publish workflow](https://github.com/smorsic/pacwich/blob/main/.github/workflows/publish.yml)
and [provenance confirmation on npm](https://www.npmjs.com/package/pacwich#provenance)

### No lifecycle scripts from dependencies

As described above, bundling `pacwich`'s dependencies helps prevent users from
being exposed to insecure lifecycle scripts.

We also prevent lifecycle script injection within the GitHub Actions workflows by using a
dedicated bootstrap action to set up all jobs, which disables all lifecycle scripts when
installing dependencies, preventing CI from being injected itself by devDependencies and the like.

**Auditability**: [Bootstrap action](https://github.com/smorsic/pacwich/blob/main/.github/actions/bootstrap/action.yml)

### No Insecure Context for Forks

We avoid using any triggers where a fork's code may run in the main repo's security context.

For example, the `pull_request_target` is often exploited when a fork's code is checked out
to perform PR checks, in which case the fork's code may substitute a malicious script
for something like a `lint` command defined in the repo.

While it's possible to use `pull_request_target` securely, we simply avoid workflows
where forks are ever checked out in the main repo's security context.

**Auditability**: [All workflows](https://github.com/smorsic/pacwich/tree/main/.github/workflows)

### SHA-pinned Actions

We use standard external actions for purposes like installing Bun, Node, etc., and these
should be treated like dependencies themselves that if compromised introduce great risk
to the publishing process or repository otherwise.

We pin the version of each action used to a specific SHA to prevent supply chain attacks
from this surface. This is enforced in the repository's settings so that this pattern cannot
be neglected.

Renovate is used again here to validate the security of currently used action versions.

**Auditability**: [All workflows](https://github.com/smorsic/pacwich/tree/main/.github/workflows)

## AI Development

I'm Scott, the creator and sole regular maintainer of this package.
Here I feel the need to speak more directly about AI use in development of this package
instead of my formal royal "we."

It's more difficult to guarantee my trustworthiness in the same way that the other claims
above can actually be proven via source code and public platforms, but I can be transparent
about my stances and practices.

### The Importance of Code Hygiene and Code Knowledge

I spent most of my career before AI caring deeply about code hygiene,
and over 8 years of writing TypeScript I developed a personal style
that I used to write the core of `bun-workspaces` (the original Bun-centric package
I repurposed into `pacwich`) almost entirely manually while caring about every module
and dir structure, and `pacwich` actually retains most of this structure.

I believe for a project like this in particular, having high knowledge of the codebase and a care
for code quality is non-negotiable for me to be a steward of the package. I can say that I have
high familiarity with `pacwich`'s source code.

This documentation website as a whole is written mostly directly by myself, sticking to my own words for
text content and even writing almost all code examples entirely by hand. This only feels natural that my
knowledge of the spec should be good enough to document it fully, trusting myself more than an agent.
I very much desire to feel like I'm the true leader and owner of `pacwich`, not an LLM.

### My Tools and Philosophy

I do use tools such as Claude Code and an AI-itegrated IDE. The main goal of agents' code for me is
to write the code I would have wanted to exist to begin with.

My opinionated coding style has helped agentic output be more predictable, streamlining agent decision making
and my review of its work. I work with the philosophy that the true fundamental principles of clean code
and good engineering are just as relevant and useful today as they were years ago, for both the benefit of
people and agents.

If I generate a larger amount of code, I won't release it until I've digested its structure with a real review, where I almost
always end up performing refactor passes, naming improvements, and more.

### Risk in Open Source

I don't believe in giving AI the "scan and stamp" treatment that is only appropriate at a job where
consequences are low.

I'm not naive enough to think that this package that orchestrates shell scripts
and runs in DevOps processes doesn't require deep critical review.

I am well aware that software engineers do not want risky vibe-coded open source, and neither do I, but
I also think that most engineers recognize that the quality of AI-assisted engineering is not black-or-white.

### In Conclusion

If I develop a feature quickly, it will be because I naturally hit my required standards and
confidence levels quickly. I don't feel the need to rush releases just to show off my potential
agentic output speed. Not every use of water demands a fire hose.

As I said, I can't prove it, but I can at least promise to work to remain a true driver of
AI tooling rather than dependent on it when it comes to `pacwich`'s processes and source code,
preserving the right parts of traditional engineering hand-in-hand with new innovations.

© 2026 [Smorsic Labs, LLC](https://smorsic.io). All rights reserved.