Commands (all-in-one)

This page contains the complete reference for all jpd commands, global flags, and environment variables in a single location.

Global Usage

Syntax

jpd <command> [arguments] [flags]

Global Flags

These flags can be used with any command:

Flag	Short	Description	Example
--agent	-a	Override detected package manager	jpd install --agent yarn
--cwd	-C	Run command in specified directory	jpd install --cwd ./my-app/
--debug	-d	Enable debug logging	jpd install --debug
--help	-h	Show help for command	jpd install --help

Environment Variables

Variable	Description	Example
JPD_AGENT	Set default package manager for session	export JPD_AGENT=yarn

Volta Integration

When Volta is detected on your system, jpd automatically uses it to run Node.js package manager commands, ensuring the correct Node.js version is used as defined by your Volta configuration.

Note

jpd automatically detects Volta and uses it when available. You don’t need to configure anything special.

---

install Aliases: i, add

Install packages using the detected package manager.

Usage

jpd install [packages...] [flags]

Flags

Flag	Short	Description	Package Manager Support
--dev	-D	Install as development dependency	All
--global	-g	Install globally	npm, yarn, pnpm, bun
--production	-P	Install only production dependencies	All
--frozen		Use frozen lockfile	All
--search	-s	Interactive package search	All
--no-volta		Skip Volta even if detected	All

Package Manager Mapping

npm

# jpd install
npm install

# jpd install lodash
npm install lodash

# jpd install -D vitest
npm install --save-dev vitest

# jpd install -g typescript
npm install --global typescript

# jpd install --production
npm install --omit=dev

# jpd install --frozen
npm install --package-lock-only

yarn

# jpd install
yarn install

# jpd install lodash
yarn add lodash

# jpd install -D vitest
yarn add --dev vitest

# jpd install -g typescript
yarn add --global typescript

# jpd install --production
yarn install --production

# jpd install --frozen
yarn install --frozen-lockfile

pnpm

# jpd install
pnpm install

# jpd install lodash
pnpm add lodash

# jpd install -D vitest
pnpm add --save-dev vitest

# jpd install -g typescript
pnpm add --global typescript

# jpd install --production
pnpm install --prod

# jpd install --frozen
pnpm install --frozen-lockfile

bun

# jpd install
bun install

# jpd install lodash
bun add lodash

# jpd install -D vitest
bun add --development vitest

# jpd install -g typescript
bun add --global typescript

# jpd install --production
bun install --production

# jpd install --frozen
bun install --frozen-lockfile

Interactive Search

Use the --search flag to search the npm registry interactively:

jpd install --search react
jpd install -s lodash

This opens a terminal UI where you can search for packages and select which ones to install.

---

run Alias: r

Run scripts defined in package.json or tasks in deno.json.

Usage

jpd run [script] [args...] [flags]

Flags

Flag	Description
--if-present	Only run script if it exists

Interactive Selection

When no script name is provided, jpd shows an interactive menu:

# Shows list of available scripts to choose from
jpd run

Need dependency bootstrapping?

jpd run now focuses purely on executing scripts. If you want jpd to handle dependency installation automatically (the old --auto-install behavior), use the dedicated start command instead. It runs your project’s dev/start script and ensures dependencies exist before handing off to the package manager.

Examples:

# Shows the interactive picker
jpd run

# Run a script and pass arguments through
jpd run build -- --watch

# Skip missing scripts without failing CI
jpd run lint --if-present

Package Manager Mapping

npm

# jpd run dev
npm run dev

# jpd run build --prod
npm run build -- --prod

# jpd run test --if-present
npm run --if-present test

yarn

# jpd run dev
yarn run dev

# jpd run build --prod
yarn run build --prod

pnpm

# jpd run dev
pnpm run dev

# jpd run build --prod
pnpm run build -- --prod

# jpd run test --if-present
pnpm run --if-present test

bun

# jpd run dev
bun run dev

# jpd run build --prod
bun run build --prod

deno

# jpd run dev
deno task dev

# jpd run build --prod
deno task build --prod

