Override or choose the agent

Sometimes you need to override jpd’s automatic package manager detection. This might be for testing, compatibility, personal preference, or when working with projects that support multiple package managers.

Why Override the Agent?

Testing Different Package Managers

# Test how your project works with different tools
jpd install --agent npm
jpd install --agent yarn
jpd install --agent pnpm
jpd install --agent bun

Team Standardization

Even if a project has multiple lock files, you might want to enforce a specific package manager:

# Team policy: always use pnpm
jpd install --agent pnpm
jpd run --agent pnpm build

Compatibility Issues

Some packages or scripts might work better with specific package managers:

# Use npm for a specific installation that has compatibility issues
jpd install --agent npm problematic-package

# Use yarn for the rest of the workflow
jpd run build  # Uses detected yarn

Performance Testing

Compare installation and execution performance across package managers:

# Time npm installation
time jpd install --agent npm

# Time pnpm installation
time jpd install --agent pnpm

Method 1: Per-Command Override (—agent flag)

Basic Usage

Override the agent for a single command:

jpd install --agent yarn lodash
jpd run --agent pnpm dev
jpd exec --agent bun create-react-app my-app
jpd update --agent npm

Supported Agents

jpd supports these package manager values for the --agent flag:

Agent	Description
`npm`	Node Package Manager
`yarn`	Yarn (auto-detects v1 vs v2+)
`pnpm`	Fast, disk space efficient PM
`bun`	All-in-one JavaScript runtime
`deno`	Secure TypeScript/JavaScript runtime

Command Examples

# Install with specific package manager
jpd install --agent yarn
jpd install --agent pnpm react
jpd install --agent npm --dev vitest
jpd install --agent bun --global typescript

# Run scripts with specific package manager
jpd run --agent npm dev
jpd run --agent yarn build
jpd run --agent pnpm test
jpd run --agent bun start

# Execute packages with specific tool
jpd exec --agent npm create-react-app my-app
jpd exec --agent yarn create vite my-app
jpd exec --agent pnpm create-next-app my-app
jpd exec --agent bun create hono my-app

Flag Position

The --agent flag can appear in different positions:

# All of these are equivalent
jpd install --agent yarn lodash
jpd install lodash --agent yarn
jpd --agent yarn install lodash

Method 2: Session-Wide Override (Environment Variable)

Setting JPD_AGENT

Set the JPD_AGENT environment variable to override the default for all commands in your session:

# Set for current session
export JPD_AGENT=yarn

# All jpd commands now use yarn by default
jpd install          # Uses yarn
jpd run dev          # Uses yarn
jpd update           # Uses yarn

# Clear the override
unset JPD_AGENT

# Set for current session
set -x JPD_AGENT yarn

# All jpd commands now use yarn by default
jpd install          # Uses yarn
jpd run dev          # Uses yarn

# Clear the override
set -e JPD_AGENT

# Set for current session
$env:JPD_AGENT = "yarn"

# All jpd commands now use yarn by default
jpd install          # Uses yarn
jpd run dev          # Uses yarn

# Clear the override
Remove-Item Env:JPD_AGENT

# Set for current session
$env.JPD_AGENT = "yarn"

# All jpd commands now use yarn by default
jpd install          # Uses yarn
jpd run dev          # Uses yarn

Persistent Environment Setup

Add to your shell configuration file for permanent override:

# Always use pnpm as default
export JPD_AGENT=pnpm

# Always use pnpm as default
export JPD_AGENT=pnpm

# Always use pnpm as default
set -x JPD_AGENT pnpm

Override Precedence

jpd checks for package manager overrides in this order (highest to lowest priority):

Command-line flag: --agent yarn
Environment variable: JPD_AGENT=yarn
Lock file detection: yarn.lock → yarn
PATH detection: First available package manager
Interactive prompt: Ask user to install one

Example of Precedence

# Set environment default
export JPD_AGENT=npm

# This uses yarn (flag overrides environment)
jpd install --agent yarn

# This uses npm (environment variable)
jpd install

# This uses whatever is detected from lock files (if JPD_AGENT is unset)
unset JPD_AGENT
jpd install

Validation and Error Handling

Invalid Agent Names

jpd validates agent names and provides helpful error messages:

$ jpd install --agent invalid-pm

Error: the agent flag is set the wrong way use one of these values instead [npm yarn pnpm bun deno]

Supported Agents List

jpd only accepts these exact values (case-sensitive):

npm
yarn
pnpm
bun
deno

Agent Availability

jpd doesn’t check if the specified agent is installed. If you override to an unavailable package manager, you’ll get the standard “command not found” error from your shell.

Practical Workflows

Project-Specific Overrides

Use .env files for project-specific package manager preferences:

# In your project's .env file
JPD_AGENT=pnpm

# jpd automatically loads .env files
jpd install  # Uses pnpm for this project

CI/CD Pipeline Standardization

Ensure consistent package manager usage in CI:

# GitHub Actions
- name: Install dependencies
  run: jpd install --agent pnpm
  env:
    JPD_AGENT: pnpm  # Backup via environment

- name: Run tests
  run: jpd run --agent pnpm test

Development vs Production

Use different package managers for different environments:

# Development - use fast local installs
export JPD_AGENT=bun
jpd install
jpd run dev

# Production builds - use npm for compatibility
jpd install --agent npm --production
jpd run --agent npm build

Monorepo Mixed Usage

Different packages in a monorepo might prefer different package managers:

# Frontend uses yarn
jpd install --agent yarn --cwd ./apps/frontend/

# Backend uses npm
jpd install --agent npm --cwd ./apps/backend/

# Shared packages use pnpm
jpd install --agent pnpm --cwd ./packages/shared/

Debugging Agent Selection

Check Current Agent

See which package manager jpd would use:

jpd agent

Debug Detection Process

Use debug mode to see how jpd selects the package manager:

jpd install --debug

# Shows detection process:
# DEBUG Agent flag is set: yarn
# DEBUG Package manager detected: yarn
# DEBUG Executing command: yarn install

Test Different Agents

Quickly test which package managers are available:

jpd install --agent npm --dry-run 2>/dev/null && echo "npm available"
jpd install --agent yarn --dry-run 2>/dev/null && echo "yarn available"
jpd install --agent pnpm --dry-run 2>/dev/null && echo "pnpm available"
jpd install --agent bun --dry-run 2>/dev/null && echo "bun available"

Advanced Usage Patterns

Conditional Agent Selection

Use shell logic to select agents based on conditions:

# Use yarn if available, fallback to npm
if command -v yarn >/dev/null 2>&1; then
  jpd install --agent yarn
else
  jpd install --agent npm
fi

# Use pnpm for large projects, npm for small ones
if [ $(find . -name "node_modules" -prune -o -name "*.js" -print | wc -l) -gt 100 ]; then
  jpd install --agent pnpm  # Better for large projects
else
  jpd install --agent npm   # Simpler for small projects
fi

Function Wrappers

Create shell functions with preset agents:

# Add to your shell config
function jpnpm() { jpd "$@" --agent npm; }
function jpyarn() { jpd "$@" --agent yarn; }
function jppnpm() { jpd "$@" --agent pnpm; }
function jpbun() { jpd "$@" --agent bun; }

# Usage
jpnpm install lodash     # Always uses npm
jpyarn run dev          # Always uses yarn
jppnpm update           # Always uses pnpm