Command Reference - PRPM Documentation

Package Discovery Commands

search

Search for packages in the PRPM registry (keyword-based).

prpm search <query> [options]

Arguments:

query - Search term to find packages

Options:

--format <format> - Filter by format (cursor, claude, windsurf, continue, etc.)
--subtype <subtype> - Filter by subtype (rule, agent, skill, slash-command, etc.)
--limit <number> - Maximum number of results to return (default: 20)
--no-interactive - Disable interactive pagination (useful for automation and scripting)

Note: Interactive mode is enabled by default when there are multiple pages of results. Use --no-interactive when you want to search and install packages programmatically in scripts or CI/CD environments. Examples:

# Basic search (interactive by default)
prpm search typescript

# Filter by format
prpm search react --format cursor

# Filter by subtype
prpm search coding --subtype rule

# Disable interactive mode for automation
prpm search python --no-interactive

# Use in scripts/CI/CD pipelines
prpm search typescript --format cursor --no-interactive | head -n 1

Output: Displays matching packages with their name, description, format, downloads, and installation command.

ai-search

AI-powered semantic search for finding packages using natural language (no login required).

prpm ai-search "<natural-language-query>" [options]

Arguments:

query - Natural language description of what you need

Options:

--limit <number> - Number of results to return (default: 10)
--format <format> - Filter by format (cursor, claude, windsurf, continue, etc.)
--subtype <subtype> - Filter by subtype (rule, agent, skill, slash-command, etc.)

Examples:

# Find packages using natural language
prpm ai-search "I need help with React state management best practices"

# Limit results
prpm ai-search "Python type safety" --limit 5

# Filter by format
prpm ai-search "code review assistant" --format claude

# Filter by subtype
prpm ai-search "API documentation generator" --subtype agent

How it works:

Uses AI embeddings to understand semantic meaning
Matches your intent rather than just keywords
Ranks results by relevance, quality, and popularity
100% free with no authentication required
Faster and more accurate than keyword search for complex queries

Output: Displays matching packages with similarity scores, descriptions, match quality, and installation commands.

info

Display detailed information about a specific package.

prpm info <package-name>

Arguments:

package-name - Full package name (e.g., @username/typescript-rules)

Options:

--json - Output in JSON format
--version <version> - Show info for a specific version

Examples:

# View package details
prpm info @username/typescript-best-practices

# View specific version
prpm info @username/typescript-best-practices --version 1.2.0

# JSON output for scripting
prpm info @username/typescript-rules --json

Output: Shows package name, version, description, author, format, subtype, dependencies, installation instructions, and README content.

show

Preview package contents before installing. Downloads and extracts the package to display its files without modifying your project.

prpm show <package> [options]

Arguments:

package - Package ID to show (e.g., @username/package or @username/package@1.0.0)

Options:

--full - Show complete file contents (not just file list)
--file <name> - Show contents of a specific file
--json - Output in JSON format (for programmatic use)

Examples:

# Preview package files
prpm show @username/typescript-rules

# View complete file contents
prpm show @username/typescript-rules --full

# View a specific file
prpm show @username/typescript-rules --file SKILL.md

# View specific version
prpm show @username/typescript-rules@2.0.0

# JSON output for scripting
prpm show @username/typescript-rules --json

Output: Displays package metadata (name, version, format, subtype), a list of all files with their sizes, and optionally the full file contents. Binary files are detected and marked as [binary]. Use Cases:

Inspect package contents before installing
Verify package structure and file organization
Review code/rules before adding to your project
Audit packages for security or quality

View trending packages from the registry.

prpm trending [options]

Options:

--format <format> - Filter by format
--subtype <subtype> - Filter by subtype
--limit <number> - Number of packages to display (default: 10)
--period <period> - Time period (day, week, month) (default: week)

Examples:

# View trending packages
prpm trending

# Trending Cursor rules this month
prpm trending --format cursor --period month

# Top 20 trending agents
prpm trending --subtype agent --limit 20

starred

List your starred packages and collections.

prpm starred [options]

Options:

--packages - Show only starred packages
--collections - Show only starred collections
--format <format> - Filter packages by format (cursor, claude, continue, windsurf, etc.)
--limit <number> - Maximum number of items to fetch (default: 100)

Prerequisites:

Must be logged in (prpm login)

