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"]
}

Free plan quota (server-authoritative)

The Free plan includes a monthly screenshot allowance (20 by default). The quota is enforced entirely by the license API — there is no local counter file anymore, so it can't be reset by deleting a file or running from a different folder.

On its first launch the CLI registers this machine automatically and stores a Free license locally — no login or account required. Registration uses a deterministic machine ID (a SHA256 hash of stable, non-privileged system facts: hostname, platform, architecture, CPU model, and CPU count). It never touches MAC addresses and never needs administrator permissions.

Before each generation, the CLI asks the API to consume quota. When the monthly limit is reached you'll see:

❌ You have reached this month's free limit.
   Upgrade to SyntaxShot Pro to continue.

The quota resets automatically at the start of each calendar month. Check your current usage any time:

syntaxshot account

Plan: free
Remaining screenshots: 12
Monthly limit: 15

If the API can't be reached, the CLI shows a friendly message and leaves your local configuration untouched.

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
}

Note: plan is not a valid config option. Your plan is determined by your license (via the API), not by this file. If a plan key is present it's ignored and the CLI warns you — use syntaxshot login <key> for Pro or syntaxshot logout to go back to Free.

Available themes

Free (3):

• midnight — Dracula-style palette, dark violet window (the one in the reference image)
• nord — Nord palette, blue-gray window
• paper — GitHub Light palette, crisp white 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
• solar — Solarized Light, light 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 — machine ID, first-launch registration, Free-quota consume, Pro validation, account, and local caching
• bin/syntaxshot.js — CLI, plan limits, --auto, confirmation prompt, login/logout/account

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

syntaxshot-cli