CLI

Command-line reference for Snipkap action Schema 6. Windows and macOS share the same commands, validation, and exit codes.

The CLI, URL Scheme, single-instance IPC, and app menus share action Schema 6. Use the CLI for scripts, AI agents, and any automation that needs a result file. Always pass --to when you need a readable result.

# Windows
Snipkap.exe <command>

# macOS (installed)
/Applications/Snipkap.app/Contents/MacOS/Snipkap <command>

Later CLI requests are forwarded to the running instance. Interactive or async actions return “accepted”. Query and OCR files are published as new files and never overwrite an existing path.

Built-in help

Snipkap --help
Snipkap --help-json

Option	Output	Notes
`--help`	UTF-8 text	Print this document and exit. Does not start the tray or UI
`--help-json`	UTF-8 JSON	Help schema, action schema, commands, exit codes, and notes
`help`	GUI window	Opens in-app help. Does not write stdout

--help and --help-json must be used alone. Option names are case-sensitive. Both exit with 0 on success.

Shared rules

Command names and values are case-insensitive; option names must match the spelling below.
Booleans accept on / off, true / false, 1 / 0, enable / disable, enabled / disabled.
<id> is 32 lowercase hex characters. <id|all> can target every pin; copy / save reject all.
<path> must be a local absolute path. Quote it in the shell if it contains spaces. --to must not already exist.
One argument is at most 32767 characters. pin-paths accepts at most 256 paths and 1 MiB combined.
Aliases: pin = pin-clipboard; rectangle = rect; shape = fixed; watermark = personalization.

Async meaning

Exit code 0 for capture and OCR means the request was accepted, not that the file exists yet. Wait for the --to path to appear, then parse it. Do not sleep for a fixed delay.

capture

Snipkap capture [--mode rect|irregular|long|gif|fixed|delay|whiteboard]
                [--irregular pen|freehand] [--horizontal]
                [--sides 3..64] [--width 1..32768 --height 1..32768]
                [--output interactive|clipboard|save|pin|history]
                [--to <path>]

Starts a capture. Defaults: --mode rect, --output interactive.

Option	Type	Required	Notes
`--mode`	enum	no	`rect`, `irregular`, `long`, `gif`, `fixed`, `delay`, `whiteboard`
`--irregular`	enum	freeform only	`pen` or `freehand`
`--horizontal`	flag	no	Horizontal scrolling capture only
`--sides`	`3..64`	fixed shape only	Regular polygon sides
`--width` / `--height`	`1..32768`	fixed shape only	Must be provided together
`--output`	enum	no	`interactive`, `clipboard`, `save`, `pin`, `history`
`--to`	path	when saving	Implies `save`. If `--output` is also set, it must be `save`

gif, delay, and whiteboard accept interactive only. The user chooses the final output after recording, countdown, or whiteboard editing. Scrolling capture and history output require the matching feature to be available, and history output also requires local history to be enabled.

Snipkap capture --mode rect --output clipboard
Snipkap capture --mode irregular --irregular pen --output clipboard
Snipkap capture --mode long --horizontal --output pin
Snipkap capture --mode fixed --sides 6 --width 800 --height 600 --to /absolute/path/capture.png

Free edition watermark

Free edition capture output always composites the built-in official watermark, including CLI, clipboard, files, pins, and history. Pro uses the saved watermark settings.

Create pins

Snipkap pin-clipboard
Snipkap pin-paths <path> [<path> ...]
Snipkap restore-pins

Command	Notes
`pin-clipboard`	Pin the current clipboard. Alias: `pin`
`pin-paths`	Create one pin per local path
`restore-pins`	Restore the last saved click-through pin session

pins

Snipkap pins list [--to <json-path>]
Snipkap pins close <id|all>
Snipkap pins passthrough <id|all> on|off
Snipkap pins rotate <id|all> left|right|180
Snipkap pins mirror <id|all>
Snipkap pins opacity <id|all> <10..100>
Snipkap pins scale <id|all> <10..1000>
Snipkap pins reset <id|all>
Snipkap pins copy <id>
Snipkap pins save <id> --to <image-path>

Subcommand	Notes
`list`	List pins; `--to` writes machine-readable JSON
`close`	Close one pin or all pins
`passthrough`	Enable or disable click-through
`rotate`	`left` / `right` / `180`
`mirror`	Horizontal mirror
`opacity`	Opacity percent `10..100`
`scale`	Scale percent relative to the original size `10..1000`
`reset`	Reset transform and opacity
`copy`	Copy to the clipboard; rejects `all`
`save`	Save to a new file; rejects `all`

history

Snipkap history enable|disable
Snipkap history pause|resume
Snipkap history settings --days <1..365> --max-entries <1..10000>
Snipkap history open
Snipkap history list [--to <json-path>]
Snipkap history latest
Snipkap history pin|copy|delete <id>
Snipkap history save <id> --to <image-path>
Snipkap history clear
Snipkap history dock show|hide|toggle

delete and clear always require user confirmation.

ocr

Snipkap ocr history <id> [--output panel|clipboard|text|json] [--to <path>]
Snipkap ocr path <image-path> [--output panel|clipboard|text|json] [--to <path>]

Default --output panel. text / json require --to; panel / clipboard reject --to.

Successful JSON includes source, full text, and regions. Each region also has line for reading order and separator for leading whitespace on the same line. Failed async recognition returns empty text, empty regions, and error.

Snipkap ocr path /absolute/path/image.png --output json --to /absolute/path/ocr.json

capabilities / status

Snipkap capabilities [--to <json-path>]
Snipkap status [--to <json-path>]

Command	JSON contents
`capabilities`	App version, action schema, platform, `edition`, `watermark`, and available capabilities
`status`	Also permissions, history settings, pin count, history dock, and capture session state

Without --to, only a short desktop notice is shown. Agents should always pass a JSON path. Free edition returns edition=free and watermark.required=true; Pro returns edition=pro and watermark.management=true.

Settings and lifecycle

Snipkap smart-paste on|off
Snipkap launch-at-login on|off
Snipkap settings open <section>
Snipkap preferences
Snipkap entitlement
Snipkap tool scale-ruler|caliper|angle
Snipkap help
Snipkap about
Snipkap quit

settings open sections: general, ocr, capture-hotkey, pin-hotkey, permissions, history, personalization, watermark, translation, about.

Command	Behavior
`settings open permissions`	Windows opens General and explains that no extra grant is needed; macOS opens the in-app permission guide
`settings open watermark`	Alias of the personalization watermark page
`preferences`	Compatibility entry. Windows opens General; macOS opens the capture-hotkey page
`entitlement`	Shows Free / Pro. For a machine-readable result use `capabilities --to` or `status --to`
`tool`	Toggle the desktop scale ruler, caliper, or angle tool

Exit codes

Code	Meaning
`0`	Success or accepted
`1`	Execution failed
`2`	Invalid arguments
`3`	Busy
`4`	File, history item, or pin not found
`5`	Permission denied or user declined
`6`	Unsupported on this platform
`7`	Resource limit exceeded

For browsers and launchers, use the URL Scheme. A URL cannot return these codes to the calling page.

On this page