@plotset/agent-cli

Create, configure and export static charts (bar, pie, treemap, maps and more) and create, preview and render data videos (bar chart race, race line, choropleth, flow map, chronobar) from the command line, backed by PlotSet. Built for AI agents: JSON output when piped, typed error codes, no interactive prompts.

Two command groups, one binary, one login:

• plotset chart … talks directly to your PlotSet account — every chart it creates is a real project, the same one you'd see in the panel. There's no local project directory and no init/push loop: chart create returns an id, and every other command acts on that id.
• plotset video … works the other way around: a local project directory holds your data and config, and PlotSet's render farm produces preview frames and the final MP4.

Install

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

Headless environment (CI, containers, no display)? Skip auth login and set PLOTSET_TOKEN, or run plotset auth set-token <token> with a token from your account's CLI settings. plotset auth status verifies the token against both backends.

Using Claude Code (or another AI agent)? Install the bundled agent skills (plotset-charts + plotset-video) and let the agent drive the whole workflow:

plotset skill install

Quick start — charts

plotset chart templates                                            # browse the catalog
plotset chart schema bar                                           # every config path, types, defaults, enums
plotset chart create --template bar --title "Q3 Revenue" --data revenue.csv
# → {"id": 12345, ...}  — data is auto-bound to the template's axes/series
plotset chart set-config 12345 --json '{"theme":{"palette":"dusk"}}'
plotset chart export 12345 --format png --out revenue.png           # screenshots the live embed
plotset chart embed 12345                                           # → iframe snippet + share URL

chart create --dry-run validates the template ref and config without spending a project against your account — use it while an agent is iterating on --config-json.

Quick start — videos

plotset video templates                       # raceline, racebar, choropleth, …
plotset video init my-race --template racebar # scaffolds project.json + sample CSV
# swap in your data, edit project.json, then:
plotset video validate                        # config + CSV checked with the renderer's own parsers
plotset video preview                         # server-rendered JPEG under previews/ — look before you render
plotset video render                          # submits to the queue; renders consume account quota
plotset video status <taskId>                 # poll until completed, then:
plotset video download <taskId>               # save the MP4

Why agents like it

• --output json / auto-JSON when piped; --fields id,embedUrl masks trim responses to what you asked for
• Errors are typed and machine-readable: {"error":true,"code":"TEMPLATE_UNKNOWN","message":...}, with distinct exit codes per failure family (auth, input, not-found, quota, server)
• Unknown templates get did-you-mean suggestions instead of a bare 404
• chart create --dry-run / video render --dry-run gates before spending account quota
• chart set-config / set-binding / set-title are scoped, single-purpose mutations — no need to read-modify-write a whole project just to change one field (config replaces the whole chartconfig, so read chart get first if you need to merge)
• video validate runs the render farm's actual CSV parsers (vendored, version-pinned), so what validates locally is what the server will see

Full command references ship with the skills: plotset skill install, or read assets/skill/*/reference.md in this package.

Configuration

Config lives at ~/.config/plotset/config.json (override the directory with PLOTSET_CONFIG_DIR). Environment variables always beat stored values:

| Variable | Meaning | Default | |---|---|---| | PLOTSET_TOKEN | Account token (shared by chart and video commands) | — | | PLOTSET_BASE_URL | Chart/platform API | https://plotset.com/api | | PLOTSET_VIDEO_BASE_URL | Video render API | https://plotset.com/video-stream | | PLOTSET_EMBED_URL | Embed HTML base (chart export/embed) | https://plotset.com | | PLOTSET_WEB_URL | Website base for auth login and printed links | https://plotset.com |

Video template schemas are cached for an hour under ~/.config/plotset/cache/; --no-cache bypasses reads.

Requirements

Node ≥ 20. A PlotSet account. Chrome installed locally, but only for chart export — it drives your existing Chrome via puppeteer-core (no bundled Chromium) to screenshot the chart's public embed page. chart export and chart embed both mint a share link, so the chart becomes reachable by anyone with the URL — there's no private export.

Development notes

The video engine embeds a few modules vendored from the render-farm monorepo (src/video/vendor/ — see its README for provenance and re-sync instructions). @plotset/formatter is pinned exactly to the renderer's version so CLI-side CSV validation matches server-side parsing. The codegen scripts under scripts/ regenerate committed artifacts (country names, schema fixtures) and need MONOREPO_DIR pointed at a service-template-video-renderer checkout.