Installation

Install Better PM and set up shell integration

Better PM can be installed via Homebrew (recommended) or npm. After installation, you’ll set up shell integration to enable features like pm cd.

System Requirements

Operating System: macOS (arm64/x64) or Linux (x64/arm64)
Shell: zsh or bash (for shell integration)
Node.js: Not required for Homebrew install; v16+ required for npm install

Install with Homebrew

Install from the custom tap:

brew install fdarian/tap/better-pm

Verify the installation:

pm --version

You should see version 0.3.3 or later.

Install with npm

If you prefer npm or don’t have Homebrew:

npm install -g better-pm

Verify the installation:

pm --version

Shell Integration

Shell integration is required for pm cd to work properly. The pm activate command outputs shell wrapper functions and completions.

Generate shell integration code

Run the activate command for your shell:

pm activate zsh   # For zsh
# or
pm activate bash  # For bash

This outputs shell code that wraps the pm command and adds completions.

Add to your shell profile

Add the following line to your shell configuration file:

# Add to ~/.zshrc
eval "$(pm activate zsh)"

# Add to ~/.bashrc
eval "$(pm activate bash)"

Reload your shell

Source your configuration file or restart your terminal:

source ~/.zshrc   # For zsh
# or
source ~/.bashrc  # For bash

Verify shell integration

Test that pm cd works:

pm cd

If you’re in a monorepo, this should change to the root directory. If not, it will output the current directory (meaning shell integration isn’t active yet).

What the Shell Wrapper Does

The pm activate command generates a shell function that intercepts pm cd commands:

pm() {
  if [ "$1" = "cd" ]; then
    # Run 'pm cd' to get the target directory
    local dir;
    dir=$(command pm cd "$@");
    if [ $? -eq 0 ] && [ -d "$dir" ]; then
      builtin cd "$dir";  # Actually change directory
    fi;
  else
    command pm "$@";  # Run other pm commands normally
  fi;
};

It also sets up completions so you can tab-complete workspace package names after pm cd.

Verify Installation

Confirm everything is working:

Check version

pm --version

Should output 0.3.3 or later.

Test package manager detection

Navigate to any project with a lockfile and run:

pm i --help

Better PM should detect your package manager automatically.

Test completions

In a monorepo, type pm cd and press Tab. You should see your workspace packages listed.

Troubleshooting

Permission Issues

If you get EACCES errors with npm global install:

sudo npm install -g better-pm

Or configure npm to use a different directory without sudo (see npm docs).

Completion Conflicts

If completions don’t work, check for conflicts with other completion systems:

which pm        # Should point to /usr/local/bin/pm or ~/.nvm/.../pm
type pm         # Should show a shell function

Next Steps

Quickstart Guide

Learn the basic commands and try your first workflow