codevideo

The CLI tool for generating CodeVideos.

The npm wrapper installs only the native binary for your operating system and architecture:

npx @fullstackcraftllc/codevideo-cli doctor
npx @fullstackcraftllc/codevideo-cli install-browser # only when Chrome is not already installed
npx @fullstackcraftllc/codevideo-cli --version

Rendering requires Node.js 20 or newer, Chrome/Chromium, and FFmpeg. Chrome is detected from CODEVIDEO_CHROME_PATH, the managed CodeVideo browser cache, or common system locations. FFmpeg is resolved from CODEVIDEO_FFMPEG_PATH and then PATH.

The wrapper supports these optional runtime locations:

• CODEVIDEO_PUPPETEER_RUNNER_PATH
• CODEVIDEO_WORK_DIR
• CODEVIDEO_LOG_DIR
• CODEVIDEO_OUTPUT_DIR
• CODEVIDEO_BROWSER_CACHE_DIR

git clone https://github.com/codevideo/codevideo
cd codevideo
cd puppeteer-runner
npm install
npx @puppeteer/browsers install chrome@latest

Make a note of what was installed in puppeteer-runner/chrome - you'll need to update the path in puppeteer-runner/recordVideoV3.js on line 73.

Then build the Go binary:

cd ../..
go build -o codevideo

Very importantly, create a .env file with your Elevenlabs API key:

# Copy from .env.example and fill in your values
ELEVEN_LABS_API_KEY=your-elevenlabs-api-key
# ... other configuration options

You should be ready to start using the CodeVideo CLI!

If you don't have an Elevenlabs account - we're working on a solution with htgo-tts and other providers.

With actions:

./codevideo -p "$(cat data/actions.json)"

Note: if you are using zsh and get the error zsh: event not found: \, try deactivating history expansion with set +o histexpand and try the command again.

If all works well, you should see the following final output:

Detected project type: Actions
/> CodeVideo generation in progress...
[==========================] 100% 
✅ CodeVideo successfully generated and saved to CodeVideo-2025-03-21-18-58-47.mp4

As an alternative, paste your actions, lesson, or course JSON into data/actions.json, data/lesson.json, or data/course.json respectively - all types are accepted.

With actions:

./codevideo -p "$(cat data/actions.json)"

With a lesson:

./codevideo -p "$(cat data/lesson.json)"

With a course:

./codevideo -p "$(cat data/course.json)"

./codevideo -p "$(cat data/actions.json)" -o codevideo-intro.mp4 --open

You can specify the orientation and resolution of the video with the -r or --resolution and -o or --orientation flags, respectively. The default resolution is 1080p and the default orientation is landscape.

All React IDE props from the CodeVideoIDE can be passed in via the -c or --config to a config.json file. (See data/config.json for an example)

./codevideo -p "$(cat data/actions.json)" -c data/config.json

Simply pass the -m serve parameter to the command to start the server:

./codevideo -m serve

To run in the background use nohup or similar:

nohup ./codevideo -m serve &

This will watch for manifest files in /tmp/v3/new and process them as they arrive. The server will output the video to the output folder.

The render worker ships as a multi-arch image (linux/amd64, linux/arm64) on Docker Hub as fullstackcraft/codevideo-cli. CI builds and pushes it on every v* tag — see .github/workflows/docker-image.yml.

The codevideo-api compose stack pulls this image and runs it in serve mode. It's a filesystem-queue worker — no published port — that shares the API's render queue through a bind mount and reads its secrets (S3, Clerk, Slack, Mailjet) from the central .env:

  codevideo-cli:
    image: fullstackcraft/codevideo-cli:0.0.8   # pin to a release
    restart: always
    init: true
    shm_size: "1gb"
    volumes:
      - ./tmp/v3/:/work/tmp/v3/
    env_file: .env
    environment:
      - CODEVIDEO_WORK_DIR=/work/tmp/v3

docker build -t fullstackcraft/codevideo-cli:dev .

Mount an env file and an output dir, then pass actions directly (this overrides the default -m serve):

docker run --rm \
  -e CODEVIDEO_OUTPUT_DIR=/app/output \
  -v "$(pwd)/.env:/app/.env" \
  -v "$(pwd)/output:/app/output" \
  fullstackcraft/codevideo-cli:dev \
  -p "[{\"name\":\"author-speak-before\",\"value\":\"Let's learn how to use the print function in Python!\"}]"

You can update the Gatsby static site by replacing the public folder within cli/staticserver. We recommend you use the example site within the example folder of the @fullstackcraftllc/codevideo-ide-react repository.

Everything in the public folder is treated as an embedded Go resource and served by the server.

Build your actions JSON in the CodeVideo Studio!

Set NPM_TOKEN as a repository variable in Github.

Then run the following command to deploy:

go test ./...

cd npm
npm ci
npm run release:check

git tag -a v0.0.7 -m "Release codevideo-cli 0.0.7"
git push origin main
git push origin v0.0.7