How do I install the Iconic CLI skill?

Run npx skillmds@latest add mergesort/iconic-cli in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Iconic CLI safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Iconic CLI?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Iconic CLI free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Iconic CLI?

mergesort (@mergesort) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Iconic CLI by mergesort — Agent Skill

Name: Iconic CLI
Author: mergesort

File contents

iconic-cli

iconic turns a visual input into semantic keywords suitable for search, tagging, or metadata.

When to use

Use iconic when you need keywords for:

an SF Symbol name like folder.fill
an emoji like 🍋
a local image file like ./icon.png

Install

If the CLI is not installed yet:

brew tap mergesort/iconic
brew install iconic

Authentication

Use either a flag or an environment variable.

OpenAI models

Models: gpt-5, gpt-5-mini, gpt-5-nano
Environment variable: OPENAI_API_KEY

Anthropic models

Models: haiku, sonnet, opus
Environment variable: ANTHROPIC_API_KEY

Examples:

export OPENAI_API_KEY="..."
iconic folder.fill

export ANTHROPIC_API_KEY="..."
iconic "🍋" --model sonnet

Best invocation patterns for agents

Prefer JSON output and quiet mode when another tool will parse the result:

iconic ./icon.png --output-format json --quiet
iconic folder.fill --output-format json --quiet
iconic "🍋" --model gpt-5-nano --output-format json --quiet

Use list output for human-readable terminal output:

iconic ./icon.png

Output formats

list: numbered list, one keyword per line
text: comma-separated string
json: JSON object with a keywords array

Examples

SF Symbol

iconic folder.fill --output-format json --quiet

Emoji

iconic "🚀" --model sonnet --output-format text --quiet

Image file

iconic ./assets/logo.png --model gpt-5 --output-format json --quiet

Important behavior

Results are written to stdout.
Progress logs are written to stderr unless --quiet is passed.
Supported image inputs: png, jpg, gif, webp.
If the input is not an image path or emoji, iconic treats it as an SF Symbol name.

Common failures

Missing API key

The CLI will fail with a message like:

Missing API key. Pass --api-key or set OPENAI_API_KEY ...

Fix by setting the correct provider key or passing --api-key.

Invalid symbol

If the SF Symbol cannot be rendered, the CLI will fail with:

Unable to render SF Symbol. Check the symbol name and availability.

Fix by verifying the symbol exists on the current macOS version.

Invalid image type

If the file is not png, jpg, gif, or webp, the CLI will fail with:

Invalid image format. Please provide a png, jpg, gif, or webp file.

Self-check

Before using the tool, you can inspect the built-in help:

iconic --help

---name: iconic-clidescription: Use the iconic CLI to generate semantic keyword metadata from SF Symbols, emoji, and image files. Trigger when a task needs searchable keywords, icon metadata, or automated tagging for visual assets.---# iconic-cli`iconic` turns a visual input into semantic keywords suitable for search, tagging, or metadata.## When to useUse `iconic` when you need keywords for:- an SF Symbol name like `folder.fill`- an emoji like `🍋`- a local image file like `./icon.png`## InstallIf the CLI is not installed yet:```bashbrew tap mergesort/iconicbrew install iconic```## AuthenticationUse either a flag or an environment variable.### OpenAI models- Models: `gpt-5`, `gpt-5-mini`, `gpt-5-nano`- Environment variable: `OPENAI_API_KEY`### Anthropic models- Models: `haiku`, `sonnet`, `opus`- Environment variable: `ANTHROPIC_API_KEY`Examples:```bashexport OPENAI_API_KEY="..."iconic folder.fillexport ANTHROPIC_API_KEY="..."iconic "🍋" --model sonnet```## Best invocation patterns for agentsPrefer JSON output and quiet mode when another tool will parse the result:```bashiconic ./icon.png --output-format json --quieticonic folder.fill --output-format json --quieticonic "🍋" --model gpt-5-nano --output-format json --quiet```Use list output for human-readable terminal output:```bashiconic ./icon.png```## Output formats- `list`: numbered list, one keyword per line- `text`: comma-separated string- `json`: JSON object with a `keywords` array## Examples### SF Symbol```bashiconic folder.fill --output-format json --quiet```### Emoji```bashiconic "🚀" --model sonnet --output-format text --quiet```### Image file```bashiconic ./assets/logo.png --model gpt-5 --output-format json --quiet```## Important behavior- Results are written to **stdout**.- Progress logs are written to **stderr** unless `--quiet` is passed.- Supported image inputs: `png`, `jpg`, `gif`, `webp`.- If the input is not an image path or emoji, `iconic` treats it as an SF Symbol name.## Common failures### Missing API keyThe CLI will fail with a message like:```textMissing API key. Pass --api-key or set OPENAI_API_KEY ...```Fix by setting the correct provider key or passing `--api-key`.### Invalid symbolIf the SF Symbol cannot be rendered, the CLI will fail with:```textUnable to render SF Symbol. Check the symbol name and availability.```Fix by verifying the symbol exists on the current macOS version.### Invalid image typeIf the file is not `png`, `jpg`, `gif`, or `webp`, the CLI will fail with:```textInvalid image format. Please provide a png, jpg, gif, or webp file.```## Self-checkBefore using the tool, you can inspect the built-in help:```bashiconic --help```

Frequently asked questions

Iconic CLI