sscc

sscc ships with the ScreenShotComposer macOS app. The Mac app installs the binary at/usr/local/bin/sscc on first launch (you can disable this in Settings → Advanced).

If you cloned the repo to build from source:

git clone https://github.com/luigiinred/ScreenShotComposer.git
cd ScreenShotComposer
bin/sscc --help

Confirm the API version your scripts target — sscc bumps it on every breaking change to the JSON envelope:

sscc --api-version

• Address by UUID, never by title. Every command that mutates a composition or layer takes --id <uuid>. Capture UUIDs at create-time with --emit-id.
• Add --json for machine-readable output. Every command returns a stable envelope — { "ok": true, "data": ... } on success, { "ok": false, "error": { "code", "message" } } on failure.
• Mutations are atomic. Either the bundle is updated cleanly or it is untouched on disk. No partial writes.
• Frames are X,Y,W,H in plate points, top-left origin. Negative origins are valid (for edge bleeds); use the = form so swift-argument-parser doesn’t mistake a leading - for a flag boundary: --frame=-200,300,800,1200.
• Text accepts \n only. Pass it literally inside double-quoted bash strings; the CLI converts it at parse time. <br/> renders as the literal characters.
• Image sizing is frame-only. There is no --scale flag. To grow an image, pass a bigger frame.

Enumerate live catalogs — templates, bezels, presets, fonts.

These four catalogs are the source of truth for any id your scripts pass elsewhere. Always cross-check before freehand-typing a bezel id, font name, or preset token.

# Pick the iPhone 17 Pro bezel from the live catalog.
sscc catalog bezels --platform iphone --json | jq -r '.data[].id' | head

Emit JSON Schema for the document nodes. Use these to validate generated payloads, build editors, or teach an agent the field grammar.

Create a new .screenshot document.

sscc new <path>
  [--template <id>]              # bundled template id (sscc catalog templates)
  [--platforms mac,iphone,ipad]  # default: all three
  [--overwrite]
  [--emit-id]                    # print only the absolute created path
  [--json]

Each requested platform gets a <platform>.json with an empty compositions: [].

Summarize what’s in a bundle.

sscc info <path> [--json]

The JSON variant is the right way to assert composition counts in a scaffold script.

sscc info MyApp.screenshot --json | jq '.data.compositions | map_values(length)'
# { "mac": 6, "iphone": 6, "ipad": 6 }

Print the full bundle (or one composition or one layer) as JSON.

sscc show <path>
  [--composition <uuid>]   # limit to that composition
  [--layer <uuid>]         # limit to that layer
  [--json]

Validate a bundle against the documented schema.

sscc validate <path> [--strict] [--json]

--strict promotes warnings to errors. Run this after every batch of edits.

Note: validate proves the file is well-formed JSON; it does not prove the bundle will render correctly. For that, see the create-screenshot-file skill’s pre-render verify gate.

Manage compositions inside a bundle.

Heads up: composition add auto-creates one empty backgroundlayer per composition. Don’t add another via layer add background — see Known quirks.

Manage layers (text, image, background, group) inside a composition.

Manage embedded image assets inside a bundle.

Render PNGs for every composition (or a filtered subset).

sscc export <path> --output <dir>
  [--platform mac|iphone|ipad]   # restrict to one bucket
  [--composition <uuid>]         # repeatable
  [--format png]                 # default & only option today
  [--opaque]                     # alpha-stripped RGB PNG (ASC-friendly)
  [--at-preset <token>]          # render-time preset override
  [--naming preset|uuid|title-slug]
  [--overwrite]
  [--json]

--at-preset is a render-time override; the document on disk keeps its original presets, so the same source can produce every ASC slot:

# Largest required sizes for every platform.
sscc export MyApp.screenshot --output ship/largest \
  --opaque --naming title-slug --json > ship/largest/manifest.json

# Plus an additional iPhone 6.5" slot.
sscc export MyApp.screenshot --output ship/iphone-6.5 \
  --platform iphone --at-preset 1284x2778 --opaque

Heads up: --opaque currently paints a gray transparency-checkerboard into plain (non-bezel) image layers that have alpha. Drop --opaque when your bundle has stickers, badges, or other transparent decorations. See Known quirks.

Every command exits 0 on success and a non-zero code on a known error class:

• 0— ok
• 2— usage error (bad / missing flag)
• 3— not found (path, composition, layer, asset)
• 4— validation error
• 5— render error
• 10— internal error

On success, --json emits:

{
  "ok": true,
  "apiVersion": 1,
  "data": { /* command-specific payload */ },
  "warnings": [
    { "code": "FONT_FALLBACK", "message": "..." }
  ]
}

On failure:

{
  "ok": false,
  "apiVersion": 1,
  "error": { "code": "NOT_FOUND", "message": "Layer ABC… not found" }
}

Parse the envelope, never the human text. Codes are stable across minor versions.

sscc is shipping in phases. These behaviours bite agents and humans equally — if you write a scaffold script, read this list once first.