@plotset/video-cli

Create data videos (bar chart races, race lines, animated maps and more) from the command line, rendered by PlotSet. Built for AI agents: JSON output when piped, typed error codes, machine-readable schemas, no interactive prompts.

Install

npm install -g @plotset/video-cli
plotset-video auth login   # opens your browser to confirm — no token copy-paste

Headless environment (CI, containers, no display)? Skip auth login and set PLOTSET_VIDEO_TOKEN, or run plotset-video auth set-token <token> with a token from your account's CLI settings.

Using Claude Code (or another AI agent)? Install the bundled agent skill and let the agent drive the whole workflow:

plotset-video skill install

Quick start

plotset-video templates                          # 8 template types
plotset-video init my-video --template racebar   # scaffold project.json + sample data
# put your data in my-video/data/layer-1.csv, tweak my-video/project.json
plotset-video validate my-video                  # config + CSV checks (schema-exact)
plotset-video preview my-video --at 0.5          # server-rendered frame → previews/*.jpg
plotset-video render my-video                    # submit → {"taskId": "..."}
plotset-video status <taskId>                    # poll until completed
# → your video: https://plotset.com/panel/video-render

A project is a plain directory: project.json (title, fps/resolution/quality, layers with per-layer config + CSV path), data/*.csv, previews/. Everything is editable with any editor; plotset-video template schema <type> prints every valid config path with types, defaults, enums and theme palettes.

Why agents like it

• --output json / auto-JSON when piped; NDJSON lists; --fields masks
• Errors: {"error":true,"code":"VALIDATION_FAILED","message":...} + exit-code families
• validate runs the renderer's own CSV parsers — what passes locally renders remotely
• render --dry-run gate before spending render quota
• Unknown config keys fail fast with did-you-mean suggestions

Full command reference ships with the skill: plotset-video skill install, or read assets/skill/reference.md in this package.

Requirements

Node ≥ 20. A PlotSet account.