Every Iconify icon from one Go binary, plus a local index that answers set-coverage, migration, and audit questions no icon tool answers today.
Search 236 icon sets and roughly 294,000 icons, fetch any icon as a recoloured SVG, and generate CSS or bulk JSON for a build step. The local SQLite mirror turns the corpus into something you can ask real questions of: which single set covers every icon this page needs, what breaks if you migrate from mdi to lucide, and which icons in this repo silently resolved through an alias.
Not in the public Printing Press library yet. The library's publish gate counts a command that can only be tested with
--dry-runas unverified, which blocks any command whose job is writing files (here,kit). Tracked upstream in cli-printing-press#4046. Until that lands, use Install from this repository immediately below. The@mvanhorn/printing-press-librarycommands further down will start working once it is merged there.
Installs the iconify and iconify-pp-mcp binaries. Requires Go 1.26.6 or newer.
go install github.com/oliver-mee/iconify-cli/cmd/iconify@latest
go install github.com/oliver-mee/iconify-cli/cmd/iconify-pp-mcp@latestOr build from a clone:
git clone https://github.com/oliver-mee/iconify-cli.git
cd iconify-cli
make build # or: go build ./cmd/iconify-pp-cliThen build the local index once, so the corpus commands work offline:
iconify index # ~40s for all 236 setsSKILL.md in this repository is the agent-facing skill. Install it into any
agent supported by the skills CLI:
npx -y skills@latest add oliver-mee/iconify-cli -g -a claude-codeOr install it by hand for Claude Code, by symlinking this repo's SKILL.md
into a skill directory named for the skill:
mkdir -p ~/.claude/skills/pp-iconify
ln -s "$(pwd)/SKILL.md" ~/.claude/skills/pp-iconify/SKILL.mdThe skill assumes iconify is on PATH; install the binary first.
iconify-pp-mcp mirrors the whole CLI command tree as MCP tools.
claude mcp add --transport stdio --scope user iconify iconify-pp-mcpFor Claude Desktop, a prebuilt .mcpb bundle is produced by make build under
build/; open it to install.
The recommended path installs both the iconify binary and the pp-iconify agent skill (Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, and other agents supported by the upstream skills CLI) in one shot:
npx -y @mvanhorn/printing-press-library install iconifyFor CLI only (no skill):
npx -y @mvanhorn/printing-press-library install iconify --cli-onlyFor skill only — installs the skill into the same agents as the default command above, but skips the CLI binary (use this to update or reinstall just the skill):
npx -y @mvanhorn/printing-press-library install iconify --skill-onlyTo constrain the skill install to one or more specific agents (repeatable — agent names match the skills CLI):
npx -y @mvanhorn/printing-press-library install iconify --agent claude-code
npx -y @mvanhorn/printing-press-library install iconify --agent claude-code --agent codexIf npx isn't available (no Node, offline), install the CLI directly via Go (requires Go 1.26.6 or newer):
go install github.com/mvanhorn/printing-press-library/library/developer-tools/iconify/cmd/iconify-pp-cli@latestThis installs the CLI only — no skill.
Download a pre-built binary for your platform from the latest release. On macOS, clear the Gatekeeper quarantine: xattr -d com.apple.quarantine <binary>. On Unix, mark it executable: chmod +x <binary>.
Install the CLI binary first. The installer writes binaries to a per-user managed bin directory by default: $HOME/.local/bin on macOS/Linux and %LOCALAPPDATA%\Programs\PrintingPress\bin on Windows.
npx -y @mvanhorn/printing-press-library install iconify --cli-onlyThen install the focused Hermes skill.
From the Hermes CLI:
hermes skills install mvanhorn/printing-press-library/cli-skills/pp-iconify --forceInside a Hermes chat session:
/skills install mvanhorn/printing-press-library/cli-skills/pp-iconify --forceRestart the Hermes session or gateway if the newly installed skill is not visible immediately.
Install both the CLI binary and the focused OpenClaw skill. The installer defaults binaries to a per-user bin directory ($HOME/.local/bin on macOS/Linux, %LOCALAPPDATA%\Programs\PrintingPress\bin on Windows):
npx -y @mvanhorn/printing-press-library install iconify --agent openclawRestart the OpenClaw session or gateway if the newly installed skill is not visible immediately.
This CLI ships an MCPB bundle — Claude Desktop's standard format for one-click MCP extension installs (no JSON config required).
To install:
- Download the
.mcpbfor your platform from the latest release. - Double-click the
.mcpbfile. Claude Desktop opens and walks you through the install.
Requires Claude Desktop 1.0.0 or later. Pre-built bundles ship for macOS Apple Silicon (darwin-arm64) and Windows (amd64, arm64); for other platforms, use the manual config below.
Manual JSON config (advanced)
If you can't use the MCPB bundle (older Claude Desktop, unsupported platform), install the MCP binary and configure it manually.
go install github.com/mvanhorn/printing-press-library/library/developer-tools/iconify/cmd/iconify-pp-mcp@latestAdd to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"iconify": {
"command": "iconify-pp-mcp"
}
}
}# confirm the API is reachable; no credentials are needed
iconify doctor --dry-run
# mirror all 236 icon sets locally so search and analysis work offline
iconify index
# find an icon by describing it
iconify icons search --query "arrow right" --prefix lucide
# fetch it as an SVG at your brand colour
iconify icons get lucide arrow-right --color '#404041' --width 32
# pick one set that covers everything a page needs
iconify set-pick rocket shield handshake
These capabilities aren't available in any other tool for this API.
-
index— Mirror icon sets and their icon names into local SQLite for offline search and analysis; --only scopes it to specific sets.Run this once before set-pick, swap, audit, or shadcn; it is what makes them answerable without the network.
iconify index --only lucide
-
set-pick— Given the icon concepts you need, rank icon sets by how many of them each set actually covers.Reach for this before writing any UI that needs several icons, so every icon comes from one set at one stroke weight.
iconify set-pick "rocket" "shield" "handshake" --agent
-
audit— Scan a codebase for Iconify references and report set spread, grid-height mismatches, palette mixing, and dead names.Use this on review to catch icons drifting across sets, or names that silently resolved through an alias.
iconify audit ./src --agent
-
swap— Map a list of icons from one set to another, classifying each as covered, renamed, or missing.Use this when standardising an existing codebase onto one icon set, to see the cost before committing.
iconify swap mdi lucide --icons home,account,cog,rocket --agent
-
shadcn— Turn Iconify icon names into shadcn.io registry slugs and optionally run the install.Use this when the project installs components from shadcn.io and you need the icon as a registry item rather than a raw SVG.
iconify shadcn lucide:home carbon:rocket --agent
-
kit— Render a whole directory of recoloured, uniformly sized SVGs from a manifest of icon names.Use this when a deck, brand kit, or design system needs many icons at one colour and size rather than one ad-hoc icon.
iconify kit icons.yaml --out assets/ --color '#404041' --width 32
-
diff— Show which icons an upstream set added, removed, or aliased since your last sync.Use this before upgrading an icon dependency, to see whether a name you rely on disappeared.
iconify diff --set lucide --agent
iconify icons search --query "arrow that loops back" --limit 32 --agent --select iconsSearch is fuzzy over names and set metadata, so describing the shape works better than guessing the exact name.
iconify kit icons.yaml --out assets/ --color '#404041' --width 32Reads a manifest of icon names and writes one recoloured, uniformly sized SVG per entry, reporting any that were renamed upstream.
iconify set-pick rocket shield handshake clock --agentRanks sets by how many of the listed concepts each covers, with licence and grid height, so you can commit to one set.
iconify swap mdi lucide --icons home,account,cog,rocket --agentClassifies every icon as covered, renamed, or missing so you see the gaps before touching code.
iconify audit ./src --agent --select findings,set_spreadJoins the repo's icon references against the local index to surface set sprawl and names that silently resolved through an alias.
Run iconify --help for the full command reference and flag list.
This CLI separates local files into four path kinds:
| Kind | Contents |
|---|---|
config |
User-editable settings such as config.toml and saved profiles |
data |
Durable local data such as data.db |
state |
Runtime state such as persisted queries, jobs, and teach.log |
cache |
Regenerable HTTP/cache files |
Each kind resolves independently. The ladder is:
- Per-kind env var:
ICONIFY_CONFIG_DIR,ICONIFY_DATA_DIR,ICONIFY_STATE_DIR, orICONIFY_CACHE_DIR --home <dir>for this invocationICONIFY_HOMEfor a flat relocated root- XDG env vars:
XDG_CONFIG_HOME,XDG_DATA_HOME,XDG_STATE_HOME,XDG_CACHE_HOME - Platform defaults matching existing installs
For containers and agent sandboxes, prefer a single relocated root:
export ICONIFY_HOME=/srv/iconify
iconify doctorUnder ICONIFY_HOME=/srv/iconify, the four dirs resolve to /srv/iconify/config, /srv/iconify/data, /srv/iconify/state, and /srv/iconify/cache.
MCP servers do not receive CLI flags from the host. Put relocation in the host env block:
{
"mcpServers": {
"iconify": {
"command": "iconify-pp-mcp",
"env": {
"ICONIFY_HOME": "/srv/iconify"
}
}
}
}Precedence matters in fleets: an ambient per-kind variable such as ICONIFY_DATA_DIR overrides an explicit --home for that kind. Use ICONIFY_HOME or the per-kind variables for durable fleet relocation; treat --home as the weaker per-invocation lever.
Relocation is one-way. Unsetting ICONIFY_HOME does not move files back to platform defaults, and doctor cannot find files left under a former root. Move the files manually before unsetting relocation variables.
Existing installs keep working because the platform-default rung matches the legacy layout. Run iconify doctor --fail-on warn to check path warnings in automation.
Search and fetch individual icons
iconify icons css- Generate a CSS mask sprite for a list of icons from one seticonify icons data- Fetch many icons from one set as a single IconifyJSON payloadiconify icons get- Fetch one icon as SVG, optionally recoloured and resizediconify icons search- Search icons by keyword across every icon set
Expand partial keywords into search suggestions
iconify keywords- Suggest search keywords that start with or end with a fragment
API metadata and cache invalidation
iconify meta last-modified- Get the last modification time per icon set, for cache invalidation and incremental synciconify meta version- Report the Iconify API version and serving region
Browse and inspect icon sets
iconify sets get- List every icon name in one set, with categories, aliases, and hidden iconsiconify sets list- List every icon set with its size, author, licence, and category
This CLI caches per-question discovery so repeat queries skip the walk and structurally similar queries get answered via entity substitution. The loop also self-captures: every invocation is journaled locally, and failed-flag corrections plus fresh teaches surface as candidates on the next recall for confirm/reject judgment. Agents call recall before discovery and fire teach & after answering. See the ## Automatic learning section in SKILL.md for the full protocol.
iconify recall <query>- Look up cached resources for a query before running discoveryiconify teach- Record a query -> resource mapping (silent on success, safe to background with&)iconify learnings list- Inspect taught rowsiconify learnings forget <query>- Undo a teachiconify learnings candidates- List auto-captured candidates awaiting confirm/rejecticonify learnings stats- Local loop metrics: recall hit rate, teach-to-reuse, playbook resolution, candidate countsiconify teach-pattern- Install a query/resource template up fronticonify teach-lookup- Add an entity mapping (e.g. country code, team alias) for pattern substitution
Pass --no-learn or set ICONIFY_NO_LEARN=true to disable the loop for deterministic flows.
The local store's schema version stamp is one-way: once this version of iconify opens the database, older binaries refuse it with a version error — upgrade the binary rather than downgrading.
# Human-readable table (default in terminal, JSON when piped)
iconify icons get mock-value mock-value
# JSON for scripting and agents
iconify icons get mock-value mock-value --json
# Filter to specific fields by name
iconify icons get mock-value mock-value --json --select <field>[,<field>...]
# Dry run — show the request without sending
iconify icons get mock-value mock-value --dry-run
# Agent mode — JSON + compact + no prompts in one flag
iconify icons get mock-value mock-value --agentThis CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--jsonoutput to stdout, errors to stderr - Filterable -
--select <field>[,<field>...]returns only fields you need - Previewable -
--dry-runshows the request without sending - Read-only by default - this CLI does not create, update, delete, publish, send, or mutate remote resources
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendlyis set
Exit codes: 0 success, 2 usage error, 3 not found, 5 API error, 7 rate limited, 10 config error.
iconify doctorVerifies configuration and connectivity to the API.
Run iconify doctor to see the resolved config, data, state, and cache directories. The platform-default config path is ~/.config/iconify/config.toml; --home, ICONIFY_HOME, and per-kind env vars can relocate it.
Static request headers can be configured under headers; per-command header overrides take precedence.
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
listcommand to see available items
- search returns far more results than the limit you asked for — The API silently clamps limit below 32. Run 'index' once and the analysis commands resolve locally, where the floor does not apply.
- an icon name comes back under a different name — Iconify resolves names through aliases, so lucide:home serves house. Run 'audit' to list every reference in a repo that resolved this way.
- set-pick, audit, swap, or diff report an empty index — They read the local mirror. Run 'index' first; it takes about 40 seconds for all 236 sets. If only some sets are missing, 'swap' withholds its verdict and names them under 'unindexed' — run 'index --only ' for those rather than trusting a partial answer.
- a set you rely on lost an icon after an upgrade — Run 'diff --set ' to list what upstream added or removed since your last index.
This CLI was built by studying these projects and resources:
- icones — TypeScript (7438 stars)
- iconify-mcp-server — TypeScript (14 stars)
- dioxus-iconify — Rust (11 stars)
- templ-iconify — Go (10 stars)
- pyconify — Python (7 stars)
- iconify-cli — TypeScript (4 stars)
- iconifydl — Go (3 stars)
Generated by CLI Printing Press