# Iconic CLI

> 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.

- Skill: `mergesort/iconic-cli` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mergesort/iconic-cli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mergesort/iconic-cli/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: mergesort (https://skillmd.com/u/mergesort)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mergesort/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
```