iconic-cli

# 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: ```bash 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: ```bash 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: ```bash 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: ```bash 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 ```bash iconic folder.fill --output-format json --quiet ``` ### Emoji ```bash iconic "🚀" --model sonnet --output-format text --quiet ``` ### Image file ```bash 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: ```text 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: ```text 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: ```text 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: ```bash iconic --help ```