Quick start
Use Node 22 or later. Any package manager works; the examples use npm. You need a browser, a terminal
and an API key with the themes:write scope. Steps 7 and 8 need the scopes in
Set up through REST. Set LIGR_API_KEY in your shell.
This example uses plain HTML, CSS and JavaScript. Any browser rendering library can use the same protocol and publishing tools.
-
Scaffold the graphic.
Terminal npx @ligr/cli graphic init my-graphiccd my-graphicnpm installnpx @ligr/cliruns theligrCLI from npm without an install. To install theligrcommand, runnpm i -g @ligr/cli. The scaffold pins both packages to exact public GitHub release URLs. Downloads need no npm account or GitHub authentication. Keep the generated lockfile in Git.ligr-graphicis the old name.npx ligr-graphic <command>still runsligr graphic <command>and prints a deprecation notice. Replaceligr-graphic <command>withligr graphic <command>.The folder holds a scorebug, the manifest
graphic.json, and two files for coding agents:AGENTS.mdand.claude/skills/ligr-graphic/SKILL.md. Delete them if you do not use an agent. The default template uses one HTML file and a script that copies its files intodist/.Edit
index.html. ItscreateGraphiccallbacks receive match data and handle visibility. The hide callback resolves after the animation; the SDK then sendsHIDDEN. The SDK is optional: any implementation of the protocol can run on LIGR. -
Create a theme. Once per theme. Skip this step if your organization already has one:
npx @ligr/cli graphic theme listprints the themes you own.Terminal npx @ligr/cli graphic theme create --name "My Theme" --sports footballThe command prints the theme id and writes it into
ligr.json, because the folder holdsgraphic.json. Your organization can own up to five themes. -
Create the graphic in the theme.
Terminal npx @ligr/cli graphic create --name "Scorebug" --sports footballThe command writes the graphic id into
ligr.json. Pass--theme <id>to use a theme that is not inligr.json. -
Push the bundle.
Terminal npx @ligr/cli graphic pushThe command builds, checks the manifest and the files with the API rules, uploads the changed files, and records the bundle. Run
npx @ligr/cli graphic validateto check without a push. -
Test the draft in the dashboard.
Open the graphic from your theme in the dashboard. The code viewer loads the working version you pushed. Choose a scenario under Data, edit declared variables under Controls, inspect Files, then press Show and Hide. See Test and troubleshoot.
-
Publish the graphic, then the theme.
Terminal npx @ligr/cli graphic publish --theme-versionThe command prints the published theme version. Inspect and activate that exact version when the broadcast allows it.
Terminal — replace 1 with the published theme version npx @ligr/cli graphic theme inspect --version 1npx @ligr/cli graphic theme activate --version 1Activation does not publish another version. Existing overlay pages need a reload to load the selected version. See Push and publish.
-
Prepare the control room through REST.
Follow Set up through REST with the theme and graphic IDs from the publishing steps. Create or reuse the competition, teams, venue, and match through REST. Create the theme profile, room, section, and graphic preset. Create an overlay with that profile and room,
autoMode: false, andadType: "noBrands".The API returns
controlRoomUrl. Open that URL when setup is complete. Your browser needs a dashboard session with access to the same organization. -
Operate the prepared graphic.
Select GFX In on the preset. Verify the graphic on the preview overlay. After changing its variables, select Update GFX to apply the values while it is shown. Select GFX Out to hide it.
REST commands also require manual mode; they do not enable it. See Presets for preset commands, or address the graphic directly over REST:
Set
OVERLAY_IDto your match overlay’s numeric id.Terminal curl -X POST "https://api.ligr.live/rest/v2/overlays/$OVERLAY_ID/graphics/commands" \-H "Authorization: Bearer $LIGR_API_KEY" \-H 'Content-Type: application/json' \-d '{ "command": "show", "name": "Scorebug" }'
What to do next
Section titled “What to do next”- Add control variables so an operator can change what the graphic shows. See The manifest.
- Read the other surfaces: theme variables, images and external data. See Data binding.
- Read the rules the bundle must follow. See Bundle rules.
- Write your own listener without the package. See The protocol.
- Push without the CLI, one REST call at a time. See Push and publish.