Examples:

# List all starred items (packages and collections)
prpm starred

# Show only starred packages
prpm starred --packages

# Show only starred collections
prpm starred --collections

# Filter by format
prpm starred --packages --format cursor

# Limit results
prpm starred --limit 20

Output: Displays starred items with their name, description, format/category, downloads/stars, and last update time. Tip: Star packages and collections on the web interface at https://prpm.dev to save your favorites for easy access later.

collections

Browse and view curated collections of packages.

prpm collections [options]
prpm collections <collection-name>

Options:

--list - List all available collections
--install - Install all packages in a collection

Examples:

# List all collections
prpm collections --list

# View a specific collection
prpm collections web-development

# Install all packages in a collection
prpm collections web-development --install

Package Management Commands

install

Install one or more packages from the registry.

prpm install <package-name> [additional-packages...] [options]

Arguments:

package-name - Package to install (supports multiple packages)

Options:

--version <version> - Install a specific version
--as <format> - Convert and install in specific format (cursor, claude, continue, windsurf, copilot, kiro, agents.md, canonical). For MCP servers, specifies the target editor (claude, codex, cursor, windsurf, vscode, gemini, opencode, kiro, trae, amp, zed)
--format <format> - Alias for --as
--subtype <subtype> - Specify subtype when converting (skill, agent, rule, etc.)
--location <path> - Custom installation location (Cursor and agents.md only)
--global - Install MCP servers to global config (e.g., ~/.claude/settings.json)
--frozen-lockfile - Fail if lock file needs to be updated (for CI)
--eager - Force skill/agent to always activate at session start (not on-demand)
--lazy - Use default on-demand activation (overrides package eager setting)

Examples:

# Install a package
prpm install @username/typescript-best-practices

# Install multiple packages
prpm install @username/typescript-rules1 @username/typescript-rules2 @username/typescript-rules3

# Install specific version
prpm install @username/typescript-rules --version 2.1.0

# Install and convert to Cursor format
prpm install @username/typescript-rules --as cursor

# Install and convert to Claude format
prpm install @username/typescript-rules --format claude

# Install to custom location (Cursor rules in monorepo)
prpm install @username/react-rules --as cursor --location packages/frontend

# Install agents.md to custom directory
prpm install @username/project-context --as agents.md --location docs

# Frozen lockfile (for CI)
prpm install @username/typescript-rules --frozen-lockfile

# Install skill with eager activation (always active)
prpm install @username/code-style --as agents.md --eager

# Install with lazy activation (on-demand, default)
prpm install @username/debugging-helper --as agents.md --lazy

# Install MCP server for a specific editor
prpm install @org/my-mcp-server --as cursor
prpm install @org/my-mcp-server --as codex

# Install MCP server globally
prpm install @org/my-mcp-server --as vscode --global

What happens during installation:

Package is downloaded from the registry
Files are extracted to the appropriate directory (.cursor/, .claude/, etc.)
Package is registered in prpm.lock
Format-specific configuration is applied (MDC headers for Cursor, etc.)

Custom Locations (--location): The --location flag allows you to install packages to custom directories. This is useful for:

Monorepos: Install Cursor rules in specific packages (e.g., --location packages/backend creates packages/backend/.cursor/rules/)
Nested projects: Keep different contexts in subdirectories
Agents.md: Create AGENTS.override.md in custom locations (e.g., --location docs creates docs/AGENTS.override.md)

Supported formats:

cursor - Installs to nested .cursor/ directory within the specified path
agents.md - Creates AGENTS.override.md in the specified path

Eager vs Lazy Activation (--eager / --lazy): These flags control how skills and agents are loaded in progressive disclosure formats (agents.md, gemini.md, claude.md, aider):

Lazy (default): Skills/agents are available but only activated when relevant based on their description. The AI decides when to use them.
Eager: Skills/agents are loaded at the START of every session. Always active, no activation needed.

Mode	When Loaded	Use Case
Lazy	On-demand when relevant	Most skills - keeps context clean
Eager	Every session start	Critical skills that should always apply

Precedence: CLI flag (--eager/--lazy) > file-level setting > package-level setting > default (lazy) Applies to: Skills and agents in progressive disclosure formats only. Rules, hooks, and other subtypes are not affected. Example directory structure:

