icon-composer-cli

Create and edit Apple .icon bundles for iOS 26+ Liquid Glass app icons — from the terminal or from Cursor.

This CLI builds the bundle (layers, fills, glass settings) and uses Apple's Icon Composer on your Mac (ictool) for real Liquid Glass previews. Not affiliated with Apple.

Install

npm install -g icon-composer-cli
icon-composer doctor

Requirements

• Node.js 18+
• macOS with Icon Composer for Liquid Glass rendering (brew install --cask icon-composer)
• Bundle create/edit and flat export also work on Linux and Windows without Icon Composer

Quick start

Point the tool at a logo and pick a background color:

icon-composer create ./logo.png ./icons --bg-color "#1a1a2e"
icon-composer render ./icons/AppIcon.icon preview.png
open preview.png

Not sure where to begin? Scan your project:

cd ~/Developer/MyApp
icon-composer context

context detects logos, existing .icon bundles, and Xcode projects, then suggests next commands.

Use with Cursor (no CLI memorization)

Install the bundled agent skills once:

icon-composer install-skills

Then open your app project in Cursor and ask naturally:

• "Make a Liquid Glass app icon from Assets/logo.png with a navy background."
• "Polish the existing .icon bundle and preview dark mode."
• "Export the App Store 1024 marketing PNG."

The agent runs icon-composer doctor, icon-composer context --json, and the right commands for you. See AGENTS.md for how skills are routed.

Commands

Command	Purpose
create	New .icon bundle from PNG/SVG
inspect	Show bundle manifest and assets
glass / fill / appearance / position	Tune Liquid Glass and layout
add-layer / remove	Multi-layer icons
preview / render	Export PNG (flat or Liquid Glass)
export-marketing	Flat 1024×1024 for App Store Connect
doctor	Check Node + Icon Composer
context	Scan project and recommend workflow
install-skills	Install Cursor / Claude / Codex skills

Full flags: icon-composer <command> --help

Example: logo → Xcode

icon-composer create logo.svg ./out --bg-color "#0A66C2"
icon-composer appearance ./out/AppIcon.icon --target fill --appearance dark --bg-color "#0D1B2A"
icon-composer render ./out/AppIcon.icon glass.png
icon-composer export-marketing ./out/AppIcon.icon marketing.png

Drop AppIcon.icon into your asset catalog in Xcode.

How it works

1. You provide a glyph (PNG or SVG).
2. The CLI writes an .icon bundle (icon.json + assets).
3. On macOS, ictool renders Apple's Liquid Glass (specular, shadow, depth).
4. You preview, export, or wire into Xcode.

Flat rendering works everywhere; Liquid Glass requires macOS + Icon Composer.

Develop from source

git clone https://github.com/Eyadkelleh/icon-composer-cli.git
cd icon-composer-cli
bun install
bun test
bun run build
npm link
icon-composer doctor

License

MIT — see LICENSE.