beautify-screenshot

Screenshots that look finished. beautify-screenshot puts a screenshot on a gradient background with padding, rounded corners and a soft shadow, and sizes the canvas for LinkedIn, X, Open Graph or any ratio you name. It is the background half of Xnapper, as a CLI, built for AI agents (and humans).

Nine gradient presets, each in a light and a dark variant that follow your macOS appearance. Ships an agent skill so an agent can take "make this screenshot pretty and LinkedIn-sized" from the raw file to Preview.

Written in TypeScript on Bun, with no runtime dependencies: the PNG codec and the compositor (OKLab gradients, mesh blobs, analytic anti-aliased corners, gaussian shadow) are a few hundred lines of typed-array code.

What it's for

Post a screenshot without opening a design tool

beautify-screenshot ~/screenshots/latest.png --ratio linkedin --width 1200 --open

The canvas grows to 1.91:1 around the untouched screenshot, the result is downscaled to 1200 px wide, and Preview opens it.

Let an agent do it

Tell your agent "frame the latest screenshot for X, dark mode, show me all the presets". With the skill installed it runs --all --open, you point at the one you like, and it renders the final file.

Match your own brand

beautify-screenshot shot.png --colors "#0f172a,#1e3a8a" --angle 35 --radius 16

Any comma-separated list of hex colours becomes a linear gradient.

For arrows, text, blur and redaction, a screenshot editor is still the better tool. This one only does backgrounds.

For AI agents

beautify-screenshot is designed for agent use: every result is available as --json, the input is never modified, and the only side effects (--open, --copy) are opt-in flags. The repo ships an agent skill under skills/ that teaches an agent the workflow and every flag:

npx skills add magnusrodseth/beautify-screenshot

See AGENTS.md for the operating rules.

Install

Prebuilt binary (macOS and Linux, no runtime required). Installs to ~/.local/bin:

curl -fsSL https://raw.githubusercontent.com/magnusrodseth/beautify-screenshot/main/install.sh | bash

Pin a version with BEAUTIFY_SCREENSHOT_VERSION=v0.1.0, or change the location with BEAUTIFY_SCREENSHOT_INSTALL_DIR. Make sure the install dir is on your PATH, then run beautify-screenshot --help.

With Bun 1.3.14 or newer already installed:

npm i -g beautify-screenshot     # or: bunx beautify-screenshot <image>

The npm package runs on Bun only (it uses Bun.Image for JPEG/WebP/HEIC input and clipboard reads).

Usage

# Defaults: aurora preset, mode follows macOS, 100pt padding, 12pt radius, 30pt shadow
beautify-screenshot shot.png                      # writes shot-aurora-dark.png next to it
beautify-screenshot shot.png --open               # and opens it in Preview
beautify-screenshot --clipboard --copy            # pasteboard in, pasteboard out

# Looks
beautify-screenshot shot.png --preset sky --mode light
beautify-screenshot shot.png --all --open         # every preset, opened together
beautify-screenshot shot.png --inset 20           # border in the screenshot's own edge colour
beautify-screenshot shot.png --colors "#a8edea,#fed6e3" --angle 50

# Sizes
beautify-screenshot shot.png --ratio linkedin --width 1200
beautify-screenshot shot.png --ratio 4:5
beautify-screenshot shot.png --ratio og --out preview.jpg

# Machine-readable
beautify-screenshot shot.png --json
beautify-screenshot --list

--padding, --inset, --radius and --shadow are in points and are multiplied by the PNG's dpi (2 on Retina captures), so the defaults look the same at 1x and 2x. --scale overrides the factor.

--ratio never crops: it grows the canvas on one axis, centred, and fills the new space with more gradient. --width only ever downscales.

--inset reads the most common colour along the screenshot's edge and paints a border in it inside the rounded card. It is off by default because region captures usually already include the app's own margin; tight crops of a single block look better with it on.

Presets

Each preset has a light and a dark variant; --mode auto picks by the macOS appearance.

| | Light | Dark | |---|---|---| | aurora | | | | sky | | | | sunset | | | | ocean | | | | lavender | | | | forest | | | | candy | | | | slate | | | | mono | | |

Named ratios

| --ratio | Ratio | Recommended --width | |---|---|---| | linkedin, og, facebook | 1.91:1 | 1200 | | linkedin-square, instagram | 1:1 | 1080 | | linkedin-portrait, instagram-portrait | 4:5 | 1080 | | linkedin-banner | 4:1 | 1584 | | twitter, x | 16:9 | 1600 | | youtube | 16:9 | 1280 | | story | 9:16 | 1080 |

Anything else works as W:H (16:9, 1.91:1, 1200x627).

Development

bun install
bun run check        # biome + tsc + bun test
bun src/cli.ts <image> --open
bun run build        # dist/beautify-screenshot, a self-contained binary
bun run docs:images  # regenerate docs/hero.png and docs/presets/ from docs/sample.png

Releasing

Bump version in package.json, commit as Release vX.Y.Z: <headline>, then tag vX.Y.Z and push the tag. CI builds binaries for macOS and Linux (arm64 and x86_64), attaches them to the GitHub Release, and publishes to npm through trusted publishing, so no token lives in the repo.