Install issues

cleya: command not found

npm link did not complete, or your global npm bin is not on PATH. Check with npm bin -g and confirm that directory is in your shell's PATH.

FFmpeg not found

Install it (brew install ffmpeg, apt install ffmpeg) or point Cleya at a specific binary with the ffmpeg_path config key. Confirm with cleya doctor.

DRAWTEXT_NOT_FOUND

Your FFmpeg was built without libfreetype, so the drawtext filter is missing. card, caption and autosub need it. On macOS:

brew tap homebrew-ffmpeg/ffmpeg
brew install homebrew-ffmpeg/ffmpeg/ffmpeg

WHISPER_NOT_FOUND

whisper.cpp is not installed or not on PATH. Only the transcription tools need it — everything else runs without it. Set whisper_path if it lives somewhere unusual.

No Chrome found

The render backend auto-detects Chrome, Chromium, Edge and Brave. If detection fails, set CLEYA_CHROME to the binary path. In a container you will usually also need:

export CLEYA_CHROME_FLAGS="--no-sandbox"

macOS asks for permissions on first run

The Vision-backed helpers are compiled from source on first use and cached. That requires Xcode Command Line Tools:

xcode-select --install

Build fails after cloning

Make sure you are on Node 18 or newer (node --version), then:

rm -rf node_modules dist && npm install && npm run build && npm test

A clean build should end with 779 passing tests across 74 files.