Command Reference

Overview

iconchanger <command> [options]

Commands

status

Show current configuration status.

iconchanger status

Displays:

• Number of app aliases configured
• Number of cached icons
• Helper script status

---

list

List all aliases and cached icons.

iconchanger list

Shows a table of all configured aliases and all cached icon entries.

---

set-icon

Set a custom icon for an application.

iconchanger set-icon <app-path> <image-path>

Arguments:

• app-path — Path to the application (e.g., /Applications/Safari.app)
• image-path — Path to the icon image (PNG, JPEG, ICNS, etc.)

Examples:

# Set a custom Safari icon
iconchanger set-icon /Applications/Safari.app ~/icons/safari.png

# Relative paths work too
iconchanger set-icon /Applications/Slack.app ./slack-icon.icns

---

remove-icon

Remove a custom icon and restore the original.

iconchanger remove-icon <app-path>

Example:

iconchanger remove-icon /Applications/Safari.app

---

restore

Restore all cached custom icons. Useful after a system update or when apps reset their icons.

iconchanger restore [options]

Options:

• --dry-run — Preview what would be restored without making changes
• --verbose — Show detailed output for each icon
• --force — Restore even if the icon appears unchanged

Examples:

# Restore all cached icons
iconchanger restore

# Preview what would happen
iconchanger restore --dry-run --verbose

# Force restore everything
iconchanger restore --force

---

export

Export aliases and cached icon configuration to a JSON file.

iconchanger export <output-path>

Example:

iconchanger export ~/Desktop/my-icons.json

---

import

Import a configuration file.

iconchanger import <input-path>

Import only adds new items — it never replaces or removes existing entries.

Example:

iconchanger import ~/Desktop/my-icons.json

---

validate

Validate a configuration file before importing.

iconchanger validate <file-path>

Checks JSON structure, required fields, and data integrity without making changes.

Example:

iconchanger validate ~/Desktop/my-icons.json

---

escape-jail

Escape macOS Tahoe's squircle jail by re-applying bundled icons as custom icons. Custom icons bypass squircle enforcement, preserving the original icon shape.

iconchanger escape-jail [app-path] [options]

Arguments:

• app-path — (Optional) Path to a specific .app bundle. If omitted, processes all apps in /Applications.

Options:

• --dry-run — Preview what would be done without making changes
• --verbose — Show detailed output

Examples:

# Escape jail for all apps in /Applications
iconchanger escape-jail

# Preview what would happen
iconchanger escape-jail --dry-run --verbose

# Escape jail for a specific app
iconchanger escape-jail /Applications/Safari.app

WARNING

Custom icons do not support macOS Tahoe's Clear, Tinted, or Dark icon modes. They remain as static bitmaps.

---

completions

Generate shell completion scripts for tab completion.

iconchanger completions <shell>

Arguments:

• shell — Shell type: zsh, bash, or fish

Examples:

# Zsh (add to ~/.zshrc)
source <(iconchanger completions zsh)

# Bash (add to ~/.bashrc)
source <(iconchanger completions bash)

# Fish
iconchanger completions fish > ~/.config/fish/completions/iconchanger.fish