CLI - UpstandPlatform/OpenRive GitHub Wiki

openrive runs on Bun and talks to the database directly, so the web app does not need to be running. An open editor tab picks up changes within a couple of seconds.

Running it

bun run cli <command>             # from the repository
bun link                          # once, then:
openrive <command>

In Docker: docker compose exec openrive openrive <command>.

Interactive mode

Running openrive with no command opens a terminal UI (built with OpenTUI):

OpenRive 18 projects
  ▸ Welcome to OpenRive     1 artboards · 6 timelines · 1 state machines · 22/09/2026, 19:02
    CyFit-Robot             1 artboards · 26 timelines · 1 state machines · …
↑↓ select · n new · e export · o editor url · d delete · u users · r refresh · q quit

Key	Does
`↑` `↓`	Move through projects
`n`	New project — pick a template or example from a list
`e`	Export the selected project to a `.riv` in the current folder
`o`	Show the editor URL for the selected project
`d`	Delete the selected project (asks first)
`u`	Show users
`r`	Refresh
`q` / `Ctrl C`	Quit

Scripts and pipes still get plain commands: with no TTY, openrive prints its help instead of opening the UI.

Commands

Server

Command	Description
`serve [--port 3000] [--host 0.0.0.0] [--dev]`	Start the editor
`mcp`	Start the MCP server on stdio

Projects

Command	Description
`list`	List projects (id, name, owner, updated)
`new <name> [--template <id>]`	Create a project from a template or example (`templates` lists ids)
`templates`	List templates and example files
`import <file.riv…> [--name <name>]`	Import `.riv` files as projects
`export <project> [out.riv]`	Write a project's `.riv`
`export <project> [out.zip] --bundle [--cdn]`	Write a standalone preview bundle: `index.html`, `index.js`, the `.riv` and (without `--cdn`) the Rive runtime
`info <project \| file.riv\|file.oriv\|source-folder> [--json]`	Show artboards, objects, timelines, state machines and theme colors
`delete <project>`	Delete a project
`validate <file.riv\|file.oriv\|source-folder…>`	Check files round-trip losslessly and validate editable sources
`diagnose <file.riv\|file.oriv\|source-folder…> [--json]`	Explain missing assets, unknown objects, uneditable features and compatibility risks
`source export <project\|file.riv> [out.oriv\|folder]`	Export a portable `.oriv` backup or a Git-friendly source folder
`source import <file.oriv\|folder> [name]`	Import an editable source archive or folder as a project
`render <project\|file.riv\|file.oriv\|source-folder> [out.png] [options]`	Render a still frame locally with the Rive runtime

Projects can be referenced by id or name.

Users

Command	Description
`users`	List users
`users add <name> [--role …] [--password <pw>] [--email <e>]`	Add a user, optionally with a password
`users password <name\|id> [--password <pw>]`	Set a password (asks for it when not given) — how you recover a locked-out server
`users role <name\|id> --role admin\|editor\|viewer`	Change a role
`users remove <name\|id>`	Remove a user (their files move to an admin)

Database

Command	Description
`db status`	Show the database in use and what it holds
`db import [dir]`	Import a legacy data folder (the pre-Drizzle file storage)
`db auth`	Whether sign-in is required, and which accounts can sign in

Global options

Option	Description
`--db <url>`	PostgreSQL URL (same as `DATABASE_URL`)
`--data <dir>`	Data folder for the embedded database (default: `./data`)
`--help`	Help

Examples

openrive new "Onboarding" --template interactive-button
openrive info "Onboarding"
openrive export "Onboarding" ./onboarding.riv
openrive export "Onboarding" --bundle                # a zip that plays the animation anywhere
openrive import ~/Downloads/*.riv
openrive validate ./assets/*.riv                     # CI check that files are intact
openrive diagnose ./assets/character.riv --json      # machine-readable file health report
openrive source export "Onboarding" ./onboarding-src # manifest + separately stored assets
openrive source export ./onboarding.riv ./backup.oriv
openrive source import ./backup.oriv "Onboarding copy"
openrive render ./onboarding.riv ./frame.png --animation 0 --time 0.5 --scale 2
openrive info some.riv --json | jq '.artboards[0].stateMachines'
openrive --db postgres://localhost/openrive list

With the embedded database, stop the web app first (one process at a time), or give the CLI its own --data folder.

See Git-friendly sources and backups for the folder layout, safety limits and CI examples.

_{This page is generated from docs/cli.md. Suggest an edit.}