Documentation & CLI Reference

Sitecast CLI Manual

Everything you need to know about installing, configuring, running, and troubleshooting Sitecast CLI on your Linux system.

Quickstart Guide

Install Sitecast globally via npm, check system dependencies using sitecast doctor, and record your first website video.

npm install -g sitecast

sitecast doctor

sitecast render https://example.com

System Requirements

OS: Linux (Ubuntu 20.04+, Debian, Arch Linux, Fedora, WSL2)
Node.js: Version 18.0.0 or later
FFmpeg: Installed in system PATH with libx264 support
Xvfb: Virtual X11 display server (xorg-server-xvfb or xvfb)
Browser: Google Chrome or Chromium (or managed Playwright Chromium via sitecast setup)

Installing system dependencies on Ubuntu:

sudo apt update && sudo apt install ffmpeg xvfb x11-utils chromium-browser

Installing system dependencies on Arch Linux:

sudo pacman -S ffmpeg xorg-server-xvfb xorg-xdpyinfo chromium

Command Reference

sitecast render <url> [options]

Main command to record a website. Opens the URL in a headed Chromium browser under Xvfb, performs human-like top-to-bottom scrolling, and outputs an MP4 video file.

sitecast doctor

Runs environment diagnostic checks for Linux kernel, Node.js version, FFmpeg binary, Xvfb display server, xdpyinfo utility, Chrome executable, and temp folder write permissions.

sitecast setup

Downloads and installs a Playwright-managed Chromium build to ~/.cache/ms-playwright/ if system Chrome is not present.

Options & Flags

Flag / Option	Default	Description
-o, --output <path>	./sitecast-<timestamp>.mp4	Destination file path for the recorded MP4 video
--width <px>	1280	Viewport width in pixels
--height <px>	720	Viewport height in pixels
--fps <n>	30	Recording frame rate (e.g. 30 or 60)
--no-browser-frame	false	Record in kiosk mode without browser address bar chrome
--dark-mode	false	Forces prefers-color-scheme: dark in Chromium
-v, --verbose	false	Print full FFmpeg and Playwright renderer debug output

Environment Variables

CHROME_EXECUTABLE	Auto-detected	Override path to Chromium or Google Chrome binary
FFMPEG_BIN	ffmpeg	Override binary path for FFmpeg executable
XVFB_DISPLAY_START	99	First virtual X11 display number used for rendering

Troubleshooting

Missing Xvfb or display error

Install xvfb using your package manager. On Ubuntu: sudo apt install xvfb. On Arch: sudo pacman -S xorg-server-xvfb.

Missing FFmpeg

Sitecast requires FFmpeg to record virtual X11 display output. Run sitecast doctor to confirm FFmpeg detection.

Temporary directory write permission

Ensure your user account has write access to /tmp where frame buffers and temporary pipes are created during recording.