CLI#

text
screenmat <image|url…> [options] render images — a URL is captured first
screenmat --spec scene.json      full scene, annotations included
screenmat inspect <image>        dimensions and the layer coordinate frame
screenmat styles                 saved styles

From a clone of the repository, use pnpm cli — it is node cli/main.ts:

bash
pnpm cli screenshot.png --frame macbook --ratio 16:9 --scale 3

The package declares bin.screenmat, so a linked or installed copy answers to screenmat directly. Both forms are the same file.

Called with no image and no --spec, the CLI prints its help and exits 0.

Options#

Only the flags you actually pass are applied. An absent flag lets the style — or the default — speak; it is never overwritten with undefined.

FlagValueDefaultNotes
-o, --outpath<image>-screenmat.<format>Exact output file.
--out-dirdirectorycurrent directoryWhere generated names land.
--specpath—A scene file. Flags override its settings.
--stylename or path—A saved style, applied underneath the flags.
--scale1 2 32Export scale. Anything else falls back to 2.
--formatpng webpwebpFalls back to PNG where the WebP encoder is missing.
--framebrowser macbook iphone nonenone
--backgroundmesh gradient solid, a dithered pattern such as halftone or atkinson, or a macOS or Windows wallpaper such as tahoe-dark or windows-11-darkmeshimage needs a scene file. Full lists: --help, or the scene reference.
--ratioauto 4:3 1:1 16:9 9:164:3
--themeauto light darkautoFrame chrome, not the background.
--urltextexample.comAddress bar text, frame=browser only. Truncated at 200 characters.
--padding0 to 0.30.065Fraction of the canvas width.
--radius0 to 0.080.018Window corner radius, same unit.
--seedinteger1Same seed, same background, exactly.
--shadow0 to 21Multiplier on the artwork's own shadow.
--grain0 to 10.35Film grain over the background.
--rotate-y−24 to 240Degrees of window tilt.
--no-title-barflagtitle bar shownRemoves the window chrome bar.
--device-ratioflagoffframe=macbook or iphone: the screen keeps the device ratio (16:10, 19.5:9) and crops the screenshot.
--screen-ratioauto 16:10 16:9 4:3 1:1autoframe=browser or none: ratio of the screen. Anything but auto crops the screenshot.
--island-sideleft rightleftframe=iphone with a landscape screenshot: the short edge that carries the island.
--panx,y, each 0 to 10.5,0.5Which part of a cropped screenshot shows: 0 start, 1 end.
--jsonflaghuman lineMachine-readable result on stdout.
-h, --helpflag—

Out-of-range numbers are clamped, not rejected: --padding 5 renders at 0.3. An unknown value for an enumerated flag falls back to the default. What does fail: an unknown flag (rejected by parseArgs), a --style name that does not exist, and a --screen-ratio, --island-side or --pan value outside what the table lists — see Errors.

Five settings have no flag, because they are background-tuning dials that a command line rarely needs: blur, shapes, shapeOpacity, saturation and contrast. They live in a scene file or a style.

Rendering images#

bash
# One image, defaults.
pnpm cli screenshot.png

