🖼️ macshot

CLI tool to decorate screenshots with macOS window frames.

Install

npm install -g macshot

Local Development

Clone the repo and install dependencies:

git clone <your-fork-or-this-repo-url>
cd macshot
npm install

Build the CLI from src/ into dist/:

npm run build

Run the built CLI locally with the sample image:

npm run start -- test-input.png
node dist/cli.js test-input.png --theme sonoma --title "Local Preview"

If you want to test the macshot command directly during development, link the package globally:

npm run dev:link
macshot test-input.png --shadow

Generate preview images for every built-in theme:

npm run preview:themes

This writes one PNG per theme to theme-previews/.

Usage

Basic

macshot screenshot.png

With Options

# Choose a background theme
macshot screenshot.png --theme sonoma

# Add window title
macshot screenshot.png --title "My App"

# Dark mode
macshot screenshot.png --dark

# Custom padding, corner radius, and shadow
macshot screenshot.png --padding 80 --radius 12 --shadow

# Specify output path
macshot screenshot.png -o output.png

Batch Conversion

macshot batch screenshot-1.png screenshot-2.png --theme ocean --out-dir ~/Downloads/macShot

Batch mode writes each file as <original-name>-macshot.png into the target directory.

AI Background (requires OpenAI API key)

# Use DALL-E to generate a unique background
macshot screenshot.png --ai

# With a custom prompt
macshot screenshot.png --ai --prompt "ocean sunset at golden hour"

Set your API key in ~/.macshot.json:

{
  "openaiApiKey": "sk-..."
}

Or use the OPENAI_API_KEY environment variable.

Themes

Theme	Description
sonoma	macOS Sonoma — vivid pink to coral-orange gradient
ventura	macOS Ventura — aqua green to deep teal gradient
monterey	macOS Monterey — soft mauve to lavender gradient
sequoia	macOS Sequoia — bright blue to indigo gradient
sunset	Warm sunset — peach to bright pink gradient
ocean	Deep ocean — moody navy gradient

List all themes:

macshot --list-themes

Configuration

Create ~/.macshot.json to set defaults:

{
  "theme": "sonoma",
  "padding": 80,
  "radius": 10,
  "dark": false,
  "shadow": true,
  "openaiApiKey": "sk-..."
}

CLI flags always override config file values.

Options

Flag	Default	Description
-o, --output <path>	<input>-macshot.png	Output file path
-t, --theme <name>	sonoma	Background theme
--title <text>	—	Window title bar text
--dark	false	Dark mode window frame
--padding <px>	80	Padding around window
--radius <px>	10	Window corner radius
--shadow	false	Add drop shadow
--ai	false	Use DALL-E for background
--prompt <text>	"abstract gradient background"	AI background prompt
--list-themes	—	List available themes

Batch-only:

Flag	Default	Description
--out-dir <path>	./macshot-output	Output directory for macshot batch

License

MIT