# Install to packages/frontend
prpm install @user/react-rules --as cursor --location packages/frontend

# Result:
packages/
  frontend/
    .cursor/
      rules/
        react-rules.mdc

uninstall

Remove installed packages from your project.

prpm uninstall <package-id> [additional-packages...] [options]

Arguments:

package-id - ID of the package to uninstall

Options:

--force - Skip confirmation prompts
--keep-files - Remove from lock file but keep the files

Examples:

# Uninstall a package
prpm uninstall @username/typescript-best-practices

# Uninstall multiple packages
prpm uninstall package1 package2 package3

# Uninstall without confirmation
prpm uninstall package-name --force

list

List all installed packages in the current project.

prpm list [options]

Options:

--format <format> - Filter by format
--subtype <subtype> - Filter by subtype
--json - Output in JSON format
--verbose - Show additional details (file paths, versions)

Examples:

# List all packages
prpm list

# List only Cursor packages
prpm list --format cursor

# List all agents
prpm list --subtype agent

# Detailed output
prpm list --verbose

# JSON output
prpm list --json

Output: Shows package ID, format, subtype, version, and file path for each installed package.

outdated

Check for packages that have newer versions available.

prpm outdated [options]

Options:

--json - Output in JSON format

Examples:

# Check for outdated packages
prpm outdated

# JSON output for scripting
prpm outdated --json

Output: Displays packages with their current version, latest available version, and update command.

update

Update specific packages to their latest versions.

prpm update <package-name> [additional-packages...] [options]

Arguments:

package-name - Package(s) to update

Options:

--version <version> - Update to a specific version
--force - Force update even if at latest version

Examples:

# Update a single package
prpm update @username/typescript-rules

# Update multiple packages
prpm update package1 package2 package3

# Update to specific version
prpm update package-name --version 2.5.0

upgrade

Upgrade all installed packages to their latest versions.

prpm upgrade [options]

Options:

--dry-run - Show what would be upgraded without making changes
--interactive - Prompt for confirmation for each package
--skip-breaking - Skip packages with breaking changes (major version bumps)

Examples:

# Upgrade all packages
prpm upgrade

# Preview upgrades
prpm upgrade --dry-run

# Interactive upgrades
prpm upgrade --interactive

Package Creation Commands

init

Initialize a new PRPM package or scan directories to discover existing packages.

prpm init [directories...] [options]

Arguments:

directories - Directories to scan (only used with --scan)

Options:

-y, --yes - Use default values, skip prompts
--private - Create a private package
-f, --force - Overwrite existing prpm.json if present
-s, --scan - Scan mode: discover packages in directories without prompts
-o, --output <path> - Output path for prpm.json (scan mode only)
-a, --append - Append to existing prpm.json instead of overwriting (scan mode only)
--dry-run - Show what would be discovered without making changes (scan mode only)

Interactive Prompts (standard mode):

Package name
Version
Description
Format (cursor, claude, windsurf, etc.)
Subtype (rule, agent, skill, etc.)
Author name
License
Repository URL
Tags
Files to include

Examples:

# Interactive initialization
prpm init

# Use defaults
prpm init --yes

# Create private package
prpm init --private

# Force overwrite
prpm init --force

# Scan mode: discover packages in current directory
prpm init --scan

# Scan specific directories
prpm init --scan .claude .cursor .windsurf

# Append discovered packages to existing prpm.json
prpm init --scan --append

# Preview what would be discovered
prpm init --scan --dry-run

# Output to custom location
prpm init --scan -o packages.json

What gets created (standard mode):

prpm.json - Package manifest
README.md - Package documentation template
Format-specific example files based on your selection

What scan mode does:

Scans directories for prompt files (.md, .mdc, SKILL.md, etc.)
Detects format (cursor, claude, windsurf, etc.) and subtype (rule, skill, agent)
Extracts package metadata from file content
Filters out packages installed from registry (only discovers user-created content)
Creates/updates prpm.json with discovered packages

publish

Publish packages or collections to the PRPM registry.

prpm publish [options]

Options:

--package <name> - Publish only a specific package from multi-package manifest
--collection <id> - Publish only a specific collection (skips packages)
-l, --list - List all packages in prpm.json without publishing
--dry-run - Test publishing without actually uploading
--tag <tag> - Publish with a specific tag (e.g., beta, next)
--access <public|private> - Set package access level
--force - Skip validation warnings

