Home

Awesome

npm version license

<!-- START doctoc generated TOC please keep comment here to allow auto update --> <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

Contents

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

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.

Caveats:

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 / as the content of a hidden .VolumeIcon.icns file for folders that are volume mountpoints. Addtionally, a com.apple.FinderInfo extended attribute with the custom-icon attribute (flag) is set on the target file or folder itself.

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.

If you supply an input path to a symlink, it is invariably its target that is used for the operation; symlinks themselves cannot have icons associated with them.

See also: Icon Changer, a GUI utility that uses fileicon behind the scenes.

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:

Important:

Installation via Homebrew

With Homebrew installed, run the following:

brew install fileicon

<sup>Tip of the hat to @danielbayley for creating and submitting the formula.</sup>

Installation from the npm registry

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

[sudo] npm install fileicon -g

Note:

Manual installation

Usage

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

<!-- DO NOT EDIT THE FENCED CODE BLOCK and RETAIN THIS COMMENT: The fenced code block below is updated by `make update-readme/release` with CLI usage information. --> 
$ 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
<!-- DO NOT EDIT THE NEXT CHAPTER and RETAIN THIS COMMENT: The next chapter is updated by `make update-readme/release` with the contents of 'LICENSE.md'. ALSO, LEAVE AT LEAST 1 BLANK LINE AFTER THIS COMMENT. -->

License

Copyright (c) 2015-2022 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.

<!-- DO NOT EDIT THE NEXT CHAPTER and RETAIN THIS COMMENT: The next chapter is updated by `make update-readme/release` with the dependencies from 'package.json'. ALSO, LEAVE AT LEAST 1 BLANK LINE AFTER THIS COMMENT. -->

npm dependencies

<!-- DO NOT EDIT THE NEXT CHAPTER and RETAIN THIS COMMENT: The next chapter is updated by `make update-readme/release` with the contents of 'CHANGELOG.md'. ALSO, LEAVE AT LEAST 1 BLANK LINE AFTER THIS COMMENT. -->

Changelog

Versioning complies with semantic versioning (semver).

<!-- NOTE: An entry template for a new version is automatically added each time `make version` is called. Fill in changes afterwards. -->