CLI Reference

Synopsis

cropbox [MEDIA]
cropbox [MEDIA] --trim-in VALUE --trim-out VALUE --crop X Y WIDTH HEIGHT
cropbox [MEDIA] --current-time VALUE
cropbox [MEDIA] --current-frame FRAME
cropbox MEDIA --out PATH [--force] [--trim-in VALUE] [--trim-out VALUE] [--crop X Y WIDTH HEIGHT]
cropbox --version

Arguments

MEDIA

Optional media path to open when launching the desktop UI.

When any of the following options are used, MEDIA becomes required:

• --out
• --trim-in
• --trim-out
• --crop
• --current-time
• --current-frame

Options

-o, --out PATH

Export directly to MP4, MOV, GIF, or PNG without opening the UI.

-f, --force

Overwrite an existing output file. This option is only valid with --out.

--trim-in VALUE

Initial trim-in time in seconds or HH:MM:SS.mmm format.

--trim-out VALUE

Initial trim-out time in seconds or HH:MM:SS.mmm format.

If omitted during headless export, Cropbox exports through the end of the timed media.

--crop X Y WIDTH HEIGHT

Initial crop rectangle in source pixels.

WIDTH and HEIGHT must be positive integers. X and Y must be zero or greater.

--current-time VALUE

Initial current time in seconds or HH:MM:SS.mmm format when launching the UI.

--current-frame FRAME

Initial current frame number when launching the UI.

This must be zero or greater.

Time Parsing

Cropbox accepts:

• seconds as a plain number, such as 12.5
• MM:SS, such as 01:30
• HH:MM:SS, such as 00:01:30
• fractional seconds in the final segment, such as 00:01:30.250

Negative values are clamped to 0.0.

Headless Export Rules

• Input and output paths must be different.
• Output directories must already exist.
• Output suffixes are limited to .gif, .mov, .mp4, and .png.
• Timed media requires trim-out to be greater than trim-in.
• Still images do not support trim settings.
• Crop rectangles must fit within the probed source dimensions.

Examples

Launch the desktop app:

cropbox clip.mp4

Launch at a specific time:

cropbox clip.mp4 --current-time 00:00:10.500

Launch with an initial crop:

cropbox clip.mp4 --crop 320 180 1280 720

Export a GIF:

cropbox clip.mp4 --out clip.gif --trim-in 2.0 --trim-out 6.0

Export a PNG still:

cropbox frame-source.png --out frame.png --crop 40 40 512 512