Prerequisites:

Must be logged in (prpm login)
Must have a valid prpm.json in current directory
Package version must not already exist in registry

Examples:

# Publish everything (all packages + all collections)
prpm publish

# Publish only a specific package
prpm publish --package my-package

# Publish only a specific collection (skips all packages)
prpm publish --collection my-collection

# Test publish (dry run)
prpm publish --dry-run

# Publish specific package as beta
prpm publish --package my-package --tag beta

# Publish private package
prpm publish --access private

# List all packages without publishing
prpm publish --list

Multi-Package Publishing: When your prpm.json has multiple packages or collections:

{
  "name": "my-workspace",
  "packages": [
    { "name": "package-a", ... },
    { "name": "package-b", ... }
  ],
  "collections": [
    { "id": "collection-1", ... },
    { "id": "collection-2", ... }
  ]
}

Publishing Behavior:

prpm publish → Publishes all packages + all collections
prpm publish --package package-a → Publishes only package-a (skips collections)
prpm publish --collection collection-1 → Publishes only collection-1 (skips packages)

What happens during publish:

Package is validated against schema
Files are packaged into a tarball
Package metadata is uploaded to registry
Tarball is uploaded to storage
Package becomes available for installation

Rate Limiting:

Burst capacity: 20 packages can be published immediately
Sustained rate: 10 packages per minute after burst
Requests are automatically queued when rate limit is reached
Maximum queue wait: 30 seconds

Playground Commands

playground

Test packages with real AI models before installing.

prpm playground [options]

Options:

-p, --package <name> - Package name to test (e.g., @user/package-name)
--input <text> - Input text to send to the model (omit for interactive mode)
-m, --model <model> - AI model to use (sonnet, opus, gpt-4o, gpt-4o-mini, gpt-4-turbo) (default: sonnet)
-c, --compare - Compare with and without package prompt (baseline test)
-i, --interactive - Start interactive multi-turn conversation mode
-v, --version <version> - Specific package version to test
--custom <prompt> - Use a custom prompt string (verified authors only)
--prompt-file <file> - Load custom prompt from a file (verified authors only)

Examples:

# Basic test
prpm playground --package @user/code-reviewer --input "Review this: console.log('hello')"

# Interactive conversation
prpm playground --package @user/brainstorm-assistant --interactive

# Compare mode (with and without prompt)
prpm playground --package @user/optimizer --input "Optimize this function" --compare

# Use a specific model
prpm playground --package @user/complex-task --input "Analyze this" --model opus
prpm playground --package @user/simple-task --input "Format this" --model gpt-4o-mini

# Test specific version
prpm playground --package @user/my-package --version 2.1.0 --input "Test this"

# Custom prompt (verified authors only)
prpm playground --custom "You are a helpful assistant" --input "Hello"
prpm playground --prompt-file my-prompt.txt --input "Test"

Supported Models:

sonnet (Claude Sonnet 3.5) - Balanced performance, 2 credits (default)
gpt-4o-mini - Fast and economical, 1 credit
gpt-4o - Advanced reasoning, 3 credits
gpt-4-turbo - Complex tasks, 4 credits
opus (Claude Opus) - Most capable, 7 credits

Credits:

1 credit = 5,000 tokens (input + output combined)
Free tier: 5 trial credits
PRPM+: 100 monthly credits ($6/month)
Credit packs: Buy additional credits that never expire

See the Playground Guide for detailed information.

Manage your PRPM+ subscription.

prpm subscribe [command]

Commands:

(no command) - Subscribe to PRPM+
status - View subscription status and credit balance
cancel - Cancel your PRPM+ subscription

Examples:

# Subscribe to PRPM+
prpm subscribe

# Check subscription status and credits
prpm subscribe status

# Cancel subscription
prpm subscribe cancel

PRPM+ Benefits:

100 monthly playground credits
Credits roll over (max 200 balance)
$6/month (or$ 3/month for organization members)
Priority support

credits

Check your playground credits balance and transaction history.

prpm credits [options]

Options:

-h, --history - Show transaction history instead of balance
-l, --limit <number> - Number of transactions to show in history (default: 10)

Examples:

# Check credit balance
prpm credits

