syntaxshot-cli

Generate real syntax-highlighted code screenshots from the terminal — no browser involved, using shiki (highlighting) + @napi-rs/canvas (rendering).

Installation

cd syntaxshot
npm install
npm link        # this enables the global `syntaxshot` command

That's it. @napi-rs/canvas ships prebuilt binaries for Windows, macOS, and Linux, so you don't need to install Cairo, GTK, Visual Studio Build Tools, or any native dependency (unlike the classic canvas package, which is a lot of pain on Windows).

Basic usage (Free plan)

syntaxshot init                          # creates .syntaxshotrc.json with your defaults
syntaxshot path/to/file.js               # generates syntaxshots/file.png
syntaxshot a.js b.ts c.css --theme nord  # multiple files, one theme
syntaxshot a.py --format jpg -o outputs  # jpg, custom folder

The Free plan always requires you to name each file. The Pro plan can do all of the above, plus:

syntaxshot ./src                       # [Pro plan] scans the whole folder

When you pass it a folder, syntaxshot:

1. Walks it recursively.
2. Filters "capturable" files (recognized code extension) and automatically ignores what doesn't make sense to show: node_modules, .git, dist/build, lockfiles (package-lock.json, yarn.lock...), package.json, tsconfig.json, any .env*, and dotfiles in general.
3. Tells you how many files it found and how many images it's about to generate, then asks for confirmation before generating anything.
4. Once confirmed, generates everything automatically, keeping the subfolder structure inside the output folder (so files with the same name in different folders don't overwrite each other).

Pass -y / --yes to skip the confirmation prompt (handy for scripts/CI).

If you're on the Free plan and try to pass a folder, the CLI blocks it with a clear message asking you to list files one by one — it doesn't disable normal usage, it just redirects you to the manual flow.

You can customize what the scan ignores in .syntaxshotrc.json:

{
  "excludeDirs": ["scripts", "tmp"],
  "excludeFiles": ["seed-data.json"]
}

The Free plan allows 10 images; the counter lives in .syntaxshot-usage.json in the folder where you run the command.

Activating a Pro license

Once you've paid (see the syntaxshot-api project), you'll get a license key by email. Activate it once per machine:

syntaxshot login SYNX-XXXX-XXXX-XXXX

This validates the key against the license API and caches the result in ~/.syntaxshot/license.json (re-checked automatically every 24h; if the API is briefly unreachable, a previously-valid license keeps working for up to 7 days so you're never blocked by a network hiccup).

syntaxshot logout   # removes the license from this machine

Configuration (.syntaxshotrc.json)

{
  "theme": "midnight",
  "format": "png",
  "output": "syntaxshots",
  "fontSize": 16,
  "lineNumbers": true,
  "quality": 0.95
}

Available themes

Free (3):

• midnight — Dracula-style palette, dark violet window (the one in the reference image)
• nord — Nord palette, blue-gray window
• solar — Solarized Light, light window

Pro (5):

• tokyonight — Tokyo Night palette, deep navy window with cyan/pink accents
• onedark — One Dark Pro palette, the iconic Atom One Dark look
• mocha — Catppuccin Mocha palette, soft pastel-on-dark
• paper — GitHub Light palette, crisp white window
• owl — Night Owl palette, deep blue with high-contrast text

Themes on the Free plan are fixed at those 3. Any theme added later defaults to Pro unless explicitly marked tier: "free" in src/themes.js — the free set doesn't silently grow as new themes ship.

Quick list with tier shown: syntaxshot themes

Key files if you want to extend this

• src/themes.js — add new themes here (syntax palette + window colors)
• src/highlighter.js — extension → language map for shiki
• src/scanner.js — folder-scan logic and exclusion rules (Pro)
• src/renderer.js — all the canvas drawing (background, window, text)
• src/license.js — license activation/validation + local caching
• bin/syntaxshot.js — CLI, plan limits, --auto, confirmation prompt, login/logout

The license backend itself (Stripe webhook, /api/v1/validate, license key generation) lives in the separate syntaxshot-api project.

syntaxshot-cli