Troubleshooting

Symptoms:

pm i
# zsh: command not found: pm

Cause: Better PM is not installed or not in your PATH.

Solution:

brew install fdarian/tap/better-pm

npm install -g better-pm

which pm
# Should output: /usr/local/bin/pm (or similar)

pm --version
# Should output version number

Symptoms:

npm install -g better-pm
# Completes, but pm command still not found

Cause: npm global binaries directory is not in your PATH.

Solution:

npm bin -g
# Example output: /usr/local/lib/node_modules/.bin

export PATH="$(npm bin -g):$PATH"

source ~/.zshrc  # or ~/.bashrc

Symptoms:

pm i
# Error: No lock file found. Could not detect package manager (pnpm, bun, or npm).

Cause: Better PM searches upward from your current directory for lockfiles but can’t find one. The search stops at your home directory or filesystem root.

Diagnosis:

Check if you have a lockfile in your project:

ls -la | grep -E "(pnpm-lock.yaml|bun.lock|package-lock.json)"

Solutions:

No lockfile exists

Generate one by running your package manager’s install command:

# For pnpm:
pnpm install

# For bun:
bun install

# For npm:
npm install

This creates the lockfile, after which Better PM will work.

Wrong directory

Navigate to your project root:

# Check where you are:
pwd

# Navigate to project root:
cd /path/to/my-project

# Verify lockfile exists:
ls pnpm-lock.yaml  # or bun.lock, package-lock.json

Lockfile above home directory

Better PM’s findUpward utility stops at your home directory to prevent searching the entire filesystem.

From src/project/find-upward.ts:20-22:

if (currentDir === homeDir) {
  return yield* Effect.fail(new Error(`${filename} not found`));
}

Solution: Move your project under your home directory, or cd into the project before running pm.

Symptoms:

pm i
# Running pnpm install
# (but you expected bun install)

Cause: Multiple lockfiles exist in your project, and Better PM picks the first one it finds.

Diagnosis:

Check for multiple lockfiles:

ls -la | grep -E "(pnpm-lock.yaml|bun.lock|package-lock.json)"

Detection order (from src/pm/detect.ts:10-18):

1. pnpm-lock.yaml → pnpm
2. bun.lock → bun
3. bun.lockb → bun
4. package-lock.json → npm

Solution:

Remove the unwanted lockfiles:

# If you want to use bun, remove pnpm/npm locks:
rm pnpm-lock.yaml package-lock.json

# Then regenerate:
bun install

Symptoms:

pm pls
# (no output, or error)

pm cd @myapp/web
# Error: Package "@myapp/web" not found

Cause: Workspace configuration is missing or malformed.

Diagnosis:

pnpm

Check for pnpm-workspace.yaml:

cat pnpm-workspace.yaml

Should contain:

packages:
  - 'apps/*'
  - 'packages/*'

Common issues:

• File doesn’t exist: Create it with your package globs
• Incorrect indentation: YAML is whitespace-sensitive
• Missing quotes: Use quotes for globs with wildcards

bun

Check package.json in your root:

cat package.json | grep -A 5 workspaces

Should contain:

{
  "workspaces": ["apps/*", "packages/*"]
}

Or:

{
  "workspaces": {
    "packages": ["apps/*", "packages/*"]
  }
}

Common issues:

• Missing workspaces field
• Incorrect glob patterns
• JSON syntax errors

npm

Check package.json (same as bun):

cat package.json | grep -A 5 workspaces

Should contain:

{
  "workspaces": ["apps/*", "packages/*"]
}

Solution:

Add or fix workspace configuration, then test:

pm pls  # Should now list packages

Symptoms:

pm pls
# Shows packages/ui but not packages/utils

Cause: Package doesn’t match workspace glob patterns, or lacks a package.json.

Diagnosis:

ls packages/utils/package.json
# Should exist

cat packages/utils/package.json | grep name
# Should output: "name": "@myapp/utils"

const PackageJson = Schema.Struct({
  name: Schema.String,
});

