The command line tools

OpticScript is an engine first and an interface second. To use it from a Makefile, a CI pipeline or a shell script you need no window — just six programs that all carry the same engine and require no runtime.

No Python install, no Node, no pip install. Each binary brings everything with it: the engine, the format libraries, the fonts.

On Windows they are mlcos-run.exe and so on; on macOS they live inside the app bundle under Contents/MacOS/, and in the DMG also in the CLI folder.

mlcos-run

Runs a script. The flags come from the script itself — every //!INPUT:, //!OUTPUT: and //!PARAM: becomes an option.

mlcos-run thumbnail.js --SRC=photo.jpg --OUT=small.webp --WIDTH=400

That is the difference from a conventional image tool: you invent the interface in the script, and the command line follows it. A script with three inputs gets three flags, and nobody writes an argument parser.

Extensions are discovered automatically — project-local in ./.mlcos-extensions/, user-wide in ~/.mlcos/extensions/, plus the bundled ones. --no-extensions turns that off.

mlcos-compile

Turns the script into a binary that stands on its own.

mlcos-compile thumbnail.js          # → bin/thumbnail

The recipient installs nothing. No runtime, no Docker image, no dependency list — one file to copy and run. Its flags are again the script's directives, and it carries its own --help.

Covered in detail in From script to executable.

mlcos-analyze

The one tool here that hands back numbers rather than an image.

mlcos-analyze stats photo.jpg        # brightness, contrast, sharpness, clipping
mlcos-analyze compare a.png b.png    # MSE, PSNR, how far apart?
mlcos-analyze hash *.jpg             # find duplicates
mlcos-analyze exif photo.jpg         # camera, lens, capture time
mlcos-analyze histogram photo.jpg    # per-channel distribution

--json on every subcommand, for when a script consumes the answer.

What it is for: checking whether a render changed (compare against a stored reference), weeding out soft scans (stats gives the Laplacian variance, the same measure cameras focus by), finding duplicates in a folder (hash survives rescaling and re-encoding), or seeing whether an image still carries the provenance your pipeline stamped into it.

$ mlcos-analyze compare render.png reference.png
  MSE            0.00000012
  PSNR           69.21 dB  (indistinguishable in practice)
  max difference 1.0 of 255
  differing      613 pixels  (0.0061 %)
  hash distance  0 bits   (the same picture)

Images of different sizes are compared by perceptual hash alone — MSE between differently sized images is undefined, and printing a number anyway would be worse than printing none.

mlcos-server

The same engine behind HTTP.

mlcos-server -port 8080 -token secret

POST /process/js takes the script and the images as multipart and returns the result. In server mode file access is off: inputs arrive as image_<KEY> fields, and nothing is read from or written to disk.

mlcos-ext

Manages extensions (JavaScript, running inside the engine) and tool plugins (separate programs the engine calls).

mlcos-ext list                                   # what is installed
mlcos-ext install-from <catalog-url> --list      # what is available
mlcos-ext install-from <catalog-url> rmbg        # fetch one

The catalogue delivers per platform: a Windows machine does not download Linux binaries, and anything that cannot run here is refused before the transfer rather than after. Every file is verified against its SHA-256 checksum before it counts as installed.

mlcos-mcp

The Model Context Protocol server: the engine as a tool for AI agents. It has its own page: MCP server.

mlcos-license

Enters a licence without the desktop app — for servers set up over SSH. It is the same activation as in the app: checked online once, valid offline afterwards.

mlcos-license activate <KEY> --name "First Last"
mlcos-license status            # what applies, until when, what is unlocked
mlcos-license status --json
mlcos-license remove

The licence applies to the account that runs the command. On a server, run it as the account the service runs under, then restart the service. A server for others on the network is unlocked by an Enterprise licence, see Team server.

Used together

The tools are cut so they complement each other in a shell pipeline. A regression test for an image pipeline needs no further software:

#!/usr/bin/env bash
set -e
mlcos-run pipeline.js --SRC=input.png --OUT=/tmp/new.png

# Does the result differ from the stored reference?
psnr=$(mlcos-analyze compare /tmp/new.png reference.png --json | jq .psnr)
if [ "$(echo "$psnr < 50" | bc)" = 1 ]; then
  echo "output changed: $psnr dB"
  exit 1
fi

Or a folder of scans with the soft ones falling out:

for f in scans/*.jpg; do
  s=$(mlcos-analyze stats "$f" --json | jq .sharpness)
  awk -v s="$s" 'BEGIN { exit (s < 0.0001) ? 0 : 1 }' && echo "too soft: $f"
done

See also

• Getting started — installation and a tour of the engine
• From script to executable — mlcos-compile in detail
• MCP server — for AI agents
• API reference — every Engine.* method