photopea-cli

Edit images from the terminal using Photopea, driven by playwright-cli.

photopea-cli boots a real Photopea instance inside a headless browser, feeds it your image through the Photopea live-messaging API, runs edits with the Photoshop-compatible scripting interface (app.activeDocument...), and writes the exported result back to disk. It supports every format Photopea can read (PSD, AI, XD, Sketch, PDF, RAW, PNG, JPG, SVG, ...) and export (PNG, JPG, WEBP, GIF, PSD, PDF, SVG, ...).

Requirements

• Node.js 20+

• playwright-cli installed globally and on PATH:

  npm install -g playwright-cli

• an internet connection (photopea.com is loaded live)

Install

npm install -g photopea-cli

Usage

photopea-cli convert <input> [output] [options]
photopea-cli edit <input> [output] [options]
photopea-cli run <input> <output> --script "js code" | --script-file file.js
photopea-cli info <input>
photopea-cli layers <input>
photopea-cli probe
photopea-cli close

Options

| flag | description | | --- | --- | | -o, --out <path> | output path (- writes bytes to stdout) | | -q, --quality <0..1> | jpg / webp quality | | -f, --format <fmt> | output format: png jpg webp gif psd pdf svg bmp tiff ico | | --resize <WxH> | resize image; either side may be empty (800x, x600) to keep aspect | | --canvas <WxH> | resize canvas without scaling content | | --rotate <deg> | rotate canvas | | --flip <h\|v> | flip canvas horizontally / vertically | | --crop <x,y,w,h> | crop to a rectangle | | --invert | invert colors of the active layer | | --grayscale | convert document to grayscale | | --script <js> | custom Photopea script (with run) | | --script-file <path> | file containing a custom Photopea script (with run) | | --timeout <ms> | per-step timeout (default 120000) | | --keep | keep the browser session alive after finishing | | --quiet | suppress progress logs |

Input - reads the image from stdin.

Examples

Convert a PSD to PNG:

photopea-cli convert design.psd design.png

Resize and recompress:

photopea-cli edit cat.jpg small.jpg --resize 400x --quality 0.8

Rotate, flip and grayscale:

photopea-cli edit cat.jpg out.png --rotate 90 --flip h --grayscale

Inspect a document:

photopea-cli info design.psd
photopea-cli layers design.psd

Run an arbitrary Photopea script — the full Photoshop-style document model is available via app:

photopea-cli run cat.jpg out.png --script "
  d.resizeCanvas('600px', '600px');
  app.echoToOE('layers: ' + d.layers.length);
"

In custom scripts, app is the Photopea application object and d is pre-bound to app.activeDocument. Use app.echoToOE(str) to log strings back to the CLI (they appear as script: ... progress lines), and app.activeDocument.saveToOE(format) is called for you afterwards using the requested output format.

Note: Photopea's script engine aborts on any uncaught JavaScript exception, which the CLI reports as a timeout. Keep scripts exception-free: guard unset properties and avoid throw.

Draw programmatically (the full Photoshop-style DOM is available):

photopea-cli run cat.jpg painted.png --script "
  d.selection.select([[40,40],[240,40],[240,240],[40,240]]);
  var c = new SolidColor();
  c.rgb.red = 255; c.rgb.green = 0; c.rgb.blue = 0;
  d.selection.fill(c);
  d.selection.deselect();
  var t = d.artLayers.add();
  t.kind = LayerKind.TEXT;
  t.textItem.contents = 'hello';
  t.textItem.size = 60;
"

Pipe through:

cat cat.jpg | photopea-cli convert - - --format webp > cat.webp

Sessions

Every run uses the shared headless browser session photopea-cli (via playwright-cli -s photopea-cli) and gets a freshly reloaded Photopea, so runs are hermetic and never affected by previous documents. By default the browser is closed when the run finishes; pass --keep to leave it running and save the browser boot time (~2s) on subsequent commands (Photopea itself is still reloaded per run). To shut everything down:

photopea-cli close

How it works

1. A local throwaway HTTP server (bound to 127.0.0.1, random port) serves a minimal bridge page that embeds photopea.com in an iframe.
2. The image is base64-chunked into the page through playwright-cli eval, rebuilt as an ArrayBuffer and delivered to Photopea via postMessage (no CORS issues, no file uploads).
3. Edit operations are compiled into a Photoshop-compatible script and executed inside Photopea.
4. The document is exported with Document.saveToOE(format); the resulting ArrayBuffer is read back out in chunks and written to disk.

Because it uses a real Photopea, anything it can do is a one-line --script away: layer manipulation, text edits, filters, batch conversion between exotic formats, and more.

License

MIT