Command line

Everything the agent tools do is also available as a command. Run commands from the iconwright folder:

node bin/iconwright.mjs <command> [options]

node bin/iconwright.mjs help lists the commands, and <command> --help shows one command's options. Unknown options are errors, so a typo never runs silently.

Sources are an Iconify id (mdi:music), an image file (.svg, .png, .jpg, .webp, .ico), raw <svg> text, or (on Windows) app:<App name> for an installed app's current icon.

Styles are given as one string, --style "color=white bg=#2d5ba6 shape=squircle shadow", or as separate flags: --color, --bg, --shape, --radius, --padding, --shadow. Separate flags win over the same key in --style. See style strings.

Design (any OS)#

Command	What it does
`search <query>`	Prints matching Iconify ids. `--limit N`, `--start N` (next page), `--collections mdi,ph`, `--palette mono\|color`, `--sheet out.png` (also saves a numbered contact sheet).
`design <source...> --out grid.png`	Renders a comparison grid: sources in rows, styles in columns. `--styles "style one\|style two"`. Prints the legend.
`preview <source> --out scenes.png`	Mocks the icon up on real surfaces. `--style`, `--label "App name"`, `--scenes taskbar,start,desktop,explorer,browser,dock,ios,android,sizes`, `--scale 1\|1.5\|2`.
`make <source>`	Writes icon files. `--formats ico,png,icns,web,pngset` (default `ico,png`), `--name`, `--out folder`, `--png-size N`, plus style options.
`studio [source]`	Opens the studio in your browser. `--style`, `--port N`, `--no-open`. Runs until you press Ctrl+C.
`sheet <images...> --out sheet.png`	Puts image files (PNG or ICO) side by side with their names.

Examples:

node bin/iconwright.mjs search rocket --palette mono --sheet rockets.png
node bin/iconwright.mjs design ph:rocket-launch-fill tabler:rocket --styles "color=white bg=#2d5ba6 shape=squircle|color=#e9c46a bg=#1f2228 shape=circle" --out grid.png
node bin/iconwright.mjs preview ph:rocket-launch-fill --style "color=white bg=#2d5ba6 shape=squircle" --label Launcher --out scenes.png
node bin/iconwright.mjs make ph:rocket-launch-fill --style "color=white bg=#2d5ba6 shape=squircle" --formats ico,icns,web --name launcher

Apps and taskbar (Windows)#

Command	What it does
`apps [text]`	Finds installed apps by name. Prints exact names and AppIDs.
`info <app...>`	Shows an app's AppID, Start menu shortcuts, pinned shortcuts and whether it's a Store app.
`apply <app...> --source <ref>`	Makes an icon and puts it on the apps. `--source app` restyles each app's own icon. `--pin` also pins them; `--refresh` restarts Explorer at the end if needed. Or `apply <app> --icon file.ico` to use an existing icon.
`status`	Lists pinned apps in order with their icon files.
`pins`	Pins, unpins and reorders in one Explorer restart: `--pin a,b`, `--unpin c`, `--order a,b`, `--position N` (0 = first, -1 = last), `--dry-run`, `--no-restart`, `--restart-cooldown N`.
`refresh`	Restarts Explorer so pinned icons reload.
`restore <app...>`	Puts the original icons back. `restore --all` restores every app and desktop icon iconwright changed.
`restore-pins`	Puts the pinned-apps list back. `--from last` (default) or `--from original`.

pin, unpin and reorder still work as shortcuts for pins.

node bin/iconwright.mjs apply Spotify Steam Discord --source app --style "color=white"
node bin/iconwright.mjs pins --pin Notepad --order Notepad --position 0 --dry-run
node bin/iconwright.mjs restore --all

Desktop (Windows)#

Command	What it does
`desktop list`	Icons with positions, icon size, options, grid spacing and monitors.
`desktop move <item> --x px --y px`	Moves one icon (snaps to the grid).
`desktop arrange [items first...]`	Lines icons up. `--by name\|type\|none`, `--corner top-left\|top-right\|bottom-left\|bottom-right`, `--flow columns\|rows`, `--monitor N`.
`desktop size <size>`	`small`, `medium`, `large`, `xl`, `huge`, or pixels from 16 to 256.
`desktop options`	`--auto-arrange on\|off`, `--snap on\|off`, `--icons on\|off`.
`desktop system <names...> --show\|--hide`	`this-pc`, `recycle-bin`, `user-files`, `network`, `control-panel`.
`desktop apply <item>`	Changes a desktop item's icon: `--source <ref>` plus style options, or `--icon file.ico`.
`desktop restore <item...>`	Puts original icons back.
`desktop save <file.json>` / `desktop load <file.json>`	Saves or restores icon positions, size and auto-arrange.

Checks (Windows)#

Command	What it does
`doctor`	Checks that the taskbar and desktop tools can work on this PC. Changes nothing.
`capture [taskbar\|desktop\|screen]`	Saves a screenshot. `--out file.png`, `--max-width px`. Doesn't work while the screen is locked.

Testing (any OS)#

Command	What it does
`report`	Prints your system details and a quick self-test as Markdown, for test reports. Names no apps, files or user folders. `--out report.md` saves it.
`mcp`	Starts the MCP server on stdio (the same as `bin/iconwright-mcp.mjs`).

Output and exit codes#

Commands print plain text or compact JSON. Windows paths use forward slashes, and every command accepts them back. On failure, a command prints a one-line error and exits with code 1.