# Several, into a folder, with a saved style underneath.
pnpm cli shots/*.png --style docs --out-dir ./build/visuals

# A device frame, tilted, at export scale 3.
pnpm cli app.png --frame iphone --rotate-y -12 --scale 3 --format png

Each positional image is rendered in turn and written on its own. --out names a single file, so pass one image with it; with several images, use --out-dir.

Without either, the file is written to the current directory under <basename>-screenmat.<format> — the input's folder is not reused.

Capturing a URL#

A positional argument that starts with http:// or https:// is opened in a headless browser, captured, then rendered like any image.

bash
# The page as it loads, framed in a browser window.
pnpm cli https://example.com --frame browser

# Your dev server, full height, in dark mode, once the app has mounted.
pnpm cli http://localhost:5173 --full-page --color-scheme dark --wait '#app'

The browser runs on your machine: the installed Google Chrome first, otherwise a Chromium managed by Playwright. Capture needs playwright-core, an optional dependency; with neither browser present, install one with pnpm exec playwright-core install chromium.

FlagValueDefaultNotes
--viewport<width>x<height>1440x900CSS pixels. Width 320–3840, height 240–2160.
--density1–32deviceScaleFactor: 2 keeps the capture sharp at export scale 3.
--full-pageflagoffThe whole page height, not only the viewport.
--color-schemelight, darklightWhat the page reads in prefers-color-scheme. Not the window --theme.
--waitselector or ms—A CSS selector to wait for, or a delay in milliseconds (≤ 30000).

Unlike the render flags, capture values out of range are rejected, not clamped: a capture at the wrong size only shows once the file is open.

The address bar shows the captured host and path (example.com/pricing) unless --url says otherwise, and the default output name follows the URL: example-com-pricing-screenmat.webp. Navigation and waiting each time out after 30 seconds. A full page is cut so the capture stays under 100 million pixels. Chrome runs with its sandbox on; on Linux that needs unprivileged user namespaces (Ubuntu 24.04: sysctl kernel.apparmor_restrict_unprivileged_userns=0). localhost and private addresses are allowed — capturing your own dev server is the first use case. Only http: and https: are accepted.

Rendering a scene#

A scene file carries what flags cannot: layers, composition, watermark, frozen palette, background image. Flags still apply on top of the file's settings, which makes one scene reusable at several scales.

bash
pnpm cli --spec scene.json --scale 3 --out hero@3x.webp

Without --out or --out-dir, the output name is derived from the first shot's input. The full format is documented in Scene format.

inspect#

Prints where the screenshot lands inside its window — the frame you need before computing any layer position. See Coordinates.

bash
pnpm cli inspect screenshot.png --frame browser --json
json
{
  "imageWidth": 2880,
  "imageHeight": 1800,
  "screen": { "x": 0, "y": 0.035, "w": 1, "h": 0.625 },
  "source": { "x": 0, "y": 0, "w": 2880, "h": 1800 },
  "titleBar": 0.035,
  "canvas": { "width": 1600, "height": 1200 },
  "input": "screenshot.png"
}

The geometry flags apply here too: --frame, --ratio, --padding, --radius, --rotate-y, --no-title-bar, --device-ratio, --screen-ratio and --pan all move the screenshot inside its window, so pass the same ones you will pass to the render.

styles#

Lists what is in the styles directory, and where that directory is.

bash
pnpm cli styles --json
json
{
  "directory": "/Users/you/.screenmat/styles",
  "styles": [
    { "name": "docs", "label": "Docs", "frame": "macbook", "background": "mesh", "ratio": "16:9", "format": "webp" }
  ]
}

name is what --style takes. See Styles.

Output#

A render prints one line per file:

text
screenshot-screenmat.webp  3200×2400  188464 octets

With --json, the same render prints an object — this is the form to parse:

FieldMeaning
outputPath actually written.
width, heightFinal pixel size, scale included.
bytesFile size.
formatThe real format — png if the WebP encoder was missing.
settingsThe complete resolved settings, defaults and style merged in.

inspect and styles print JSON either way: --json makes it a single line, without it the same object is pretty-printed.

Errors#

Messages go to stderr and the process exits with code 1. Everything on stdout is either the report or the JSON, so a pipeline can read stdout safely.

MessageCause
inspect attend le chemin d'une imageinspect called with no path.
Impossible de lire <path> : …File missing or unreadable.
Impossible de décoder <path> : …Not an image, or an unsupported codec.
Style « x » introuvable dans <dir> — disponibles : …Unknown --style. The available names are listed for you.
--screen-ratio attend … — reçu « x »--screen-ratio outside the listed ratios.
--island-side attend left ou right — reçu « x »--island-side is neither left nor right.
--pan attend deux nombres…--pan is not x,y.
--full-page ne s'applique qu'à une URL http(s)A capture flag was passed with no URL among the arguments.
--viewport attend <largeur>x<hauteur>…--viewport is not 1440x900-shaped.
width attend un entier entre 320 et 3840 — reçu « x »A capture option out of range — the field is named.
Impossible de capturer <url> : …Navigation failed, timed out, or a --wait selector never appeared.
… playwright-core n'est pas installé…The optional dependency is missing.
… aucun navigateur trouvé…Neither Chrome nor Playwright's Chromium is installed.
Scène illisible : ce n'est pas du JSON--spec file is not valid JSON.
Une scène a besoin d'au moins un shot…No entry in shots had a usable input.

Unlike the MCP server, the CLI writes wherever you point it and overwrites an existing file. That is the contract of a command-line tool; the guard rails are on the MCP side, where a remote model picks the path.