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