iconic-cli

name	iconic-cli
description	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 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