macOS CLI for managing custom icons for files and folders
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin
doc
man
test
.gitignore
.npmignore
CHANGELOG.md
LICENSE.md
Makefile
README.md
TODO.md
package-lock.json
package.json

README.md

npm version license

Contents

fileicon — introduction

fileicon is a macOS CLI for managing custom icons for files and folders, as a programmatic alternative to interactively using Finder.

fileicon allows assigning a custom icon to any file or folder, using any image file whose format is recognized by the system.

Caveat: Custom icons rely on extended attributes of the macOS filesystems, HFS+ and APFS. Therefore, custom icons are lost when copying files or folders to filesystems that don't support these attributes; for instance, custom icons cannot be stored in a Git repository.

When assigning an image file with fileicon set, a set of icons in several resolutions is created and stored in the resource fork of the target file itself / of a hidden Icon\r file inside the target folder.

The icon with the highest resolution measures 512 x 512 pixels, and the input image is scaled accordingly.
Note that input images that aren't square can result in distorted icons; for best results, provide square images.

Examples

# Assign custom icon derived from image file 'img.png' to file 'foo':
fileicon set foo img.png

# Remove previously assigned custom icon from folder 'foodir':
fileicon rm foodir

# Extract custom icon from file 'foo' to icon file 'foo.icns':
fileicon get foo

# Test if folder 'foodir' has custom icon:
fileicon test foodir

Installation

Supported platforms

  • macOS

Installation from the npm registry

With Node.js or io.js installed, install the package as follows:

[sudo] npm install fileicon -g

Note:

  • Whether you need sudo depends on how you installed Node.js / io.js and whether you've changed permissions later; if you get an EACCES error, try again with sudo.
  • The -g ensures global installation and is needed to put fileicon in your system's $PATH.

Manual installation

  • Download the CLI as fileicon.
  • Make it executable with chmod +x fileicon.
  • Move it or symlink it to a folder in your $PATH, such as /usr/local/bin (requires sudo).

Usage

Find concise usage information below; for complete documentation, read the manual online, or, once installed, run man fileicon (fileicon --man if installed manually).

$ fileicon --help


Manage custom icons for files and folders on macOS.  

SET a custom icon for a file or folder:

    fileicon set      <fileOrFolder> [<imageFile>]

REMOVE a custom icon from a file or folder:

    fileicon rm       <fileOrFolder>

GET a file or folder's custom icon:

    fileicon get [-f] <fileOrFolder> [<iconOutputFile>]

    -f ... force replacement of existing output file

TEST if a file or folder has a custom icon:

    fileicon test     <fileOrFolder>

All forms: option -q silences status output.

Standard options: --help, --man, --version, --home

License

Copyright (c) 2015-2018 Michael Klement mklement0@gmail.com (http://same2u.net), released under the MIT license.

Acknowledgements

This project gratefully depends on the following open-source components, according to the terms of their respective licenses.

npm dependencies below have optional suffixes denoting the type of dependency; the absence of a suffix denotes a required run-time dependency: (D) denotes a development-time-only dependency, (O) an optional dependency, and (P) a peer dependency.

npm dependencies

Changelog

Versioning complies with semantic versioning (semver).

  • v0.2.2 (2018-03-05):

    • [enhancement] filecon set <file> is now short for filecon set <file> <file>; that is, you can now more conveniently make an image file use itself as its icon.
  • v0.2.1 (2018-01-13):

    • [doc] Read-me improvements re supported image formats.
    • [enhancement] Improved wording of error message on attempting to use a pipe such as via a process subsitution (<(...)) in lieu of an actual image file, which is not supported.
  • v0.2.0 (2017-10-14):

    • [compatibility] macOS 10.13 (High Sierra) is now supported.
    • [enhancement] Switched from using sips -i for icon creation to a Python-based Cocoa call to NSWorkSpace.setIcon(_:forFile:options:), courtesy of https://apple.stackexchange.com/a/161984/28668 As a result, icons in multiple resolutions are now generated, with a top resolution of 512 x 512 pixels (previously: 128 x 128)
    • [doc] More technical background added to README.md.
    • [usability] subcommands are now case-insensitive, and 'remove' is supported as an alias of 'rm'.
  • v0.1.8 (2016-04-21):

    • [dev] Refactored exit-code reporting for the 'get' command (no change in functionality.)
    • [dev] TODO.md added.
  • v0.1.7 (2016-04-21):

    • [fix] Stored-npm-credentials detection code in the Makefile updated for newer npm versions.
    • [fix] Folder write test is now properly skipped for 'get' and 'test' commands - thanks, @zmwangx.
    • [fix] 'get' command now properly reports errors if icon extracton fails - thanks, @zmwangx.
    • [dev] Insignificant trailing whitespace removed - thanks, @zmwangx.
    • [dev] Added folder used by tests that was missing from the repo.
  • v0.1.6 (2015-09-16):

    • [doc] Man-page improvements.
    • [dev] Makefile improvements.
  • v0.1.5 (2015-09-15):

    • [doc] Man-page improvements.
    • [dev] Makefile improvements.
  • v0.1.4 (2015-09-14):

    • [fix] Spurious error message no longer prints when invoking fileicon --man on a system where the man page isn't installed.
    • [doc] Read-me improvements.
  • v0.1.3 (2015-09-02):

    • [dev, doc] minor tweaks
  • v0.1.2 (2015-08-04):

    • [doc] Read-me and manual enhancements.
  • v0.1.1 (2015-08-03):

    • [doc] Read-me and manual enhancements.
    • [dev] Permission-related tests added.
  • v0.1.0 (2015-08-03):

    • Initial release.