> ## Documentation Index > Fetch the complete documentation index at: https://rive.app/docs/llms.txt > Use this file to discover all available pages before exploring further. # Command Reference > Every Rive CLI command, flag, and exit code. ```bash theme={null} rive COMMAND ``` Run `rive --help` for this list in your terminal, and `rive --version` to print the installed version. ## Commands | Command | Does | | -------------------- | -------------------------------------------------------------------------------------------------------------- | | `rive create` | Scaffold a Rive project locally. It creates the following: `rive.yaml`, `scene.rml`, `AGENTS.md`, `.gitignore` | | `rive ` | Open the preview window and rebuild as you edit. The directory defaults to `.` | | `rive login` | Sign in with your Rive account | | `rive logout` | Sign out | | `rive whoami` | Show who you are signed in as | | `rive docs` | The CLI's own authoring documentation | | `rive samples` | Clone a runnable example project to your machine | | `rive schema` | Look up types | | `rive inspect` | Print the resolved scene | | `rive doctor` | Check the environment: version, auth, ports, project | | `rive lsp` | Language server over stdio, for editor integrations | | `rive update` | Install the latest published CLI | | `rive switch` | Pick a CLI version, or select one by name | | `rive uninstall` | Remove a cached CLI version | | `rive analytics` | Show or set usage analytics (`on` \| `off`) | `update`, `switch` and `uninstall` are only supported for the installer build under `~/.rive/bin`. If installing the CLI via Homebrew, use the `brew` methods to manage CLI versioning and updates. ## Project flags These apply to `rive `. ### Build modes Mutually exclusive, so pick one. `--screenshot` under [Capture](#capture) counts as one of them. With none of them, the CLI opens the preview window and rebuilds as you edit. | Flag | Does | | ----------- | ------------------------------------------------------------------------------------------------------------- | | `--verify` | Check the project without writing a `.riv`. Exit 1 on errors | | `--once` | Write an unsigned `.riv`. Exit 1 on errors | | `--publish` | Write a signed `.riv`. Needs `rive login`, and may watermark the output, see the note below. Exit 1 on errors | | `--test` | Run `Tests` scripts. Exit 6 on failures | Until the project is bound to a Rive file in your account, `--publish` writes a watermarked build. Binding records `push.fileId` in `rive.yaml`, and it is done by `rive push`, which is coming soon. The watermark applies whether or not the project has scripts. ### Modifiers These attach to whichever mode you chose. | Flag | Does | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--init` | Write `rive.yaml` if missing, then continue | | `--rev=` | Also write an editor `.rev`. Needs `rive login`. Combines with `--once` or `--publish`, and on its own does an `--once` build too. Refused with `--verify`, `--test` and `--screenshot` | ### Capture | Flag | Does | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `--screenshot[=]` | Build, render one frame without a window, write a PNG. Defaults to `build/.png` | | `--viewport=` | The size the scene is laid out at: the capture size with `--screenshot`, and the window size when watching. Defaults to the artboard's own size | | `--bench=` | Build, time that many frames without a window, report advance and render statistics plus WASM memory growth | `--bench` runs instead of `--screenshot`, not alongside it. Passing both times the frames and writes no PNG, without saying so. It is a build mode in its own right, so it does not combine with `--verify`, `--once`, `--publish` or `--test`. It renders at the artboard's own size and ignores `--viewport`, and it runs 300 warm-up frames before the ones it times. ### Driving the scene | Flag | Does | | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--data=` | Set one view model property before the scene runs. Repeat the flag for several properties | | `--pointer=` | Simulate one pointer event at artboard coordinates. Repeatable | | `--advance=` | Step the scene forward. Repeatable, and runs in order with the other interactions | | `--data-dump[=]` | Write the bound view model values, globals and nested artboards as JSON. Defaults to `build/.data.json`; `-` or `stdout` writes to standard output | | `--data-dump-filter=` | Keep only these property paths, comma separated. Globs allowed, as in `battery/*,score` | | `--data-dump-every=` | Sample every N frames rather than once at the end, as JSON Lines | | `--artboard=` | Artboard to show on launch. An unknown name falls back to the first artboard without warning | Interactions run in the order you write them, and `--pointer` and `--advance` need `--screenshot`. #### Advancing time `--advance` steps the scene where it sits among the other interactions. A bare number is whole frames at 60fps; `1s` or `250ms` is animation time, stepped in 1/60s frames with one shorter frame for any remainder. The time forms take a decimal point, so `1.5s` is 90 frames. ```bash theme={null} rive myproject --screenshot=out.png --advance=60 # 60 frames rive myproject --screenshot=out.png --advance=1s # the same, written as time rive myproject --screenshot=out.png --advance=250ms ``` Position it for what you need: | Where | Does | | ---------------------- | ---------------------------------------------------------- | | Before a gesture | Plays an intro before the interaction lands | | Between two gestures | Lets one action's transition finish before the next starts | | After the last gesture | Settles the scene before the capture | ```bash theme={null} rive myproject --screenshot=out.png \ --advance=1s \ --pointer=click@120,60 \ --advance=20 ``` A sign, whitespace, trailing text, a decimal point on a bare frame count, or a value above a 32-bit unsigned integer is rejected with exit code 2. `--advance` replaces `--frame`. A bare `--advance=N` means what `--frame=N` meant, so `--frame=20` becomes `--advance=20`. Passing `--frame` is an error naming `--advance`. `--bench` takes its own frame count and does not combine with `--advance`, `--pointer`, `--gamepad`, `--semantics` or `--semantic-action`. #### Setting data `--data` takes a property path and a value. The path starts at the view model instance bound to the artboard, and every segment is a property name, so a flat view model takes the bare property and a nested one takes a path: ```bash theme={null} rive myproject --screenshot=out.png --data=level=100 rive myproject --screenshot=out.png --data=battery/level=100 ``` Each `--data` sets one property. Repeat the flag to set several: ```bash theme={null} rive myproject --screenshot=out.png \ --data=settings/speed=42 \ --data=settings/scale=9 ``` A path that matches no property logs `data: no property at ""` and is dropped. The build still succeeds, and the scene renders with that property's authored value. Under `--quiet` you see nothing at all, so confirm your values landed rather than assuming they did. #### Reading data back `--data` sets values going in; `--data-dump` reads them back out. It builds, runs headless, and writes the bound view model values as JSON, so a test can assert on what the scene computed: ```bash theme={null} rive myproject --data-dump=- --advance=60 ``` `--data-dump-every` turns that into a time series instead of a single reading: a header, a frame-0 baseline, then only what changed on each sample. It takes a whole number of frames at 60fps, and counts the frames gestures advance internally. #### Simulating a pointer `--pointer` takes a kind and a position. `down`, `up`, `move` and `click` each take a single point. `click` expands to a move, a press and a release with a frame between each, because a state machine only sees a gesture when it next runs: ```bash theme={null} rive myproject --screenshot=out.png --pointer=click@120,60 ``` `--pointer` only checks the shape of the value. A kind that is not `down`, `up`, `move`, `click` or `drag` parses fine, then fails at delivery with `pointer: unknown gesture` and exits with `1`. `drag` is a fifth kind, and the only one with a different shape: `drag@x1,y1>x2,y2[:steps]`. It moves to the first point, presses, emits `steps` moves along the line to the second point, then releases. `steps` defaults to 8. Every event gets its own frame, so a drag runs for `steps + 3` frames: a higher count is a finer and slower sweep, a lower one a flick. Scroll physics reads the velocity that implies, so the count changes how far a scroll throws. ```bash theme={null} rive myproject --screenshot=out.png --pointer='drag@200,300>200,80:12' ``` Quote the `drag` value so the shell does not read `>` as a redirection. ### Serving | Flag | Does | | ------------------ | ---------------------------------------------------------------- | | `--serve[=port]` | Also push builds to connected players. Defaults to port `9640` | | `--headless-serve` | Serve with no local window. Takes its port from `--serve=` | ### Other | Flag | Does | | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `--quiet` | No terminal log at all, compiler errors included. Read the exit code, `--format=json`, or `logs.problems` instead | | `--optimize` | Compile scripts at Luau O2 instead of O1. The scripts run faster and the bytecode is harder to debug | | `--immediate` | Render on the main thread | | `--format=json` or `--format=human` | `human` is the default terminal log. `json` needs `--once`, `--verify`, `--publish` or `--test`, and prints one JSON report object on stdout | ## Preview window commands Type these in the terminal while the preview window is open. | Key | Does | | -------------------------- | -------------------------------------------------------------------------- | | `s` or `screenshot [path]` | Write a PNG of the window | | `p` or `pause` | Toggle playback | | `a` or `artboard [name]` | Switch the shown artboard | | `f` or `fit [mode]` | Switch how the artboard maps into the window. Bare `f` lists the modes | | `z` or `size` | Resize the window to the artboard, and follow it again after a manual drag | | `rev [path]` | Write an editor `.rev`. Needs `rive login` | | `?` or `help` | List commands | ## Per-command flags ### `create` ```bash theme={null} rive create # prompt for a name, then write that directory rive create # write the project in (`.` is the cwd) rive create [dir] --from-rev= ``` `--from-rev` converts an editor `.rev` into a project: `scene.rml` plus its scripts and assets as files. Without a ``, the `.rev`'s own name is used. The directory must be empty or new. ### `schema` ```bash theme={null} rive schema # properties of a type, inherited included rive schema --search # find a type or property by name, then pick one ``` | Flag | Does | | -------------- | ------------------------------------------------------------------------- | | `--list` | Pick a type to describe. Where no picker can draw, prints every type name | | `--animatable` | Only properties that can be keyed | | `--bindable` | Only properties that can be data bound | | `--all` | Include editor-only properties | ### `docs` ```bash theme={null} rive docs # the documentation index rive docs # one topic, for example `layout` or `luau/protocols` ``` | Flag | Does | | ----------------- | -------------------------------------- | | `--list` | Pick a topic to read | | `--search ` | Lines matching text across every topic | | `--path` | Print the docs directory on disk | ### `samples` ```bash theme={null} rive samples # pick one and copy it into a new directory rive samples --path # print the samples directory on disk ``` ### `inspect` ```bash theme={null} rive inspect [dir] # resolved scene as JSON. The directory defaults to `.` ``` Exits `1` when `problems` contains an error, and `1` with a message on stderr when the directory has no `rive.yaml`. | Flag | Does | | ------------------- | -------------------------------------------------------------------------------------- | | `--json` | JSON output (the default) | | `--all` | Include editor-only properties | | `--artboard=` | One artboard only. An unknown name gives an empty `artboards` list and still exits `0` | ### `doctor` ```bash theme={null} rive doctor [project-dir] ``` | Flag | Does | | --------------- | --------------------------------- | | `--format=json` | Machine-readable report on stdout | `doctor` prints five checks (`version`, `update`, `auth`, `live-link` and `project`), each `ok`, `warn` or `fail`. It exits `0` when everything is `ok` or `warn`, and `1` when a check fails. ## Signing in | What you run | Session needed | | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--publish`, `--rev` | Yes, with `rive login` | | Preview window, `--once`, `--verify`, `--test`, `--screenshot`, `--serve`, `--headless-serve` | No, and these work offline | | `create`, `docs`, `samples`, `schema`, `inspect` | No | | `update`, `whoami`, `doctor` | No account, but they reach the network. `whoami` exits `3` when you are not signed in and `7` when it cannot reach Rive; `doctor` reports a missing session as a warning and still exits `0`, but exits `1` when a check fails | Credentials live outside the project: `~/.config/rive/app.rive.cli/` on macOS and Linux, honouring `XDG_CONFIG_HOME`, and Windows Credential Manager on Windows. A gated mode checks the session live, so `--publish` and `--rev` fail on a dropped connection even with valid stored credentials. ## Exit codes | Code | Meaning | | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `0` | OK | | `1` | Build errors, or any failure without a more specific code | | `2` | A flag the CLI parsed and rejected: a bad `--pointer`, `--data`, `--advance` or `--viewport` value; `--frame`, which is gone; `--format` given anything but `json` or `human`; `--format=json` without a build mode; two build modes at once; `--rev` with a mode that writes nothing; an interaction with no `--screenshot`; or `rive` with no arguments outside a project | | `3` | Not logged in, or the session was rejected | | `6` | Test cases failed. The build itself was fine | | `7` | A service could not be reached, so it is safe to retry | Exit 2 does not cover a misspelled flag. On `rive `, a flag the CLI does not recognize is ignored, so `--bogus` builds and exits `0`. Values are checked, though: `--viewport=abc` exits `2` with a message, and so does every other flag value the CLI parses. A bare word is read as the project directory and the last one wins, so a stray argument silently changes what gets built. A green exit is not proof your flags landed. ## JSON output `--format=json` on `--once`, `--verify`, `--publish` or `--test` prints one JSON object on stdout. `data` differs per mode. `--verify` and `--once` carry the build: ```json theme={null} {"success": true, "command": "build", "data": {"riv": "./build/myproject.riv", "bytes": 140, "buildMs": 2.0, "problems": []}, "errors": [], "warnings": []} ``` `--test` carries the run: ```json theme={null} {"success": false, "command": "test", "data": {"passed": 5, "failed": 1, "noTestsFound": false, "failures": [{"test": "clamp > intentional failure", "line": 29, "message": "5 is not equal to 10"}]}, "errors": ["clamp > intentional failure: 5 is not equal to 10"], "warnings": []} ``` `command` is the mode, not the flag: `"build"` for `--once`, `"verify"` for `--verify`, `"publish"` for `--publish`, `"test"` for `--test`. Each entry in `data.problems` is `{severity, kind, code, script, line, column, message}`, with `severity` one of `error`, `warning` or `hint`. `errors` repeats them as `script:line message` strings, carrying the same zero-based line, and drops the `:line` entirely for a problem on the first line. `data.riv` is `null` on `--verify` and on any failed build. Logs stay on stderr, so stdout carries nothing else. `line` and `column` in `--format=json` are zero-based, while the terminal log and `rive inspect` report the same problem one-based. Add 1 before showing either to a person. ## Environment variables | Variable | Overrides | | ------------------ | -------------------------------------------------------------------------- | | `RIVE_API_BASE` | The API host. A custom host also gets its own stored login | | `RIVE_NO_TUI` | Any value except `0` disables interactive pickers | | `TERM` | Unset, empty, or `dumb` disables interactive pickers | | `NO_COLOR` | Draws pickers without color | | `RIVE_HOME` | The CLI's install and state root. Defaults to `~/.rive` | | `XDG_CONFIG_HOME` | Relocates the credential directory on macOS and Linux | | `RIVE_DOCS_DIR` | The directory `rive docs` reads | | `RIVE_SAMPLES_DIR` | The directory `rive samples` copies from | | `RIVE_ANALYTICS` | Forces analytics consent: `on`/`1`/`true`/`yes`, or `off`/`0`/`false`/`no` | Interactive pickers draw on stderr, so redirecting stdout alone does not disable them. Where no picker can draw (`TERM=dumb`, `RIVE_NO_TUI=1`, or stdin not a terminal as in CI), the CLI falls back to printing the list instead.