> ## Documentation Index
> Fetch the complete documentation index at: https://better-pm.fdarian.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get started with Better PM in minutes

# Quickstart

This guide walks you through the most common Better PM workflows. After completing it, you'll understand how to install dependencies, add packages, and navigate your monorepo efficiently.

<Note>
  Make sure you've completed the [installation](/installation) and set up shell integration before continuing.
</Note>

## Your First Commands

Let's start with the basics in any project with a lockfile.

### Install Dependencies

Better PM automatically detects your package manager and runs the appropriate install command.

```bash theme={null}
pm i
```

This is equivalent to:

* `pnpm install` if you have `pnpm-lock.yaml`
* `bun install` if you have `bun.lockb`
* `npm install` if you have `package-lock.json`

<Info>
  Both `pm i` and `pm install` work — use whichever you prefer.
</Info>

### Add a Dependency

Add a package to your project:

```bash theme={null}
pm add lodash
```

Add a dev dependency with the `-D` flag:

```bash theme={null}
pm add -D typescript
```

<Tip>
  **Paste-friendly**: You can paste install commands directly:

  ```bash theme={null}
  pm add "npm install -D prettier"
  ```

  Better PM extracts `prettier` and the `-D` flag automatically, then uses your project's actual package manager.
</Tip>

### Remove a Dependency

Remove a package:

```bash theme={null}
pm remove lodash
```

## Monorepo Workflows

Better PM shines in monorepo environments. Let's explore the key features.

### List Workspace Packages

View all packages in your monorepo as a tree:

```bash theme={null}
pm pls
```

Example output:

```
packages/
│   ├── core "@myapp/core"
│   └── utils "@myapp/utils"
apps/
    └── web "@myapp/web"
```

<Note>
  The command is `pm pls` (package list) to distinguish it from `pm ls`, which is a proxy for your package manager's `ls` command (e.g., `pnpm ls` for listing installed dependencies).
</Note>

### Navigate to a Package

Jump to any workspace package:

```bash theme={null}
pm cd @myapp/web
```

Return to the monorepo root:

```bash theme={null}
pm cd
```

<Info>
  Tab completion works for package names! Type `pm cd @my` and press Tab to see suggestions.
</Info>

### Scoped Installs

When you're inside a workspace package, `pm i` automatically installs only that package:

```bash theme={null}
cd apps/web
pm i              # Installs only @myapp/web and its dependencies
```

Behind the scenes, Better PM runs:

* `pnpm install --filter "@myapp/web..."` (pnpm)
* `bun install --filter "@myapp/web"` (bun)
* `npm install --workspace @myapp/web` (npm)

To install a specific package from anywhere:

```bash theme={null}
pm i -F @myapp/web
```

Install multiple packages:

```bash theme={null}
pm i -F @myapp/web -F @myapp/api
```

### Root Install Safety

At the monorepo root, `pm i` shows a warning before installing everything:

```bash theme={null}
cd /path/to/monorepo
pm i
```

Output:

```
[WARNING] You are at the monorepo root. This will install ALL packages.

Workspace packages:
packages/
│   ├── core "@myapp/core"
│   └── utils "@myapp/utils"
apps/
    └── web "@myapp/web"

Proceed with installing all packages? (y/N)
```

To skip the prompt (useful in CI):

```bash theme={null}
pm i --sure    # or -y
```

## Additional Commands

Better PM includes several proxy commands that pass through to your package manager.

### Run Scripts

Run a package.json script:

```bash theme={null}
pm run dev
pm run build
pm run test
```

<Tip>
  **Automatic passthrough**: Unknown commands automatically run as scripts:

  ```bash theme={null}
  pm dev      # Equivalent to 'pm run dev'
  pm build    # Equivalent to 'pm run build'
  ```

  This was added in version 0.3.3.
</Tip>

### Execute Packages

Run a package with npx/pnpx/bunx:

```bash theme={null}
pm x prettier --check .    # Uses pnpx, bunx, or npx
```

### Update Dependencies

Update packages interactively:

```bash theme={null}
pm up -i              # Interactive update
pm up --latest        # Update to latest versions
```

### Check Dependency Usage

See why a package is installed (pnpm/bun only):

```bash theme={null}
pm why react
```

### Other Proxy Commands

These commands work exactly like their package manager equivalents:

* `pm ls` — List installed dependencies (not workspace packages)
* `pm link` — Link a package
* `pm unlink` — Unlink a package

## Example Workflow

Here's a complete workflow for working on a feature in a monorepo:

<Steps>
  <Step title="Navigate to your workspace">
    ```bash theme={null}
    pm cd @myapp/web
    ```
  </Step>

  <Step title="Add a new dependency">
    ```bash theme={null}
    pm add react-query
    ```
  </Step>

  <Step title="Install updated dependencies">
    ```bash theme={null}
    pm i
    ```

    This installs only `@myapp/web` and its dependencies.
  </Step>

  <Step title="Run the dev server">
    ```bash theme={null}
    pm dev
    ```

    Automatically runs the `dev` script from package.json.
  </Step>

  <Step title="Add a dev tool">
    ```bash theme={null}
    pm add -D vitest
    ```
  </Step>

  <Step title="Go back to the root">
    ```bash theme={null}
    pm cd
    ```
  </Step>
</Steps>

## Common Patterns

### Install All Packages in CI

```bash theme={null}
pm i -y    # Skips the confirmation prompt
```

### Add the Same Dependency to Multiple Packages

```bash theme={null}
cd packages/core
pm add zod

cd ../utils
pm add zod
```

Or from the root with filters:

```bash theme={null}
pm i -F @myapp/core -F @myapp/utils
```

### Clean Install a Specific Package

```bash theme={null}
rm -rf node_modules
pm i -F @myapp/web
```

## Next Steps

You now know the core Better PM commands! Here are some resources to explore:

<CardGroup cols={2}>
  <Card title="Commands Reference" icon="terminal" href="/commands/install">
    Detailed documentation for every command
  </Card>

  <Card title="Monorepo Guide" icon="folder-tree" href="/guides/monorepo-setup">
    Advanced monorepo workflows and best practices
  </Card>

  <Card title="Shell Integration" icon="terminal" href="/guides/shell-integration">
    Set up shell completions and navigation
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/fdarian/better-pm">
    View source code and contribute
  </Card>
</CardGroup>

## Getting Help

View help for any command:

```bash theme={null}
pm --help
pm i --help
pm add --help
```

For more assistance, open an issue on [GitHub](https://github.com/fdarian/better-pm/issues).