ImageOptim-CLI: batch image optimisation for macOS builds

What ImageOptim-CLI is for, and who should care

ImageOptim, ImageAlpha and JPEGmini are macOS applications with graphical interfaces. ImageOptim-CLI exists to drive them from a shell so that compressing a directory of images stops being a manual step. The README states the goal plainly: "Automates ImageOptim, ImageAlpha, and JPEGmini for Mac to make batch optimisation of images part of your automated build process."

The audience is narrow and specific. You need macOS, because package.json declares "os": ["darwin"] and the README says macOS only. You need at least one of the three apps installed separately. If your build runs on Linux containers, this tool does not apply to you at all, regardless of how convenient the command line looks. The value is for front-end teams on Macs who want image compression to run before assets are committed or deployed, and who would otherwise open an app and drag files in by hand.

How the tool drives three separate macOS apps

The mechanism is unusual and worth understanding before you install anything. ImageOptim-CLI is a Rust binary, described in the README as "a Rust rewrite of the original TypeScript + AppleScript implementation, distributed on npm as platform-specific binaries". It does not implement PNG or JPEG compression itself. It shells out to the installed applications.

That design explains the flags. ImageOptim is enabled by default, and -I, --no-imageoptim turns it off. ImageAlpha and JPEGmini are opt-in through -a, --imagealpha and -j, --jpegmini. The ImageAlpha-specific options expose that app's own settings: --quality takes a range from 0-100 with a default of 65-80, --speed runs from 1 (brute-force) to 10 (fastest) with a default of 1, and --number-of-colors sets a palette size from 2-256 with a default of 256.

JPEGmini is the awkward one. The README states it "has no API or command line interface, so this tool automates its GUI". That means the process running the CLI, typically your terminal, needs permission to control the computer under System Settings, Privacy & Security, Accessibility. This is not a configuration detail you can skip; without it, the JPEGmini path cannot work. The repository layout confirms the approach: Cargo.toml includes "src/**/*.applescript" in the published package, so AppleScript files ship inside the binary's source set.

Installing ImageOptim-CLI and running a first optimisation

The README gives one installation command, a global npm install. Node 18 or newer is required according to the engines field in package.json.

npm install --global imageoptim-cli

After that, the binary is called imageoptim. Running it with no arguments optimises every image in the current directory, which is the example the README leads with. Before letting it write anything, use --dry-run, which the help text describes as listing images that would be optimised without optimising them.

imageoptim --dry-run

Once the file list looks right, target a specific format. The README gives this example for PNGs, which enables ImageAlpha alongside ImageOptim:

imageoptim --imagealpha '**/*.png'

For JPEGs, the equivalent example enables JPEGmini. Note that the README shows passing both extensions as separate patterns:

imageoptim --jpegmini '**/*.jpg' '**/*.jpeg'

To run JPEGmini alone, without ImageOptim afterwards, combine --jpegmini with --no-imageoptim. The README's example is `imageoptim --jpegmini --no-imageoptim '**/*.jpg' '**/*.jpeg'`. You can also point it at a directory rather than a glob, as in `imageoptim '~/Desktop'`.

For build scripts, --json emits newline-delimited JSON instead of human-readable text, and -S, --no-stats suppresses the file size savings and quality loss summary. --batch-size controls how many images are processed at a time and defaults to 3000.

The macOS-only constraint and the JPEGmini dependency

Two limitations decide whether this tool fits your project.

The first is the platform. There is no Windows or Linux build. The package.json os field is darwin only, and the README repeats it. Any CI runner that is not a Mac cannot use this. That excludes most default hosted runners, and it means the tool cannot be part of a pipeline that also builds on Linux unless you split the image step into a separate macOS job.

The second is licensing and permission for JPEGmini. The README lists JPEGmini, JPEGmini Lite and JPEGmini Pro as paid, while ImageOptim and ImageAlpha are free. The GUI automation requirement adds an operational constraint: an unattended build agent needs Accessibility permission granted to whatever process invokes the CLI. That is a system-level setting on the machine, not something the tool can configure for you. If you cannot grant it, the --jpegmini flag is not usable in that environment, and you are left with the two free apps.

The README does not document rollback or how to restore an original image after optimisation. If overwriting matters to your workflow, that is a gap to test on copies before trusting it on a working tree.

How it differs from squoosh-cli and sharp-based pipelines

The obvious alternative is a tool that performs compression itself rather than orchestrating apps. sharp, or a CLI built on it such as squoosh-cli, encodes images in-process using libraries like libvips. That approach runs anywhere Node runs, including Linux containers, and needs no GUI, no Accessibility permission and no paid app.

The trade-off runs the other way too. Because ImageOptim-CLI delegates to ImageOptim and ImageAlpha, it inherits whatever encoders those apps bundle, and the README's topics list names a long set: advpng, gifsicle, jpegtran, jpegoptim, optipng, pngcrush, pngout, pngquant. A single tool that bundles all of those is a different proposition from picking one encoder and configuring it. The cost is that you can only get that coverage on a Mac with the apps installed.

A third option is doing nothing in the build and using an image CDN that optimises on delivery. That removes the build step entirely but moves the work to request time and to a third party. ImageOptim-CLI is for teams that want the bytes smaller in the repository, not at the edge.

Release cadence, maintenance and the MIT licence

Version 4.0.0 was released on 2026-08-02, with a 4.0.0-alpha.1 on 2026-07-25. The previous stable release, 3.1.9, dates from 2023-11-06, so the 4.x line was a substantial gap after the 3.x series. The repository's last push was on 2026-08-02, the same day as the 4.0.0 release, and the repository is not archived. That is recent enough to treat the project as still being worked on, though the three-year gap between 3.1.9 and 4.0.0 is worth knowing if you are planning to depend on it for years.

The licence is MIT, declared in both Cargo.toml and package.json. That covers the CLI itself. It does not cover the applications it drives: ImageOptim and ImageAlpha are free downloads, JPEGmini is paid, and their terms are separate from this project's. Installing the CLI does not grant you any right to those apps.

Upgrade cost is mostly the npm install plus whatever changed in the app interfaces. The justfile shows the project keeps Cargo.toml and package.json versions in lockstep with a check-versions recipe, and the release process bumps both together. For consumers, that means the npm version and the Rust crate version track each other.

Editorial conclusion

Adopt ImageOptim-CLI if your build runs on macOS and you already have ImageOptim installed, and if the JPEGmini step can be treated as optional because it needs Accessibility permission and a paid licence. Do not adopt it for Linux CI, for HEIC or other formats the three apps do not handle, or as a replacement for an image CDN. Verify first that the three apps are installed where the tool expects them, that your terminal has Accessibility permission if you enable JPEGmini, and that a run with --dry-run lists the files you meant to optimise before you let it write to them.

Frequently asked questions

Official sources

1. JamieMason/ImageOptim-CLI on GitHub
2. License: MIT
3. Project website
4. README
5. Releases