---
title: "Command line"
description: "Open, play, inspect and export animations, or work with LottieFiles from your shell."
canonical: "https://terminal.lottiefiles.com/docs/cli/"
last_updated: 2026-10-30
---

# Command line

Open, play, inspect and export animations, or work with LottieFiles from your shell.

Run `creator-tui --help` for the command list, or `creator-tui <command> --help` for its arguments.
Examples below use files and workspace names you replace with your own.

## Start and get help

| Command or option | What it does | Example |
| --- | --- | --- |
| No arguments | Opens home. | `creator-tui` |
| `[FILE]` | Opens a `.ctd` locally, or JSON, `.lottie`, SVG, Frolic `.vd` or Rive `.riv` as a document saved beside it as a `.ctd`. An `lf:` path or LottieFiles link opens a linked working copy. | `creator-tui hero.lottie` |
| `-h`, `--help` | Prints help. | `creator-tui --help` |
| `help [COMMAND]` | Prints help for a command. | `creator-tui help export` |
| `-V`, `--version` | Prints the installed version. | `creator-tui --version` |
| `--` | Ends options, for a filename beginning with a dash. | `creator-tui -- -hero.json` |

SVG opens as a Lottie drawing; its own animation is left out. Read import warnings before editing.

## Accounts and LottieFiles