start

Opinionated helper for dev/start workflows with automatic dependency bootstrapping.

Usage

jpd start [args...]

Behavior

• Ensures node_modules exists before delegating to the package manager. If it’s missing, jpd installs dependencies first.
• Uses the same package manager, Volta detection, and cwd overrides as run.
• Skips the install step for Deno projects (no node_modules to inspect).
• Falls back to plain script execution when everything is already installed, so repeated runs stay fast.

Examples:

# Start the dev server, installing deps if needed
jpd start

# Pass options through to the underlying script
jpd start -- --host 0.0.0.0 --open

---

exec Alias: e

Execute packages using the detected package manager’s executor.

Usage

jpd exec <package> [args...]

Package Manager Mapping

npm

# jpd exec create-react-app my-app
npx create-react-app my-app

# jpd exec typescript --version
npx typescript --version

yarn v1

# jpd exec create-react-app my-app
yarn create-react-app my-app

# jpd exec typescript --version
yarn typescript --version

yarn v2+

# jpd exec create-react-app my-app
yarn dlx create-react-app my-app

# jpd exec typescript --version
yarn dlx typescript --version

pnpm

# jpd exec create-react-app my-app
pnpm dlx create-react-app my-app

# jpd exec typescript --version
pnpm dlx typescript --version

bun

# jpd exec create-react-app my-app
bunx create-react-app my-app

# jpd exec typescript --version
bunx typescript --version

Caution

Deno doesn’t have a direct equivalent to dlx/npx. The exec command will return an error when used with Deno projects.

Yarn Version Detection

jpd automatically detects whether you’re using Yarn v1 (Classic) or Yarn v2+ (Berry) and uses the appropriate command:

• Yarn v1: Uses yarn <package> directly
• Yarn v2+: Uses yarn dlx <package>

---

dlx

Dedicated package-runner command that behaves identically to exec but provides a separate command for clarity.

Usage

jpd dlx <package> [args...]

This command is functionally identical to jpd exec but provides a dedicated entry point for package execution workflows.

---

create Alias: c

Scaffold new projects using create runners from various package managers.

Usage

jpd create <name|url> [args...]

Package Manager Support

