bolens/appicon

appicon

Resolve desktop and brand icons to local file paths for Waybar, Rofi, scripts, and other consumers that need an icon file.

Website · Documentation · Releases

appicon resolve firefox
appicon resolve --json --format png --size 24 "VS Code"
appicon resolve --json firefox discord
appicon resolve --offline some-cached-app
appicon resolve --explain missing-app
appicon prefetch firefox discord
appicon prefetch --from-desktop
appicon prefetch --json --offline firefox
appicon override set my-browser firefox
appicon override suggest my-browser
appicon override list
appicon sources get --json

appicon status appicon cache stats appicon cache prune appicon mcp # stdio MCP for agents appicon daemon # optional user socket daemon appicon completion bash # print completion script appicon man | man -l - # view man page

**Default resolve order:** file → overrides → XDG / `.desktop` → [SVGL](https://svgl.app/). Change the order with `sources.json`, `sources.yaml`, or `--order`. Optional stages include `simple-icons`, `dashboard-icons`, `github`, BYOK (`logo-dev`, `iconify`, `noun-project`), `glyph`, and local packs. See [docs/sources.md](docs/sources.md) and [docs/packs.md](docs/packs.md).

XDG, SVGL (cache-first), local packs, opt-in CDN/github/BYOK/glyph stages, PNG rasterization, `--offline`, `cache prune`, MCP, optional unix-socket daemon (not on Windows), and shell completions are implemented. Deferred ideas: [docs/deferred.md](docs/deferred.md).

**Consumer contract:** exit `0` for a hit, `1` for a miss, and `2` for an error. `resolve --json` has stable fields for a single object or a `{results:[…]}` batch. See [docs/consumer-contract.md](docs/consumer-contract.md) and the [single](docs/resolve-result.schema.json) and [batch](docs/resolve-batch-result.schema.json) schemas. Callers should keep their fallback glyph after a miss. Keep appicon optional so a missing binary cannot break a bar.

**Portability:** Primary target is Linux (XDG, Flatpak/Snap roots, systemd daemon). The local `xdg` stage also discovers macOS `.app` bundle icons from XML `Info.plist` metadata and Windows `.url` shortcuts with an absolute `IconFile`; binary plist, Windows `.lnk`, and embedded EXE icon extraction are not supported. Config/cache fall back to OS user dirs when `XDG_*` are unset. Daemon refuses on Windows (`daemon_supported=false` in `status`).

**PNG note:** `resolve --format png` prefers `resvg` or `rsvg-convert` on `PATH`, otherwise a pure-Go [oksvg](https://github.com/srwiley/oksvg) fallback. Rasterized files are cached under `$XDG_CACHE_HOME/appicon/raster/`. Pixel size defaults to `48` and is capped at **512** (`--size` / MCP `size` values above that are clamped).

**Theme note:** `--theme dark|light`, `APPICON_THEME`, or `GTK_THEME` suffix (`Adwaita:dark`) prefer matching SVGL/CDN and XDG variants (`name-dark` / `name-symbolic` / `name-light`). Icon **theme name** is separate (`APPICON_ICON_THEME`).

Sources: $XDGCONFIGHOME/appicon/sources.json (or .yaml) — every stage is an ordered entry. Default without a file is file → overrides → xdg → svgl. Opt-in remotes are never enabled by default. BYOK stages take tokenenv / secretenv (env var names whose values hold secrets — never put keys or secret paths in config).

appicon sources list
appicon sources get --json
appicon pack install simple-icons   # local clone + register
appicon pack install --name mine --subdir icons https://github.com/org/my-icons.git
appicon resolve --order glyph,svgl,xdg my-app
appicon resolve --order logo-dev,xdg shopify.com   # needs LOGO_DEV_TOKEN
appicon status

Example — remaps and a personal pack before path/XDG/SVGL:

{
  "sources": [
    { "type": "overrides" },
    { "type": "pack", "name": "mine", "path": "~/.local/share/appicon/packs/mine" },
    { "type": "file" },
    { "type": "xdg" },
    { "type": "svgl" },
    { "type": "simple-icons" }
  ]
}

Local pack paths must be absolute or start with ~/; working-directory-relative and named-user paths are rejected.

CDN stages (simple-icons / dashboard-icons) are separate from local pack install clones of the same upstreams. Do not point http-index at third-party CDNs unless you control the allowlist and accept their terms.

Overrides

Long-tail query remaps live in $XDGCONFIGHOME/appicon/overrides.json (or .yaml):

appicon override set my-wm-class firefox
appicon override list --json
appicon override export --format yaml > overrides.yaml
appicon override import --merge --file overrides.yaml

MCP (agents)

Run the same binary as a stdio MCP server — tools call internal/resolve (no extra download logic):

appicon mcp