| Command | Arguments and options | Example |
| --- | --- | --- |
| `login` | Signs in to LottieFiles (opens a browser once; over SSH or on Linux with no display, a link to open anywhere). | `creator-tui login` |
| `logout` | Forgets the saved sign-in. | `creator-tui logout` |
| `whoami` | Shows who's signed in to LottieFiles, and their workspaces; `--json` gives JSON. | `creator-tui whoami --json` |
| `cdn FILE` | Prints the CDN link and embed page, turning the link on first. `FILE` is an `lf:` path, LottieFiles link, or linked local file. `--optimized` uses Optimized .lottie (paid plans); `--off` turns links off everywhere they're used. | `creator-tui cdn lf:acme/website/hero` |
| `ls [PLACE]` | Lists workspaces, projects, folders, files or a file's versions; `--json` gives JSON. | `creator-tui ls lf:acme/website --json` |
| `pull FILE` | Downloads a file from LottieFiles by its `lf:` name or link; `-o`, `--out PATH` chooses a file or folder (here, by its name, otherwise); `--force` writes over a file that's there already, losing edits not on LottieFiles. | `creator-tui pull lf:acme/website/hero/intro -o public/intro.lottie` |
| `push FILE [TO]` | Uploads a Lottie (JSON or `.lottie`), with its state machines and themes. A project or folder means a new file there, a file means a new version, and a workspace means its Drafts. Without `TO`, publishes a new version of the file it was pulled from. `--name NAME` names the new file (its file's name otherwise); `--force` saves a new version even if someone saved one since it was pulled. | `creator-tui push intro.lottie lf:acme/website` |

An `lf:` path names a workspace, project, folders and file: `lf:acme/website/hero/intro`.
Names ignore case and punctuation; a unique name prefix is enough. `@6` selects version 6.
LottieFiles file links and Creator links work too. See [LottieFiles](https://terminal.lottiefiles.com/docs/lottiefiles.md).

`pull` writes a `.ctd` by the file's name, or the format named by the output extension. It
refuses to overwrite a different or edited local file without `--force`. `push` without a target needs a stored link from a pull or
publication. It refuses a newer remote version without `--force`.

```sh
creator-tui ls                                      # your workspaces
creator-tui ls lf:acme                              # a workspace's projects
creator-tui ls lf:acme/website/hero                 # a folder's files, or a file's versions
creator-tui pull lf:acme/website/hero/intro@6       # its sixth version
creator-tui push intro.lottie                       # a new version, if it was pulled
creator-tui push intro.lottie lf:acme/website      # a new file in a project or folder
creator-tui push intro.lottie lf:acme/website --name Intro
creator-tui pull lf:acme/website/intro -o intro.json --force
creator-tui push intro.json --force
```

Saving with `w` in the editor saves locally. Use `push` or the export panel to publish.
`push` includes fonts; panel exports follow their **Text** choice.

## Play and inspect

| Command | Arguments and options | Example |
| --- | --- | --- |
| `play FILE` | Plays an animation in the terminal, looping, without the editor: a file the editor opens, or an `lf:` name. `--theme NAME` plays it in a theme the file has. Click to pause, drag to scrub, `esc` to quit. | `creator-tui play hero.lottie --theme dark` |
| `tokens FILE` | Lists a Lottie file's tokens (values an app sets while it plays) and themes. `FILE` is JSON or `.lottie`; `--json` gives JSON. | `creator-tui tokens hero.lottie --json` |
| `states FILE` | A Lottie file's state machines in words: each state, what it plays, its rules, the inputs an app sets, and any problems the check finds. `FILE` is JSON or `.lottie`; `-m`, `--machine ID_OR_NAME` selects one (every one otherwise); `--json` gives dotLottie JSON. | `creator-tui states button.lottie -m Button --json` |
| `docs` | Lists your live Creator documents. | `creator-tui docs` |
| `open DOCUMENT` | Opens a Creator document by id; timing and easing sync as you edit. | `creator-tui open DOCUMENT_ID` |
| `mcp` | An MCP server on stdin and stdout for Claude Desktop, Claude Code, Cursor, Codex or OpenCode: the copilot's tools, in the Creator Terminal open on this computer or, with none open, a document of its own. `--alone` never uses the app open. See [Other AI apps](https://terminal.lottiefiles.com/docs/mcp.md). | `claude mcp add creator-tui -- creator-tui mcp` |

`states` reads; it does not change the file. Use [States](https://terminal.lottiefiles.com/docs/states.md) to edit a machine and
[Creator sync](https://terminal.lottiefiles.com/docs/creator-sync.md) for the limits of live editing.

## Capture

`creator-tui capture [URL] [OPTIONS]` captures a web page's interface as a Lottie of layers to
animate, named after its components (see [Capturing your app](https://terminal.lottiefiles.com/docs/capture.md)), with no window, on
macOS and Linux (not on Windows yet). With no address, the app in the folder it's run in: from
its dev server, started for the capture if it isn't running. It needs Chrome, Edge, Brave or
Chromium.

| Option | Values and behaviour | Example |
| --- | --- | --- |
| `--element SELECTOR` | Captures the first element a CSS selector matches, rather than what the page shows. | `creator-tui capture localhost:5173 --element "main .card"` |
| `--size WxH` | The window's size in CSS pixels, 200 to 4096 each; default `1440x900`. | `creator-tui capture https://example.com --size 390x844` |
| `--component SPEC` | Renders a registry component and captures its different rest, hover, pressed and clicked looks; writes `NAME.json` unless `-o` is given. | `creator-tui capture --component @animate-ui/demo-components-buttons-flip` |
| `--components` | Every component of the app, each captured alone from its pages (its Storybook's stories when it has Storybook), written as a library: a Lottie each and an `index.json`. The app's library (what the palette's Components shows) unless `--out` names a folder. | `creator-tui capture --components` |
| `-o`, `--out PATH` | The Lottie file to write; otherwise `NAME.capture.json` here, named after what was captured, written again by the next capture of it. | `creator-tui capture -o home.json` |

## Export

`creator-tui export FILE [OPTIONS]` exports a document (`.ctd`), a Lottie file (JSON or
`.lottie`), or an SVG, Frolic `.vd` or Rive `.riv` read as the editor opens it, beside the source
unless you choose an output, never over a file that's already there (`name.export.ext` then).
The default format is dotLottie. Video needs ffmpeg on the PATH. See [Export](https://terminal.lottiefiles.com/docs/export.md) for what
each format carries.

| Option | Values and behaviour | Example |
| --- | --- | --- |
| `-f`, `--format` | `lottie`, `dotlottie`, `vd`, `svg`, `mp4`, `webm`, `mov`, `gif`, `webp`, `apng`, `png`; comma-separated, or `all`. Aliases: `json`, `frolic`, `frames`. Format names ignore case and a leading dot. | `creator-tui export hero.json -f mp4,dotlottie` |
| `-o`, `--out PATH` | Output file, or a PNG sequence folder; one format only. With `--data`, an output folder. | `creator-tui export hero.json -f gif -o hero.gif` |
| `--scale NUMBER` | Multiplies picture and video dimensions; default `1`. Frame dimensions round down to even numbers after scaling and rounding, with a minimum of 2 pixels. | `creator-tui export hero.json -f png --scale 2` |
| `--background COLOUR` | What's behind pictures and video: `white`, `black` or hexadecimal RGB (`#rgb` or `#rrggbb`, with `#` optional). Otherwise see-through where the format allows it, else the document's background (white while it's hidden). | `creator-tui export hero.json -f mp4 --background '#101010'` |
| `--theme NAME` | Applies a theme in the file before token overrides. | `creator-tui export hero.lottie --theme dark` |
| `--set TOKEN=VALUE` | Sets a token; repeat for several. Values must suit the token's type. | `creator-tui export hero.lottie --set 'title=Hello' --set 'accent=#ff0000'` |
| `--data PATH` | CSV, TSV or JSON rows; columns name tokens. Writes one animation per row. Columns without matching tokens are reported and left out. | `creator-tui export hero.lottie --data people.csv -o cards` |
| `--no-blur-bake` | Leaves motion blur out of Lottie, `.lottie` and SVG. Video and pictures always have it. | `creator-tui export hero.json -f svg --no-blur-bake` |
| `--fonts` | Includes whole fonts in Lottie and dotLottie, including row exports. The default carries used glyphs. | `creator-tui export hero.json --fonts` |
| `--json` | Prints one JSON report instead of a line per file: what reading the file and each export couldn't carry. Not with `--data`. | `creator-tui export logo.svg -f vd --json` |

With token overrides or a theme, default output names include `-set` or the theme name.
With `--data`, the default folder is `<source>-<table>` beside the source.
There is no CLI loop-range option: CLI exports use the entire animation.

What a conversion couldn't carry is said in words: reading a Rive file prints
`ball.riv: left out: 4 events` first, and each export's line ends with what it left out
(`(not carried into Frolic: 1 sound)`). With `--json`, the report is
`{"file", "read", "exports": [{"format", "out", "said", "lost"}], "failed", "skipped"}`, where `read` and
each `lost` list a loss each:

| Field | What it is |
| --- | --- |
| `code` | What was lost, as the converter that met it names it: its prefix (`rive`, `svg-import` for reading an SVG, `svg` for writing one, `frolic`, `video`, …), then the thing: `rive.event`, `svg-import.pattern-fill`, `frolic.sound`. The same thing met by two converters has two codes (`svg-import.inner-shadow`, `figma.inner-shadow`). A code stays as it is when its words change. |
| `words` | It as said: `4 events`. |
| `at` | Where in the source the first of them is, when known; otherwise `null`. |
| `count` | How many. |
| `how` | What was drawn instead when it was approximated (`radial` for a conic gradient in Frolic); `null` when it was left out. |

`failed` and `skipped` list `{"format", "why"}`, each format as `--format` names it: one that couldn't be written (the command then ends in an error), or one skipped (a video without ffmpeg).

The shell command writes directly to its output; it does not offer the panel's **Replace** or
**Keep both** confirmation. Choose a separate output path for delivery files.
Formats needing ffmpeg are skipped when ffmpeg is absent; inspect the messages as well as the
exit status. Other format failures are reported while remaining formats are attempted.

## Installation and preferences

| Command | Arguments and options | Example |
| --- | --- | --- |
| `update` | Installs the newest version now (it also updates itself in the background); `--check` only says whether there's a newer one. | `creator-tui update --check` |
| `uninstall` | Removes Creator Terminal from this computer: the command, the app and its caches. Asks before settings, sign-ins and kept edits go too; `--all` removes them without asking. ffmpeg stays. | `creator-tui uninstall --all` |
| `telemetry [WHAT]` | `status` (default), `on` or `off`. Status describes what is sent. | `creator-tui telemetry off` |
| `app` | Makes the application shortcut that opens a separate window. | `creator-tui app` |
| `--window` | Opens in the app's own window with its built-in font. | `creator-tui --window hero.json` |
| `--no-sound` | No sound out of the computer for this run, whatever the **Sound** setting says (for agents' runs and recordings). | `creator-tui --no-sound hero.json` |


## Environment

| Variable | Use | Example (POSIX shell) |
| --- | --- | --- |
| `LOTTIEFILES_TOKEN` | Supplies a LottieFiles token without browser sign-in. Keep its value out of scripts and logs. | `LOTTIEFILES_TOKEN="$LOTTIEFILES_TOKEN" creator-tui whoami` |
| `DO_NOT_TRACK=1` | Disables usage stats. | `DO_NOT_TRACK=1 creator-tui hero.json` |


For display variables, see [Terminals](https://terminal.lottiefiles.com/docs/terminals.md).
Agent, model, theme and usage preferences live in **Settings**; older environment overrides for
those choices are no longer read.