Install

One binary for macOS Apple Silicon and Linux x86_64. Media tools are downloaded and checksum-verified on first use.

curl -fsSL https://github.com/cerul-ai/cerul-robotics/releases/latest/download/cerul-robotics-installer.sh | sh
cerul-robotics --version

Your first episode

Export your model key in the environment (Gemini by default), preview, then run.

# preview: no files written, no model calls
cerul-robotics annotate ./dataset --only 0 --semantic --dry-run --json
# label, then watch the result
cerul-robotics annotate ./dataset --only 0 --semantic --json
cerul-robotics render ./dataset/.cerul/episodes/0/annotations.json --out ./review.mp4

Add --hands --semantic none to track human hands locally without a key.

LeRobot writeback

Reads v3.0 and v3.1. Writes subtasks to v3.1 language columns. Prefer a new copy:

cerul-robotics annotate ./dataset --semantic subtask --write-lerobot --out ./dataset-labeled

Output files

JSON and events

--json prints one final object on stdout and NDJSON progress on stderr, line by line:

stderr
{"event":"annotation_progress","episode":"6774a70fd1f870ab/0","done":220,"total":221}
{"event":"published","annotation":"semantic.subtask","records":4}
stdout
{"modules":[{"annotation":"semantic.subtask","complete":true,"records":4}],"partial":false}

Exit codes

Configuration

Later sources win:

1. ~/.cerul-robotics/config.toml
2. project cerul-robotics.toml
3. environment variables
4. --set section.field=value

Use --workspace ~/.cerul to read labels made by earlier cerul annotate versions.