ccpi CLI Command Reference

Overview

ccpi (Claude Code Plugin Installer) is the official CLI for managing Claude Code plugins from the Tons of Skills marketplace. It handles plugin discovery, installation, updates, removal, and validation from the command line.

The package is published to npm as @intentsolutionsio/ccpi and can be installed globally or used via npx.

# Install globally
npm install -g @intentsolutionsio/ccpi

# Or use via npx (no install required)
npx @intentsolutionsio/ccpi <command>

Once installed, all commands are available under the ccpi binary.

Command Reference

ccpi install

Install a plugin from the marketplace or a Git repository.

Syntax:

ccpi install <plugin>

Arguments:

Examples:

# Install by marketplace name
ccpi install ci-optimizer

# Install from a GitHub repository
ccpi install jeremylongshore/claude-code-plugins

# Install a specific plugin from a monorepo
ccpi install jeremylongshore/claude-code-plugins --path plugins/devops/ci-optimizer

Behavior:

1. Resolves the plugin name against the marketplace catalog
2. Clones the plugin repository to the local plugin directory
3. Validates the plugin structure (checks for plugin.json, required fields)
4. Registers the plugin with Claude Code

If the plugin is already installed, ccpi install reports the current version and prompts for update if a newer version is available.

Exit codes:

ccpi list

List all installed plugins.

Syntax:

ccpi list

Options:

This command takes no options. It scans the local plugin directory and displays all installed plugins with their name, version, and category.

Example output:

Installed plugins:

  ci-optimizer          v2.1.0    devops
  react-scaffolder      v1.3.2    frontend-development
  terraform-drift       v1.0.0    cloud-infrastructure
  security-scanner      v3.0.1    security

4 plugins installed

Behavior:

1. Scans the Claude Code plugin directory for installed plugins
2. Reads each plugin’s plugin.json to extract metadata
3. Displays a formatted table sorted alphabetically by name

ccpi search

Search the marketplace catalog for plugins matching a query.

Syntax:

ccpi search <query>

Arguments:

Examples:

# Search by keyword
ccpi search terraform

# Search by category
ccpi search devops

# Search by problem domain
ccpi search "code review"

# Search by technology
ccpi search kubernetes

Example output:

Search results for "terraform":

  terraform-drift-detector    v2.1.0    devops
    Detect and remediate Terraform configuration drift

  terraform-module-gen        v1.4.0    cloud-infrastructure
    Generate Terraform modules from architecture diagrams

  iac-validator               v1.2.0    devops
    Validate infrastructure-as-code across Terraform, Pulumi, CDK

3 results found

Behavior:

1. Fetches the marketplace catalog (cached locally, refreshed periodically)
2. Runs a fuzzy search across plugin names, descriptions, keywords, and categories
3. Ranks results by relevance
4. Displays matching plugins with name, version, category, and description

Search ranking factors:

ccpi update

Update one or all installed plugins to their latest versions.

Syntax:

ccpi update [plugin]

Arguments:

Examples:

# Update a specific plugin
ccpi update ci-optimizer

# Update all installed plugins
ccpi update

Example output:

Checking for updates...

  ci-optimizer      v2.1.0 → v2.2.0    updated
  react-scaffolder  v1.3.2              up to date
  security-scanner  v3.0.1 → v3.1.0    updated

2 plugins updated, 1 already up to date

Behavior:

1. Reads the installed version from each plugin’s plugin.json
2. Fetches the latest version from the marketplace catalog
3. If a newer version is available, pulls the updated plugin
4. Validates the updated plugin structure
5. Reports the update results

Version comparison: Uses semantic versioning (SemVer) comparison. A version 2.2.0 is newer than 2.1.0. Pre-release versions (e.g., 2.2.0-beta.1) are not automatically installed unless already on a pre-release track.

ccpi remove

Remove an installed plugin.

Syntax:

ccpi remove <plugin>

Arguments:

Examples:

# Remove a plugin
ccpi remove ci-optimizer

Example output:

Removed ci-optimizer v2.1.0

Behavior:

1. Locates the plugin in the local plugin directory
2. Removes the plugin directory and all its contents
3. Deregisters the plugin from Claude Code

If the plugin is not found, the command exits with an error and lists installed plugins.

Data persistence: Plugin data stored in ${CLAUDE_PLUGIN_DATA} is not removed by ccpi remove. This directory persists across installs and removals, preserving user-generated state. To fully clean up, manually delete the data directory after removal.

ccpi validate

Validate plugin structure and schema compliance.

Syntax:

ccpi validate [--strict]

Options:

Examples:

# Standard validation
ccpi validate

# Strict validation (CI mode)
ccpi validate --strict

Example output (passing):

Validating plugin structure...

  plugin.json          valid
  README.md            present
  skills/              2 skills found
    code-review        valid (7 tools)
    lint-fix           valid (5 tools)
  commands/            1 command found
    analyze            valid

Validation passed (0 errors, 0 warnings)

Example output (failing):

Validating plugin structure...

  plugin.json          valid
  README.md            MISSING
  skills/              2 skills found
    code-review        valid (7 tools)
    lint-fix           ERROR: unknown tool "Readfile"

Validation failed (1 error, 1 warning)
  ERROR: skills/lint-fix/SKILL.md - unknown tool "Readfile" in allowed-tools
  WARNING: README.md is missing

Checks performed:

Behavior:

1. Scans the current directory (or specified path) for plugin structure
2. Validates plugin.json against the schema
3. Validates each SKILL.md frontmatter against the skill schema
4. Validates each command and agent markdown frontmatter
5. Reports all errors and warnings
6. Exits with code 0 (pass) or 1 (fail)

For more comprehensive validation, use the universal validator with the --enterprise flag. See the Validation section below.

ccpi marketplace add

Add a marketplace source for plugin discovery. This enables ccpi search and ccpi install to find plugins from the specified repository.

Syntax:

ccpi marketplace add <repo>

Arguments:

Examples:

# Add the Tons of Skills marketplace
ccpi marketplace add jeremylongshore/claude-code-plugins

Behavior:

1. Fetches the marketplace.json catalog from the specified repository
2. Caches the catalog locally for offline search
3. Registers the source for future ccpi search and ccpi install commands

The default marketplace source is the Tons of Skills catalog hosted at tonsofskills.com/catalog.json. Adding additional sources allows organizations to host private plugin catalogs alongside the public marketplace.

ccpi info

Display detailed information about a plugin.

Syntax:

ccpi info <plugin>

Arguments:

Examples:

# Show plugin details
ccpi info ci-optimizer

Example output:

ci-optimizer v2.1.0

  Description:  Optimize CI/CD pipeline configurations for faster builds
  Author:       Jane Smith <jane@example.com>
  License:      MIT
  Category:     devops
  Repository:   https://github.com/janesmith/ci-optimizer
  Homepage:     https://ci-optimizer.dev

  Keywords:     ci, cd, pipeline, optimization, github-actions, gitlab-ci

  Skills:       2
    pipeline-audit        Audit CI pipeline for performance issues
    config-optimizer      Generate optimized CI configurations

  Commands:     1
    analyze               Run CI analysis on current project

  Installed:    Yes (v2.1.0, up to date)

Behavior:

1. Looks up the plugin in the marketplace catalog
2. If installed locally, reads the local plugin.json for installed version
3. Displays all metadata fields and lists skills, commands, and agents
4. Indicates whether the plugin is installed and up to date

Common Workflows

First-Time Setup

Install the CLI and add the Tons of Skills marketplace:

npm install -g @intentsolutionsio/ccpi
ccpi marketplace add jeremylongshore/claude-code-plugins

Discover and Install Plugins

Search for plugins by keyword, review details, then install:

ccpi search "code review"
ccpi info code-reviewer
ccpi install code-reviewer

Keep Plugins Updated

Periodically check for and apply updates:

ccpi update

Validate Before Publishing

Run validation locally before submitting a plugin to the marketplace:

cd plugins/category/my-plugin/
ccpi validate --strict

For enterprise-grade validation, use the universal validator:

python3 scripts/validate-skills-schema.py --enterprise --verbose plugins/category/my-plugin/

Clean Up Unused Plugins

List installed plugins, review what is no longer needed, and remove:

ccpi list
ccpi remove old-plugin

Catalog Caching

The ccpi CLI caches the marketplace catalog locally to enable fast searches and reduce network requests. Understanding the cache behavior helps troubleshoot stale search results.

Cache Location

The catalog cache is stored in the user’s local data directory. The exact path depends on the operating system:

Cache Refresh

The cache refreshes automatically when:

• ccpi search is run and the cache is older than 24 hours
• ccpi update is run (always fetches fresh catalog)
• ccpi marketplace add is run (fetches and caches the new source)

To force a cache refresh, delete the cache file or run ccpi update.

Validation Pipeline

The ccpi validate command provides quick structural validation suitable for development. For comprehensive validation, the ecosystem provides a multi-tier pipeline:

For marketplace submissions, plugins must pass at minimum the strict tier. The enterprise tier provides a compliance score and letter grade (A through F) used for marketplace quality rankings.

# Quick check during development
ccpi validate

# Pre-submission check
ccpi validate --strict

# Enterprise compliance score
python3 scripts/validate-skills-schema.py --enterprise --verbose plugins/category/your-plugin/

# Full CI simulation (runs all checks)
./scripts/quick-test.sh

Exit Codes

All ccpi commands follow standard Unix exit code conventions:

Scripts and CI pipelines can check exit codes to determine command success:

ccpi validate --strict || echo "Validation failed"

Global Options

These options are available on all ccpi commands:

# Show help
ccpi --help
ccpi install --help

# Show version
ccpi --version

Environment Variables

Set environment variables in your shell profile for persistent configuration:

# ~/.bashrc or ~/.zshrc
export CCPI_CATALOG_URL="https://internal.company.com/plugins/catalog.json"

Troubleshooting

”Plugin not found” on install

The marketplace catalog may be stale. Force a refresh:

ccpi update  # Refreshes the catalog cache
ccpi search <plugin-name>  # Verify the plugin exists
ccpi install <plugin-name>

Search returns no results

Check that a marketplace source is configured:

ccpi marketplace add jeremylongshore/claude-code-plugins
ccpi search <query>

Validation passes locally but fails in CI

CI runs ccpi validate --strict, which treats warnings as errors. Run strict mode locally to reproduce:

ccpi validate --strict

Common strict-mode failures: missing README.md, non-SemVer version strings, invalid SPDX license identifiers.

Plugin installed but not appearing in Claude Code

Restart Claude Code after installing a plugin. Claude Code scans the plugin directory at startup and may not detect newly installed plugins mid-session.