• npm, pnpm, yarn, bun: Accepts package names (e.g., react-app, vite, next-app)
• deno: Accepts URLs to TypeScript scripts (e.g., https://deno.land/x/fresh/init.ts)

Flags

• --search, -s: Search npm for popular create-* packages and select interactively
• --size <n>: Number of results to show when --search is used (default: 25)

Passing flags to scaffolding tools

• npm: jpd automatically inserts -- so flags go to the scaffolder. Do not add another --; if you do, jpd will normalize it.
• pnpm / yarn v2+ / bun: pass flags directly after your app name.
• yarn v1: uses npx; pass flags directly after your app name.
• deno: pass arguments directly after the URL.

Package Manager Mapping

npm

# jpd create react-app my-app
npm exec create-react-app -- my-app

# jpd create vite@latest my-app -- --template react
npm exec create-vite@latest -- my-app --template react

yarn v1

# jpd create react-app my-app
npx create-react-app my-app

# jpd create vite@latest my-app -- --template react
npx create-vite@latest my-app --template react

yarn v2+

# jpd create react-app my-app
yarn dlx create-react-app my-app

# jpd create vite@latest my-app -- --template react
yarn dlx create-vite@latest my-app --template react

pnpm

# jpd create react-app my-app
pnpm dlx create-react-app my-app

# jpd create vite@latest my-app -- --template react
pnpm dlx create-vite@latest my-app --template react

bun

# jpd create react-app my-app
bunx create-react-app my-app

# jpd create vite@latest my-app -- --template react
bunx create-vite@latest my-app --template react

deno

# jpd create https://deno.land/x/fresh/init.ts my-app
deno run https://deno.land/x/fresh/init.ts my-app

# jpd create https://raw.githubusercontent.com/denoland/fresh/main/init.ts my-fresh-app
deno run https://raw.githubusercontent.com/denoland/fresh/main/init.ts my-fresh-app

URL Validation for Deno

When using jpd with deno, the first argument must be a valid HTTP or HTTPS URL:

# ✅ Valid - HTTPS URL
jpd -a deno create https://deno.land/x/fresh/init.ts my-app

# ✅ Valid - HTTP URL
jpd -a deno create http://localhost:8000/init.ts my-app

# ❌ Invalid - Package name not supported
jpd -a deno create fresh my-app

For other package managers, URLs are not supported and will result in an error.

Automatic Create Prefix

For npm, pnpm, yarn, and bun, jpd automatically adds the create- prefix if not already present:

# These are equivalent:
jpd create react-app my-app
jpd create create-react-app my-app

---

update Aliases: u, up, upgrade

Update packages to their latest compatible versions.

Usage

jpd update [packages...]

Package Manager Mapping

npm

# jpd update
npm update

# jpd update lodash
npm update lodash

yarn

# jpd update
yarn upgrade

# jpd update lodash
yarn upgrade lodash

pnpm

# jpd update
pnpm update

# jpd update lodash
pnpm update lodash

bun

# jpd update
bun update

# jpd update lodash
bun update lodash

deno

# jpd update
deno outdated

---

uninstall Aliases: un, remove, rm

Remove packages from your project.

Usage

jpd uninstall [packages...] [flags]

Flags

Flag	Short	Description
--interactive	-i	Interactive package selection

Interactive Mode

Use the -i flag to select packages to remove interactively:

jpd uninstall -i

This shows a list of installed dependencies that you can select for removal.

Package Manager Mapping

npm

# jpd uninstall lodash
npm uninstall lodash

yarn

# jpd uninstall lodash
yarn remove lodash

pnpm

# jpd uninstall lodash
pnpm remove lodash

bun

# jpd uninstall lodash
bun remove lodash

---

clean-install Alias: ci

Perform a clean installation with frozen lockfiles, ideal for CI/CD environments.

Usage

jpd clean-install

Package Manager Mapping

npm

# jpd clean-install
npm ci

yarn v1

# jpd clean-install
yarn install --frozen-lockfile

yarn v2+

# jpd clean-install
yarn install --immutable

pnpm

# jpd clean-install
pnpm install --frozen-lockfile

bun

# jpd clean-install
bun install --frozen-lockfile

Yarn Version Handling

jpd intelligently handles different Yarn versions:

• Yarn v1: Uses --frozen-lockfile flag
• Yarn v2+: Uses --immutable flag

The version is detected automatically by running yarn --version.

---

agent Alias: a

Display the detected package manager for the current project.

Usage

jpd agent [args...] [flags]

Note: Unknown flags are passed through to the detected package manager. Additional arguments after agent are forwarded to the underlying tool (npm, yarn, pnpm, bun, or deno).

Output Examples

$ jpd agent
npm

$ jpd agent
yarn

$ jpd agent
pnpm

# Pass --version flag through to the detected package manager
$ jpd agent --version
npm 9.8.1

This command is useful for:

• Debugging package manager detection
• Scripting and automation
• Understanding which package manager jpd will use
• Checking the version of the detected package manager

---

completion

Generate shell completion scripts for jpd commands.

Usage

jpd completion <shell> [flags]

Supported Shells

• bash
• zsh
• fish
• powershell
• nushell

Flags

Flag	Description
--output, -o	Write completion to a file instead of stdout (all shells)

Installation Examples

Bash

# System-wide installation
jpd completion bash > /etc/bash_completion.d/jpd

# User installation
jpd completion bash > ~/.bash_completion.d/jpd

# Add to .bashrc
echo 'source <(jpd completion bash)' >> ~/.bashrc

Zsh

# Add to .zshrc
echo 'autoload -U compinit; compinit' >> ~/.zshrc
jpd completion zsh > ~/.zsh/completions/_jpd

# Or use Oh My Zsh
jpd completion zsh > ~/.oh-my-zsh/completions/_jpd

Fish

jpd completion fish > ~/.config/fish/completions/jpd.fish

PowerShell

jpd completion powershell | Out-String | Invoke-Expression

# Add to profile
jpd completion powershell >> $PROFILE

Nushell

# Generate completion file
jpd completion nushell --output ~/.config/nushell/completions/jpd_completions.nu

# Add to config.nu or env.nu
echo 'source ~/.config/nushell/completions/jpd_completions.nu' >> ~/.config/nushell/config.nu

---

Debug Mode

Enable verbose logging with the --debug flag to see exactly what commands jpd is executing:

jpd install --debug
jpd run build --debug
jpd exec create-react-app my-app --debug

Debug Output

Debug mode shows:

• Package manager detection process
• Lock file analysis
• Volta detection status
• Exact commands being executed
• Command execution results

Example debug output:

DEBUG Package manager detection started
DEBUG Lock file detected: package-lock.json
DEBUG Package manager detected: npm
DEBUG Volta detected: true
DEBUG Executing command: npm install
INFO Using npm

---

Working Directory (—cwd)

The --cwd flag allows you to run jpd commands in a different directory without changing your shell’s working directory.

Usage

jpd <command> --cwd <path> [args...]

Path Requirements

Trailing Slash Required

The --cwd flag requires paths to end with / except for the root directory /.

Examples

# Install dependencies in a subdirectory
jpd install --cwd ./my-frontend-app/

# Run build script in a package
jpd run --cwd ./packages/ui/ build

# Root directory (no trailing slash needed)
jpd install --cwd /

# Invalid - missing trailing slash
jpd install --cwd ./my-app  # ❌ Error

# Valid - with trailing slash
jpd install --cwd ./my-app/ # ✅ OK

CI Build Behavior

When jpd is compiled with the CI build flag (-ldflags "-X github.com/louiss0/javascript-package-delegator/build_info.rawCI=true"), the trailing slash requirement is relaxed:

# In CI mode, both work:
jpd install --cwd ./my-app   # ✅ OK in CI
jpd install --cwd ./my-app/  # ✅ OK always

Use Cases

• Monorepos: Run commands in different workspaces
• Build scripts: Execute commands in subdirectories without cd
• CI/CD: Install dependencies in specific project folders
• Development: Test commands in different project structures

---

integrate

Generate integration files for external tools like Warp terminal and Carapace.

Usage

jpd integrate <target> [flags]

Supported Targets

• warp - Generate Warp terminal workflow files
• carapace - Generate Carapace completion spec

Warp Integration

Generate workflow files for Warp terminal:

# Generate individual workflow files
jpd integrate warp --output-dir ./workflows/

# Print workflows as multi-document YAML
jpd integrate warp

Creates workflow files for:

• jpd-install.yaml - Package installation with interactive prompts
• jpd-run.yaml - Script execution
• jpd-exec.yaml - Package execution
• jpd-dlx.yaml - Package runner execution
• jpd-update.yaml - Package updates
• jpd-uninstall.yaml - Package removal
• jpd-clean-install.yaml - Clean installation
• jpd-agent.yaml - Package manager detection

Carapace Integration

Generate spec file for Carapace universal completion:

# Install spec to global Carapace directory
jpd integrate carapace

# Write spec to custom file
jpd integrate carapace --output ./jpd.yaml

# Print spec to stdout
jpd integrate carapace --stdout

Installation Locations

Platform	Default Path
Linux/macOS	~/.local/share/carapace/specs/javascript-package-delegator.yaml
Windows	%APPDATA%\carapace\specs\javascript-package-delegator.yaml
Custom	Set XDG_DATA_HOME to override on Unix systems

Flags

Flag	Description	Applies To
--output-dir	Output directory for workflow files	Warp
--output, -o	Output file for spec	Carapace
--stdout	Print spec to stdout instead of installing	Carapace

---

See Also

• completion — shell completion scripts
• agent — inspect detected package manager
• Getting Started Tutorial - Learn jpd basics
• Interactive Workflows - Master search and selection features
• Mental Model - Learn the Why/What/How design philosophy