CLI Reference

Getting started

Basic usage

The CLI entry point is main.py. At minimum, pass a topic:

python main.py --topic "explain how B-trees work"

This runs the full pipeline: script generation, fact-checking, Manim code generation, layout validation, TTS voiceover, Docker render, and ffmpeg merge. Output lands in output/<run-id>/final.mp4.

Common patterns

# Quick low-effort run
python main.py --topic "what is a hash table" --effort low

# High-effort with web research, algorithm template
python main.py --topic "explain merge sort" --effort high --template algorithm

# Expert audience, formal tone, light theme
python main.py --topic "CAP theorem" --audience expert --tone formal --theme light

# Pipeline only (no Docker render)
python main.py --topic "recursion basics" --no-render

Reference

CLI flags

Core

Context

Output

Render

Source material

Context injection

Pass local files, URLs, or GitHub repos as source material. The pipeline builds the animation from your content rather than Claude's training data alone.

Local files and directories

# Explain a codebase
python main.py --topic "explain this codebase" --context ./src --context ./docs

# Turn a paper into an animation
python main.py --topic "summarize this paper" --context paper.pdf

# Exclude lock files and build output
python main.py --topic "visualize this" --context ./repo --context-ignore "*.lock" --context-ignore "dist/"

# Obsidian vault page
python main.py --topic "visualize my notes" --context ~/Documents/vault/page.md

URLs and GitHub repos

# Web article
python main.py --topic "explain this concept" --url https://en.wikipedia.org/wiki/Binary_search_tree

# GitHub repo README
python main.py --topic "explain this project" --github nicglazkov/Chalkboard

# Combine files and URLs
python main.py --topic "explain my project" --context ./README.md --url https://example.com/blog-post

Supported file types

Text and code files (.py, .js, .md, .yaml, .ps1, .bat, and many more), images (.png, .jpg, .webp, .gif), PDFs, and Word docs (.docx). URLs are fetched with HTML stripped to plain text, truncated at 100k characters.

File uploads via the web UI

The web UI also supports file uploads with drag-and-drop folder support. See file uploads in the Guide for details and size limits.

Token reporting

Before the pipeline starts, Chalkboard reports how much of the context window your source material uses. If context exceeds 10k tokens you'll be prompted to confirm. Pass --yes to skip this prompt for scripted runs. If context exceeds 90% of the model window, Chalkboard aborts.

Resuming with context

--context, --url, and --github are not stored in the checkpoint. Pass them again on resume:

python main.py --topic "..." --run-id <id> --context ./src

Configuration

Environment variables

All settings can be overridden via .env or environment variables. Copy .env.example to get started.

Checkpointing

Resuming runs

Every run is checkpointed after each pipeline stage. If it crashes or you abort, resume with the same run ID:

python main.py --topic "..." --run-id <previous-run-id>

Execution picks up from the last successful checkpoint. The pipeline does not re-run stages that already completed.

Preview to full render workflow

Run --preview first to quickly check the visuals at low quality, then do the full HD render. The pipeline result is already checkpointed, so it won't re-run:

# Step 1: generate script + animation, render preview
python main.py --topic "how B-trees work" --preview
# → output/<run-id>/preview.mp4 (480p, fast)

# Step 2: full HD render (pipeline skipped — uses checkpoint)
python main.py --topic "how B-trees work" --run-id <run-id>
# → output/<run-id>/final.mp4 (full quality + visual QA)