CLI Options

Command syntax#

rollberry capture <url...> [options]

The capture subcommand is required. You can provide one or more URLs as positional arguments. If multiple URLs are provided, they are captured sequentially and stitched into a single video file.

Options reference#

The following table lists every available CLI option:

Detailed option descriptions#

URL (positional arguments)#

You can provide one or more URLs. URLs are captured in the order they are listed:

# Single URL
rollberry capture https://example.com
 
# Multiple URLs (stitched into one video)
rollberry capture https://example.com https://example.com/about
 
# Localhost
rollberry capture http://localhost:3000

--out#

Specifies the path for the output MP4 file.

rollberry capture https://example.com --out my-video.mp4

--viewport#

Sets the browser viewport dimensions. The format is WIDTHxHEIGHT in pixels:

# Full HD desktop
rollberry capture https://example.com --viewport 1920x1080
 
# Mobile device
rollberry capture https://example.com --viewport 390x844

--fps#

Sets the frame rate of the output video. The maximum supported value is 60:

# Standard 60 FPS (default)
rollberry capture https://example.com --fps 60
 
# Lower frame rate for smaller file size
rollberry capture https://example.com --fps 30

--duration#

Controls the scroll duration in seconds. When set to auto (default), Rollberry calculates the duration based on the scrollable height of the page (approximately 800px per second, clamped between 4s and 40s).

# Automatic duration based on content
rollberry capture https://example.com --duration auto
 
# Fixed 10-second scroll
rollberry capture https://example.com --duration 10

--motion#

Defines the easing curve used for scrolling:

• ease-in-out-sine (default): Smooth acceleration and deceleration.
• linear: Constant speed from start to finish.

rollberry capture https://example.com --motion linear

--wait-for#

Determines when the capture starts after navigation:

• load (default): Wait for the browser load event.
• selector:<css>: Wait until the specified CSS selector is visible.
• ms:<n>: Wait for a fixed number of milliseconds.

# Wait for main element
rollberry capture https://example.com --wait-for "selector:#main-content"
 
# Fixed 5-second delay
rollberry capture https://example.com --wait-for "ms:5000"

--hide-selector#

Hides elements matching the CSS selector before capture begins. This flag can be used multiple times:

rollberry capture https://example.com \
  --hide-selector ".cookie-banner" \
  --hide-selector ".sticky-nav"

--page-gap#

When capturing multiple URLs, this adds a static pause (in seconds) between the pages. The video will show the last frame of the previous page for the specified duration before moving to the next URL.

rollberry capture https://a.com https://b.com --page-gap 2

--force#

By default, Rollberry will exit with an error if the output file already exists. Use --force to overwrite it:

rollberry capture https://example.com --force

--debug-frames-dir#

Saves every individual PNG frame captured by the browser into the specified directory. Extremely useful for debugging rendering or timing issues.

rollberry capture https://example.com --debug-frames-dir ./debug-frames

--manifest#

Rollberry generates a sidecar JSON file containing metadata about the capture (duration, frame count, pages, etc.). Use this flag to change its location.

--log-file#

Saves structured JSONL logs to the specified file. Useful for automated pipelines and post-capture analysis.

Exit codes#