Skip to content
Swarm Icons

CLI Overview

Swarm Icons ships with a command-line tool that handles icon set management without requiring Node.js. It speaks directly to the npm registry and the Iconify API in pure PHP, so you can browse, download, search, update, and export icons from your terminal.

Running the CLI

Section titled “Running the CLI”

The CLI is installed automatically with Composer. Run it from your project root:

Terminal window
php vendor/bin/swarm-icons

This shows the full list of available commands. To get help for any command, add --help:

Terminal window
php vendor/bin/swarm-icons json:download --help

Available commands

Section titled “Available commands”
CommandDescription
json:browseBrowse all 200+ Iconify icon sets with filtering
json:downloadDownload JSON icon collections from npm
json:updateCheck for and apply updates to downloaded sets
icon:searchSearch icons by name across sets
icon:listList all icons in a local directory or Iconify set
icon:exportExport icons from a JSON collection as standalone SVG files
cache:clearClear the icon cache
cache:warmPre-fetch icons into the cache for production
initGenerate a starter configuration file

Typical workflow

Section titled “Typical workflow”

A common workflow when starting a new project:

Terminal window
# 1. Browse what's available
php vendor/bin/swarm-icons json:browse --search=material


# 2. Download the sets you need
php vendor/bin/swarm-icons json:download mdi tabler heroicons


# 3. Search for specific icons
php vendor/bin/swarm-icons icon:search tabler arrow


# 4. Later, check for updates
php vendor/bin/swarm-icons json:update --dry-run

The manifest

Section titled “The manifest”

Downloads are tracked in a swarm-icons.json file at your project root. This manifest records both the set prefixes and their npm versions, enabling two features:

  • Restore after a fresh clone: running php vendor/bin/swarm-icons json:download with no arguments re-downloads everything in the manifest.
  • Update detection: json:update compares stored versions against npm to find newer releases.

You can automate restoration by adding a Composer script:

"scripts": {
    "post-install-cmd": ["swarm-icons json:download"],
    "post-update-cmd":  ["swarm-icons json:download"]
}

What’s next

Section titled “What’s next”