CLI Reference

ppicons-cli

Generate reusable icon components for Prisma PHP and Caspian projects from the terminal. Instead of copying SVG markup by hand, ppicons downloads icon definitions from the remote catalog, normalizes the SVG, writes framework-friendly component files, and refreshes AI-aware metadata files in the target project.

Single Icon

Generate one component with ppicons add <name>.

Full Catalog

Install the entire remote icon set with one command.

AI Metadata

Refresh ppicons.json and Copilot-specific instruction files automatically.

Quick Examples Terminal

npx ppicons add search
npx ppicons add anchor globe rocket
npx ppicons add --all
npx ppicons update

Why Use It

Turn icons into first-class components

UI icon usage gets messy fast when SVGs are copied inline across templates and components. ppicons keeps the icon layer predictable by installing normalized, reusable components into the project.

One source of truth per installed icon.

Consistent SVG normalization and attribute handling.

Predictable file names and import paths across supported frameworks.

Easier refactoring, reuse, and search in the editor.

Machine-readable and AI-readable project metadata for tooling.

Features

What the CLI covers

Capability	What you get
Single icon generation	`ppicons add <name>` downloads and writes one component file.
Bulk generation	`ppicons add --all` generates the full icon catalog in one run.
Update installed icons	`ppicons update` refreshes only the icons already installed in the project.
Dual language support	PHP mode for Prisma PHP and Python mode for Caspian.
Auto-detect language	Detects `caspian.config.json` for Python or `prisma-php.json` for PHP.
Force overwrite	`--force` overwrites existing generated files.
AI-aware outputs	Writes `ppicons.json` and `.github/instructions/ppicons.instructions.md`.
Catalog discovery	Documents and exposes the remote icon catalog endpoints used by the CLI.

Requirements

Runtime prerequisites

Node.js 18+

Network access to https://ppicons.tsnc.tech

A Prisma PHP project or a Caspian project when using the generated components in a real app.

Installation

Global or local setup

Global install npm

npm install -g ppicons

Local dev dependency npm

npm install -D ppicons

Commands

Common CLI workflows

Add one icon CLI

npx ppicons add search

Add multiple icons CLI

npx ppicons add search user settings

Add the full icon set CLI

npx ppicons add --all

Update installed icons CLI

npx ppicons update

Force overwrite CLI

npx ppicons add search --force
npx ppicons add --all --force

Flags

Supported switches

Flag	Description
`--all`	Generate every icon from the remote catalog.
`--force`	Overwrite existing generated icon files.
`--lang php`	Force Prisma PHP and PHPX output.
`--lang py`	Force Caspian Python output.

Language Selection

How mode detection works

If you do not pass --lang, ppicons auto-detects the target mode using the project root:

If caspian.config.json exists, it uses Python mode.

Else if prisma-php.json exists, it uses PHP mode.

Else it falls back to PHP mode.

Explicit examples CLI

npx ppicons add search --lang php
npx ppicons add search --lang py

Generated Output Locations

Where the components land

By default, ppicons writes icon components into src based on the selected language mode.

Mode	Output directory
Prisma PHP and PHPX	`src/Lib/PPIcons`
Caspian Python	`src/lib/ppicons`

The generator converts icon names to PascalCase component file names. Examples: search becomes Search.php or Search.py, and chevron-right becomes ChevronRight.php or ChevronRight.py.

Prisma PHP and PHPX Usage

Generated PHP icons are class-based PHPX components consumed with HTML-first x- tags.

<x-search />
<x-search class="size-4" />

Caspian Usage

Generated Caspian icons are Python components and are intended to be used with JSX-like tags inside templates.

<!-- @import { Search } from ../../lib/ppicons -->

<search />
<search class="size-4" />

AI-aware Project Files

What gets refreshed on add or update

Every successful add or update refreshes project metadata files that help editors, scripts, and AI tools understand the icon setup.

ppicons.json Manifest