packages:
  - 'packages/*'  # Should match both

ls -d packages/*/
# Should show both packages/ui/ and packages/utils/

Symptoms:

pm cd @myapp/web
# Prints: /path/to/apps/web
# (but doesn't actually cd there)

Cause: Shell integration not activated.

Solution:

eval "$(pm activate zsh)"

eval "$(pm activate bash)"

source ~/.zshrc  # or ~/.bashrc

type pm
# Should output: pm is a shell function
# NOT: pm is /usr/local/bin/pm

Symptoms:

pm cd <TAB>
# No completions appear

Diagnosis:

pm cd --completions
# Should list all workspace package names

grep "pm activate" ~/.zshrc  # or ~/.bashrc
# Should find the eval line

# ❌ Wrong order:
compinit
eval "$(pm activate zsh)"

# ✅ Correct order:
eval "$(pm activate zsh)"
compinit

Symptoms: Typing pm cd <TAB> takes 2-3 seconds to show completions.

Cause: Using npm installation instead of Homebrew.

Explanation:

From the README:

Homebrew is recommended — it installs a native binary, so shell completions resolve in ~60ms.

npm installation runs the CLI through Node.js, which is slower (200-500ms startup time).

Solution:

Switch to Homebrew installation:

npm uninstall -g better-pm
brew install fdarian/tap/better-pm

Then reload shell and test:

source ~/.zshrc
pm cd <TAB>  # Should be much faster

Symptoms:

cd ~/my-monorepo
pm i
# Installs everything without warning

Expected behavior: Should show a warning and prompt for confirmation.

Cause: Using -y / --sure flag, or running in non-interactive environment.

Diagnosis:

Check your command:

pm i -y         # Bypasses prompt
pm i --sure     # Bypasses prompt
pm i            # Should prompt

Check environment:

echo $CLAUDECODE
# If "1", interactive prompts are disabled

Solution:

• To install specific packages: pm i -F @myapp/web

• To install everything intentionally: pm i -y

• For safety, always cd into a package before running pm i

Symptoms:

pm add "npm install react"
# Error: ...

Common issues:

No packages extracted

pm add "npm install"
# Error: No packages specified in pasted command. To install dependencies, use: pm i

Cause: Pasted command has no package names.

Solution: Include the package name:

pm add "npm install react"

Unsupported package manager

pm add "yarn add react"
# (Doesn't parse, tries to install package named "yarn")

Cause: yarn is not in the supported list (PM_NAMES = ['npm', 'pnpm', 'bun']).

Solution: Extract package name manually:

pm add react

Version specifiers

pm add "npm install react@18.2.0"
# May fail depending on package manager

Cause: The @18.2.0 becomes part of the extracted package name.

Solution: Use explicit version:

pm add react@18.2.0

Symptoms:

pm cd @myapp/web
# Error: Package "@myapp/web" not found. Available packages: ...

Cause: Package name doesn’t match any workspace package.

Diagnosis:

pm pls

pm cd @myapp/Web   # ❌ Wrong case
pm cd @myapp/web   # ✅ Correct

cat apps/web/package.json | grep '"name"'
# Output: "name": "@myapp/web"

Symptoms: Commands take 2-5 seconds to start.

Diagnosis:

which pm
# Homebrew: /usr/local/bin/pm (fast)
# npm: /usr/local/lib/node_modules/.bin/pm (slower)

time pm --version
# Homebrew: ~0.06s
# npm: ~0.2-0.5s

Solution: Use Homebrew installation for better performance:

brew install fdarian/tap/better-pm

Symptoms: pm pls or pm cd takes several seconds in a monorepo with 100+ packages.

Cause: Better PM enumerates all workspace packages by:

1. Reading workspace globs from config
2. Expanding globs to find all matching directories
3. Reading each package.json to extract the name

Mitigation:

• Use Homebrew installation (native binary is faster)
• Cache isn’t implemented yet, so each command re-scans
• Consider organizing workspace into fewer, larger packages

Note: This is a known limitation for very large monorepos.