# View transaction history
prpm credits --history

# View last 20 transactions
prpm credits --history --limit 20

Output:

Without --history: Displays current credit balance, monthly allotment (if PRPM+ subscriber), and next renewal date
With --history: Shows recent credit transactions including purchases, usage, monthly credits, and rollover

buy-credits

Purchase additional playground credits.

prpm buy-credits

Opens an interactive prompt to select and purchase credit packs. Credit Packs:

100 credits = $5.00
Credits never expire
Stack with monthly PRPM+ credits

Examples:

# Open credit purchase flow
prpm buy-credits

suggested-inputs

Manage suggested test inputs for your packages (authors only).

prpm suggested-inputs <command> <package> [input]

Commands:

add <package> <input> - Add a suggested test input
list <package> - List all suggested inputs for a package
remove <package> <id> - Remove a suggested input

Examples:

# Add suggested input
prpm suggested-inputs add @user/my-package "Review this authentication code"

# List all inputs
prpm suggested-inputs list @user/my-package

# Remove an input
prpm suggested-inputs remove @user/my-package abc123

What it does: Suggested inputs appear automatically in the playground web interface, making it easier for users to test your package with relevant examples.

Local File Management Commands

index

Scan your project directories for existing prompt files and register them in PRPM.

prpm index [options]

Options:

--verbose - Show detailed output for each file

Scanned Directories:

.cursor/rules/ - Cursor rules
.cursor/agents/ - Cursor agents
.cursor/commands/ - Cursor slash commands
.claude/agents/ - Claude agents
.claude/skills/ - Claude skills
.claude/commands/ - Claude slash commands
.continue/rules/ - Continue rules
.windsurf/rules/ - Windsurf rules
.prompts/ - Generic prompts
.mcp/ - MCP servers

Examples:

# Index local files
prpm index

# Verbose output
prpm index --verbose

Output: Shows how many files were found and registered in each directory, and updates prpm.lock.

convert

Convert AI prompt files between different formats (e.g., Cursor to Claude, Claude to Windsurf).

prpm convert <source-file> [options]

Arguments:

source-file - Path to the file you want to convert

Options:

-t, --to <format> - Target format (cursor, claude, windsurf, kiro, copilot, continue, agents.md)
-s, --subtype <subtype> - Target subtype (agent, skill, slash-command, rule, prompt, etc.)
-o, --output <path> - Custom output path (defaults to format-specific location)
-y, --yes - Skip confirmation prompts

Examples:

# Convert Cursor rule to Claude skill
prpm convert .cursor/rules/my-rule.mdc --to claude --subtype skill

# Convert Claude agent to Windsurf rule
prpm convert .claude/agents/my-agent.md --to windsurf

# Convert to Copilot with custom output
prpm convert my-prompt.md --to copilot --output .github/instructions/custom.instructions.md

# Auto-detect source format and convert to Continue
prpm convert some-file.md --to continue --subtype rule

# Skip confirmation prompts
prpm convert .claude/skills/helper/SKILL.md --to cursor --yes

How it works:

Auto-detects the source format from file content and location
Parses the source file to extract content and metadata
Converts to canonical intermediate format
Transforms to target format with appropriate structure
Writes to format-specific default location or custom output path

Default Output Locations:

Cursor: .cursor/rules/*.mdc (rules) or .cursor/commands/*.md (commands)
Claude: .claude/skills/*/SKILL.md (skills), .claude/agents/*.md (agents), .claude/commands/*.md (commands)
Windsurf: .windsurf/rules/*.md
Continue: .continue/rules/*.md (rules) or .continue/prompts/*.md (prompts)
Copilot: .github/instructions/*.instructions.md
Kiro: .kiro/steering/*.md (steering) or .kiro/hooks/*.kiro.hook (hooks)
Agents.md: agents.md (root file)

Supported Conversions: All formats can be converted to all other formats with intelligent content preservation and format-specific adaptations.

User Management Commands

Authenticate with the PRPM registry.

prpm login [options]

Options:

--token <token> - Use an existing authentication token

Examples:

# Interactive login
prpm login

# Login with token
prpm login --token your-auth-token

# Login to custom registry (set registry URL first)
PRPM_REGISTRY_URL=https://custom-registry.example.com prpm login
# Or configure permanently:
prpm config set registryUrl https://custom-registry.example.com
prpm login

Authentication Flow:

Opens browser for authentication (or uses provided token)
Saves authentication token to ~/.prpmrc
Token is used for future authenticated requests

whoami

Display information about the currently authenticated user.

prpm whoami [options]

Options:

--json - Output in JSON format

Examples:

# Show current user
prpm whoami

# JSON output
prpm whoami --json

Output: Displays username, email, and authentication status.

Configuration Commands

config

View or modify CLI configuration.

prpm config <action> [key] [value]

Subcommands:

list (or ls) - List all configuration values
get <key> - Get a configuration value
set <key> <value> - Set a configuration value
delete <key> (or rm) - Reset a configuration value to default

Configuration Keys: Readable keys:

registryUrl - Registry URL
telemetryEnabled - Telemetry enabled (true/false)
token - Authentication token (set via prpm login)
username - Username (set via prpm login)

Settable keys:

registryUrl - Change the registry URL
telemetryEnabled - Enable or disable telemetry

Note: token and username are managed via prpm login and cannot be set directly. Examples:

# List all configuration
prpm config list
# or just:
prpm config

# Get a specific value
prpm config get registryUrl
prpm config get telemetryEnabled

# Set registry URL
prpm config set registryUrl https://custom-registry.dev

# Enable telemetry
prpm config set telemetryEnabled true

# Disable telemetry
prpm config set telemetryEnabled false

# Reset a value to default
prpm config delete registryUrl
prpm config delete telemetryEnabled

Telemetry values: When setting telemetryEnabled, you can use:

true, 1, yes - Enable telemetry
false, 0, no - Disable telemetry

telemetry

Manage anonymous usage telemetry.

prpm telemetry <action>

Actions:

enable - Enable telemetry
disable - Disable telemetry
status - Show current telemetry status

Examples:

# Check status
prpm telemetry status

# Enable telemetry
prpm telemetry enable

# Disable telemetry
prpm telemetry disable

What we collect:

Command usage (anonymized)
Error messages (anonymized)
Installation success/failure rates
Package popularity

We do NOT collect:

Personal information
File contents
Project details
Authentication tokens

schema

View or validate package schemas.

prpm schema [options]

Options:

--validate <file> - Validate a package manifest against schema
--format <format> - Show schema for a specific format
--output <file> - Write schema to file

Examples:

# View main package schema
prpm schema

# Validate your package
prpm schema --validate prpm.json

# Get schema for specific format
prpm schema --format cursor

# Save schema to file
prpm schema --output schema.json

Exit Codes

The PRPM CLI uses standard exit codes:

0 - Success
1 - General error
2 - Invalid arguments or usage
3 - Network error
4 - Authentication error
5 - Package not found
6 - Validation error

These can be useful when scripting with PRPM:

#!/bin/bash
if prpm install @username/typescript-rules; then
  echo "Installation successful"
else
  echo "Installation failed with code $?"
fi

Environment Variables

PRPM respects these environment variables:

PRPM_REGISTRY_URL - Override default registry URL
PRPM_TOKEN - Authentication token
PRPM_TELEMETRY - Enable/disable telemetry (true/false)
PRPM_CONFIG_PATH - Custom config file location
NO_COLOR - Disable colored output

Example:

PRPM_REGISTRY_URL=https://custom.registry.dev prpm search typescript

​Package Discovery Commands

​search

​ai-search

​info

​show

​trending

​popular

​starred

​collections

​Package Management Commands

​install

​uninstall

​list

​outdated

​update

​upgrade

​Package Creation Commands

​init

​publish

​Playground Commands

​playground

​subscribe

​credits

​buy-credits

​suggested-inputs

​Local File Management Commands

​index

​convert

​User Management Commands

​login

​whoami

​Configuration Commands

​config

​telemetry

​schema

​Exit Codes

​Environment Variables

Package Discovery Commands

search

ai-search

info

show

trending

popular

starred

collections

Package Management Commands

install

uninstall

list

outdated

update

upgrade

Package Creation Commands

init

publish

Playground Commands

playground

subscribe

credits

buy-credits

suggested-inputs

Local File Management Commands

index

convert

User Management Commands

login

whoami

Configuration Commands

config

telemetry

schema

Exit Codes

Environment Variables