This file is the core machine-readable inventory. It includes project type and language mode, framework config metadata, icon output directories, supported commands, remote catalog API endpoints, installed icon inventory, and import entry metadata for the current project mode.

{
  "schemaVersion": 5,
  "generatedAt": "2026-04-19T00:00:00.000Z",
  "project": {
    "type": "prisma-php",
    "framework": "prisma-php",
    "language": "php",
    "detectedBy": "prisma-php.json",
    "rootDirectory": ".",
    "sourceDirectory": "src",
    "configFile": "prisma-php.json",
    "manifestFile": "ppicons.json",
    "componentsDirectory": "src/Lib/PPIcons",
    "iconsDirectory": "src/Lib/PPIcons",
    "copilotInstructionsFile": ".github/instructions/ppicons.instructions.md"
  },
  "commands": {
    "addOne": "npx ppicons add <icon-name>",
    "addMany": "npx ppicons add <icon-a> <icon-b>",
    "addAll": "npx ppicons add --all",
    "updateInstalled": "npx ppicons update"
  },
  "catalogApi": {
    "listAll": {
      "method": "GET",
      "url": "https://ppicons.tsnc.tech/icons?icon=all",
      "returns": "IconRecord[]",
      "purpose": "List all available icons that can be installed."
    },
    "getOne": {
      "method": "GET",
      "urlTemplate": "https://ppicons.tsnc.tech/icons?icon=<icon-name>",
      "exampleUrl": "https://ppicons.tsnc.tech/icons?icon=search",
      "returns": "IconRecord",
      "purpose": "Fetch one icon by name before installing it."
    },
    "responseFields": {
      "id": "number",
      "name": "string",
      "componentName": "string",
      "svg": "string",
      "createdAt": "number",
      "updatedAt": "number"
    }
  }
}

.github/instructions/ppicons.instructions.md

This dedicated instruction file is generated for GitHub Copilot. It includes install commands for new icons, icon discovery API guidance, project-specific usage examples, and notes about the current icon directory and import entry.

.github/copilot-instructions.md

This top-level file is left available for project-owned, always-on Copilot notes. ppicons does not generate or overwrite it.

Icon Discovery API

Inspect the remote catalog directly

If you need to know which icon names are available before installation, use the remote catalog API.

Fetch all icons GET

GET https://ppicons.tsnc.tech/icons?icon=all

Fetch one icon by name GET

GET https://ppicons.tsnc.tech/icons?icon=search

The icon=all endpoint returns a JSON array of icon objects. The single-icon endpoint returns one JSON object.

Example response JSON

{
  "id": 166531,
  "name": "search",
  "componentName": "Search",
  "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"24\" height=\"24\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\" class=\"lucide lucide-search\"><circle cx=\"11\" cy=\"11\" r=\"8\"/><path d=\"m21 21-4.3-4.3\"/></svg>",
  "createdAt": 1774923647142,
  "updatedAt": 1774923647142
}

Field	Meaning
`id`	Numeric record id.
`name`	Icon name used by `ppicons add <name>`.
`componentName`	PascalCase component name that will be generated.
`svg`	Raw SVG markup returned by the catalog.
`createdAt`	Creation timestamp.
`updatedAt`	Update timestamp.

Troubleshooting

Common recovery paths

I wanted PHP mode but Caspian was detected

Force PHP output explicitly:

npx ppicons add search --lang php

Existing files were not overwritten

Use --force:

npx ppicons add search --force

ppicons update says no icon components were found

This means the target icon directory exists but no generated icon files matching the current language mode were found yet. Run an add command first:

npx ppicons add search

Network fetch failed

Check that internet access is available.

Check that your firewall or proxy allows requests to https://ppicons.tsnc.tech.

Check that the icon name exists in the remote catalog.

Contributing

Pull requests and issues are welcome. If you change generation behavior, update the tests and keep the README aligned with the actual CLI behavior.

License

Released under the MIT License.

Author

The Steel Ninja Code

thesteelninjacode@gmail.com