---
title: "Home and the screen"
description: "Find the controls on home and in the editor, manage documents, and set your preferences."
canonical: "https://terminal.lottiefiles.com/docs/home-and-screen/"
last_updated: 2026-10-29
---

# Home and the screen

Find the controls on home and in the editor, manage documents, and set your preferences.

## Home

`creator-tui` with nothing to open starts on home: the wordmark in motion (CREATOR spaced out
over Terminal), and under it what to do. It takes keys and clicks from the first frame. Where
the terminal draws pictures, the wordmark starts with the app's icon in your theme's colours,
its points and handles at work; drawn in characters, it starts with LottieFiles' mark.

- **Continue** (when documents are open: last time's, at a start) goes back to them as they
  were. ● marks one with edits not saved.
- **New document** (`⌃N`) starts a blank canvas.
- **Zen** (`z`) starts a blank document with the stage and copilot alone, when **AI features** are on.
- **A recent file** plays beside the list while it's picked, where the window is wide enough.
- **Examples and templates** (`enter` or `→`) lists the [examples](https://terminal.lottiefiles.com/docs/examples.md) and the
  [templates' gallery](https://terminal.lottiefiles.com/docs/templates-and-styles.md).
- **Sign in to LottieFiles** or **LottieFiles workspaces** (`⌃L`) opens [your workspaces](https://terminal.lottiefiles.com/docs/lottiefiles.md), signing in first when you
  aren't.
- **Agents Mode** (`⌃O`) opens [Agents](https://terminal.lottiefiles.com/docs/agents.md).
- **Settings** (`F2`) opens [Settings](https://terminal.lottiefiles.com/docs/home-and-screen/#settings).
- **Quit** (`q`), last, closes Creator Terminal.

Whatever you choose opens in front, and what was open last time waits in tabs behind it.

- `↑` `↓` (or `j` `k`) move, `enter` or a click opens, `q` quits.
- `esc` goes to the editor: the documents open, or a blank canvas.
- From the editor, File › **Home** (or **Home** in the palette) comes back here with your documents
  still open. Closing the last document (`⌃W`) comes here too.
- `⇧K` opens the [interface's themes](https://terminal.lottiefiles.com/docs/home-and-screen/#interface-themes).

`creator-tui file.json` skips home and goes straight to the editor.


## The screen

The stage (the Composition panel in After Effects, the canvas in Figma or Rive) sits between
the left panel and the rail. The score runs beneath them.

Watch: [A tour of the studio](https://terminal.lottiefiles.com/tour/).

![Three shapes on the stage, CREATE on the left, ARTBOARD in the rail and Position tracks in the score.](https://terminal.lottiefiles.com/docs/assets/shots/start-screen.png)

### Menus

The window's top row runs across it, over every panel: **File**, **Edit**, **View** and **Help**
from its left corner, then the documents' tabs (once two are open), and **⌕ commands** at its
right end, where it stays however many documents are open. Each menu lists the commands people
look for first, each with its key; the [command palette](https://terminal.lottiefiles.com/docs/home-and-screen/#the-command-palette) has every one. In
a window too narrow for the four names, one **☰** opens them.

- **File**: **New document**, **Open…**, **Templates**, **LottieFiles**; **Save**, **Export…**,
  and after an export, **Export to filename** (`⌘E`); **Settings**; **Close document**, **Close all**,
  **Home**.
- **Edit**: **Undo**, **Redo**; **Cut**, **Copy**, **Paste**, **Duplicate**, **Delete**; **Select all**.
- **View**: the zooms; Grid, Snapping, Skeleton and Motion paths (a dot by those on), and
  **Onion skin ›**, its own menu to the side ([Onion skin](https://terminal.lottiefiles.com/docs/editing.md#onion-skin)); Preview,
  Agents Mode, Theme….
- **Help**: **Keys**, **What's new**.

Click a name to open its menu; with one open, moving along opens the next. `F10` opens File (where
the terminal keeps `F10` for itself, **Menus** in the palette does), `←` `→` go from menu to menu,
`↑` `↓` and `enter` pick, `esc` closes. What can't be done now (Cut with nothing selected) is dim
and, picked, says why.

### Left panel

The left panel (the Tools panel in After Effects, the toolbar in Figma or Rive) starts with
**New document** (`⌃N`), **Agents Mode** (`⌃O`) and **LottieFiles** (`⌃L`), as in the File and
View menus. Under them, **CREATE** lists the drawing tools. Click a row, then draw on the stage.
`v` returns to selecting.

| Row | Key | What you make |
|---|---|---|
| **Rectangle** | `⇧R` | A rectangle with corner handles |
| **Ellipse** | `⇧O` | An ellipse |
| **Polygon** | `⇧D` | A polygon |
| **Star** | `⇧S` | A star |
| **More shapes ›** | Click | **Arc**, **Ring**, **Capsule**, **Arrow**, **Squircle**, **Cogwheel**, **Supershape** |
| **Pen** | `⇧P` | Points joined by lines or curves |
| **Curve pen** | `⇧P⇧P` | A smooth curve through points |
| **Pencil** | `⇧N` | A freehand path |
| **Brush** | `⇧N⇧N` | A freehand stroke with a calligraphic nib |
| **Text** | `⇧T` | A line of text or a wrapping text box |
| **Chart** | `⇧X` | A chart with sample data |
| **Material** | `⇧Z` | A rectangle with a material, or a full-size backdrop with a click |
| **Particles** | Click | An emitter |

[Layers](https://terminal.lottiefiles.com/docs/layers.md) explains the drawing tools; [Particles](https://terminal.lottiefiles.com/docs/particles.md) explains emitters.
**RECENT** at the foot lists up to five files you saved, newest first. Click one to open it.
Below 150 columns the panel shows icons; below 100 it steps aside. In a short window the rows
over CREATE step aside first. Everything still has its keys and
[palette](https://terminal.lottiefiles.com/docs/home-and-screen/#the-command-palette) commands.

### Stage

The animation at its own aspect, with selection handles and editing guides when needed.

- A hairline and crop marks show its bounds, even on a dark background. They light up while a
  preview or loop plays.
- ⌥-drag across it to scrub.
- The selected layer's path is drawn with a dot per frame. Where the dots bunch the move is slow;
  where they spread it's fast.
- Under the picture: previous key (`j`), play, next key (`k`), the time, and the loop.

### Rail

The rail (the Properties panel in After Effects or Figma, the Inspector in Rive) is on the right.

- The document and its sync state. Double-click its name to rename the file.
- With nothing selected, the artboard and the score's length:
  - its size: click a number and type. The aspect presets (16:9, 9:16, 1:1, 4:5) grow it around
    what's there, never cropping; a background layer that filled it still fills it.
  - the length, in seconds or frames: click one and type. Layers that ran to the end run to the
    new end.
  - the frame rate: click it and type (24, 25, 30, 50, 60, or any from 1 to 240), or **Set the
    frame rate** in the palette. Everything keeps its time in seconds: keys, layers' in and out
    points, precomps, markers, an Animate text's timing, an emitter's lifetimes, the playhead.
- **Grid** sets spacing. **Background** opens a colour picker; its eye shows or hides the background.
- **Shutter**, **Phase** and **Samples** appear when a layer uses motion blur;
  [Motion blur](https://terminal.lottiefiles.com/docs/layers.md#motion-blur) explains them.
- **TOKENS**, document themes, data rows and state machines appear when the document has them.
  See [Layers](https://terminal.lottiefiles.com/docs/layers.md#tokens-and-themes) and [States](https://terminal.lottiefiles.com/docs/states.md).
- With a layer selected, its values. **Anchor**, **Position**, **Scale**, **Rotation**,
  **Opacity** and **Size** sit above its appearance and feature controls. Click a number to
  type, or drag it sideways; `⇧` changes it ten times as far, `⌥` a tenth as far. The key
  mark beside a value shows whether it animates and whether a key is at the playhead.
- The copilot and state-machine inspectors use the rail’s place while open.
  **↓ export** opens the [export panel](https://terminal.lottiefiles.com/docs/export.md) there, whatever is selected.
- While typing a value, `tab` keeps it and moves to the next field; `⇧tab` goes back.
  See [The rail's values](https://terminal.lottiefiles.com/docs/editing.md#the-rails-values).
- Edits that arrived from Creator (another editor, or an agent) that you did not see happen.
  Click one to select its track. `u` and `⇧U` name the edit they undo or redo.
- When its rows run past its foot, scroll it: ↑ more and ↓ more say there are more, and a click on
  one goes a page.

### Score

The score (the timeline in After Effects, Figma animation tools or Rive) is at the bottom:
one row per animated property.

- A layer's name sits on its first row; click it to fold the layer.
- Each move, the span between two keys, is drawn as its speed: a flat band is linear, a hump eases
  in and out, a spike that fades starts fast.
- A layer's first row shows its in and out points, with a grip at either end and one in the
  middle (`≡`):
  - drag an end's grip to trim the layer there;
  - drag the middle one to move the whole layer, keys and all;
  - drag anywhere else for a box that picks the keys inside it (`⇧`, or `⌃`, `⌥`, adds them to
    those picked); the ruler scrubs.
- Both snap to the playhead, markers and other keys, and work on every layer selected.
- `[` `]` move the selected layers to start or end at the playhead. The palette's **Trim the
  layer's start (or end) to the playhead** trims them there.
- **Make the animation loop seamlessly** (the palette) makes each animated property end where it
  starts, so it plays round with no jump. It plays back to the first frame's value at the end
  frame, eased as the move before, with no key added to the score; exports get it as an
  ordinary key. Change the start, or the length, and the end follows. A key you put at the end
  yourself stays as you set it.
  - It leaves alone a property with one key before the end, one keyed at the end to a value of
    its own (a spin to 360°), a shape's path, one inside a precomp, one with keys off the
    timeline, and one a behaviour or a rig drives.
  - The playhead goes round: back a frame from the start is the last frame.
  - **Stop looping seamlessly** stops it; the keys stay as they are.

### Ease box

Click a key and its move's ease opens beside it: the curve with handles to drag, nine presets,
and its `cubic-bezier()`, times, length and values. Rest on a preset and the stage loops the move
with it, the trial curve dashed over the one you have. Click to keep it.

![The ease box trying back-out on a heart's scale-up, the trial curve dashed over the current one](https://terminal.lottiefiles.com/docs/assets/ease-box.png)

### Graph editor

A track's values over time, in the score's place: double-click a track's name, press the ease
box's **graph**, or choose **Graph editor** in the palette. `esc` closes it; `↑` `↓` pick
another row and it shows that track.

- Each dimension is a curve of its own (x and y of a position; red, green, blue and alpha of a
  colour). The one you're shaping is bright, with its keys and each move's two handles; the
  others are faint, and drawn as far as they're on the plane. Click a dimension's name along the
  top, or one of its keys, to shape it.
- The plane fits the dimension you're shaping, and keeps still while you drag in it (a key
  dragged past its edge goes past it). Click the dimension's name to fit it again; an undo, or
  an edit made elsewhere, fits it again too.
- Drag a handle to shape that move's ease for that dimension alone: a position's (a scale's,
  an anchor's, a size's, a gradient's start or end) x can ease late while y eases early, as
  Lottie keeps them. A preset (or **all moves**) eases every dimension alike again.
- A key's two handles stay in line, so the curve goes smoothly through it: drag one and the
  handle on the key's other side turns with it, keeping its time. `⌥`-drag a handle to move it
  alone (a corner). A handle reaches at most twice its move's height past either end.
- Drag a key to move it in time and change its value on that dimension: it keeps to whole
  frames, a frame from the keys either side, so the keys stay in order. Dragged up or down, it
  keeps its time until the pointer goes a cell or two sideways.
- Each drag is one undo step.

A colour's channels are eased as one (a handle shapes them all, and the top line says so), and
so is a move along a curved motion path (shape it in the ease box), and every track of a Creator
document: Creator keeps one ease a key.

Watch: [The graph editor](https://terminal.lottiefiles.com/graph-editor/).

### Preview

`` ` `` (or `⌘\`, or **⊡ preview** at the end of the transport) shows the animation alone, full
screen, as the exported file plays: no panels, no score, nothing over the picture, looping the
whole score.

- `space` or a click plays and pauses.
- Press and drag across the picture to scrub: its width is the whole score.
- `←` `→` step a frame.
- `g` shows or hides the document's background.
- `esc` goes back to editing.

The time and keys show under it while it's paused, or for a moment when the pointer moves. Nothing
can be edited meanwhile, but the copilot's edits still show.

`creator-tui play <file>` opens a file straight into the preview, without the editor: anything
the editor opens (a Lottie, a `.lottie`, an SVG, a Frolic `.vd`, a Rive `.riv`, or an `lf:` name
or its link, an older version too with `@N`). It loops, and plays and scrubs as above; `esc` or
`q` quits. `--theme <id>` plays it in one of the file's themes (`creator-tui tokens` lists them).

![The Showreel in preview, full screen, paused, the line under it giving the time](https://terminal.lottiefiles.com/docs/assets/preview.png)

Watch: [Play, scrub and preview](https://terminal.lottiefiles.com/play-scrub/).

### Bottom line

The bottom line (the status bar) gives a hint for the control under the pointer, or reports
what happened after an action. **SCORE**, **STAGE**, **EASE** or **ASK** tells you where
keys go when that focus needs saying. The active selection has full colour; the other
panel’s selection is grey. `esc` returns the keys to the score.

At the right, the version shows an update's download progress or the version ready to use,
on home as well as in the editor. Click it to check for updates and read **What's new**, or
open the restart offer when an update is ready. The **undo**, **redo** and **keys** buttons in
the editor do the same as `u`, `⇧U` and `?`.

### Panels

The layout is set by the document, not by what is selected or folded, so nothing moves under the
pointer. Drag the edge above the score, or beside the rail, to resize the panels; double-click an
edge to put it back. The sizes are kept in `~/.config/motion/layout.json`.

## Documents and tabs

Opening something never loses what you were working on. An example, a recent file, a new document
(`⌃N`), a template, a film or an agent's take opens in a tab of its own. The one you were on
waits behind as you left it: its edits, undo, selection and copilot conversation. A copilot still
working there carries on, and what it says comes to the status line.

![Three documents open: one with an edit not saved waiting in its tab, two templates just made, one in front](https://terminal.lottiefiles.com/docs/assets/tabs.png)

- **Tabs** show on the window's top row, after the menus, once two documents are open.
  - ● marks edits not saved (or a document with no file yet), ✦ a copilot at work, and an italic
    name a document only being looked at.
  - Click one to bring it forward, its `×` to close it.
  - `{` and `}` go to the one before and after; `⌃W` closes the one in front.
  - Double-click the one in front to rename its file.
- **A document only looked at gives its place.** One opened from RECENT or home and not changed
  yet (or the blank canvas Creator Terminal starts with) is replaced by the next one you open, as a
  browser tab is by a link. Change it, and it stays.
  - One already open comes to the front rather than opening twice.
  - Two new ones get names of their own (`untitled`, `untitled 2`).
- **Closing** one (`⌃W` or its `×`) closes it. Closing the last one goes home, over a blank
  canvas, and so does closing that blank canvas.
- **Close all documents** in the palette (`:` or `⌘P`), or File › Close all, closes every tab.
  Find it by "close all", "close documents", "close tabs" or "close windows". It has no key of
  its own, and isn't offered for a lone blank canvas never drawn on.

### Before edits not saved are closed

Closing a document, closing them all or quitting while one has edits not saved (or not synced
to Creator) asks first, in a box naming it, or saying how many documents there are and
listing them. With nothing unsaved, each just happens.

- **Save** (`enter` or `s`; **Save all** for several) saves them, then closes or quits. A new
  document is named first, as `w` asks, and it goes on once that's saved; `esc` there stops.
- **Don't save** (`d`) closes or quits without them.
- **Cancel** (`esc` or `c`, or a click outside the box) closes, saves and loses nothing.

### Coming back where you were

The documents open, and their edits not saved yet, are kept as you go in
`~/.config/motion/session` (`MOTION_SESSION=path` keeps them elsewhere). The files themselves
aren't touched until you save.

- The next `creator-tui` opens on home, where **Continue** (or `esc`) opens them again where they
  were. `creator-tui file.json` opens that file in front of them. Quit with **Don't save** and
  they open as their files have them.
- A document's edits from last time go back on its file as one step: `u` takes them off (the file
  as it is), `w` saves them.
- If the file changed on disk meanwhile, the status line says so and both are kept: your edits in
  front, `u` for the file.
- A file with edits in two windows at once comes back with both, the other window's in a tab of
  their own (`name 2`).
- Edits are kept as you go, a moment after each, so a closed terminal or a crash loses a second or
  two at most.
- A Creator document is kept by Creator, not here. Save in the box syncs it, and the close or
  quit waits for the sync.

## The command palette

`:` or `⌘P` (or **⌕ commands** on the window's top row) opens the command palette at the top of the stage.
`⌘P` again closes it.

- Every command by its name, with its key, found by a few letters of its words (`exp gif`: Export
  as GIF; `dup`: Duplicate). The ones run lately come first.
- A command's key, typed as it's written, finds it first: `:w` saves, `:q` quits, `:space` plays.
- A layer's name selects it. A number goes to that frame (`48`) or time (`1.5 s`). A recent
  file's or an example's name opens it.
- Commands that don't apply now are left out, unless their whole name is typed: then they show,
  dimmed, saying why.
- Some open a list of their own (Export as…, Open a template…, Theme); `esc` goes back from it.
  Some ask for a short value, typed there (Rename the layer, Go to frame).
- With nothing found and the copilot set up, the last row asks it.
- `↑` `↓` (or `⌃N` `⌃P`, `⌃J` `⌃K`, the wheel) move; `enter` or a click runs it, as its key would,
  in one undo step. `⌃U` clears what's typed, `⌃W` takes a word back. `esc` closes it.

![The command palette lists matching commands after typing frame rate.](https://terminal.lottiefiles.com/docs/assets/shots/start-palette.png)

Two commands worth knowing:

- **Open a file…** lists the document's folder, the files saved lately first. Letters find a
  name, a path typed goes there (`shots/`, `../`, `~/Documents/`), `tab` completes, `enter` opens
  it in a tab. It opens Creator Terminal's .ctd, Lottie, .lottie, SVG, Frolic's .vd and Rive's
  .riv; any but a .ctd opens as a document saved beside it as one.
- **Set the position**, **scale**, **rotation**, **opacity** and **anchor** of the selected
  layer, **the artboard's size** and **the length** start from what they are. Type the new value
  (`640 360`; one number scales both ways; `90 fr` or `3 s`) and `enter`. It's keyed where it
  animates, as typing it in the rail is.

### Commands for the screen and documents

These are the palette’s names. Type a few words after `:` to find one. Feature commands
are listed with their [keys](https://terminal.lottiefiles.com/docs/keys.md) and on their reference pages.

| Task | Commands |
|---|---|
| Documents | **New document**, **Open a file…**, **Save**, **Reload**, **Close the document**, **Close all documents**, **Previous document**, **Next document** |
| Export | **Export as…**, **Export again** (named **Export to filename** after an export), **Upload to LottieFiles** |
| Playback | **Play or pause**, **Previous frame**, **Next frame**, **Ten frames back**, **Ten frames on**, **Go to the start**, **Go to the end**, **Go to frame** |
| Document values | **Set the artboard's size**, **Set the length**, **Set the frame rate** |
| Time view | **Zoom the time in**, **Zoom the time out**, **Show the whole score** |
| Stage view | **Zoom to 100%**, **Zoom to fit**, **Zoom to the selection**, **Grid**, **Snapping**, **Skeleton**, **Motion paths of every layer**, **Show or hide the background**, **Preview, full screen** |
| Other screens | **Templates**, **Open a template…**, **LottieFiles**, **Agents**, **Copilot**, **Close the copilot**, **State machines**, **Try it** |
| Preferences and help | **Theme**, **Settings**, **AI features on or off**, **Keys**, **Menus**, **What's new** |

## Interface themes

The interface's own colours come in themes. (A document's themes are something else: see
[Tokens and themes](https://terminal.lottiefiles.com/docs/layers.md#tokens-and-themes).)

`⇧K` opens the palette on them: `terminal` first, then the dark themes and the light ones (`←` `→`
go from one group to the other). Move through them and the screen is drawn in each; `enter` or a
click chooses one, `esc` puts back what was.

A dark theme and a light one are chosen, and which of the two shows: the terminal's side (its
background when Creator Terminal starts), always dark, or always light. `m` in the themes goes through
the three. The choice is kept in the [settings](https://terminal.lottiefiles.com/docs/home-and-screen/#settings):

```json
{ "theme": { "mode": "system", "dark": "tokyonight", "light": "github-light" } }
```

`mode` is `system`, `dark` or `light`. With nothing kept it's `system`, `creator` and
`creator-light`. `"theme": "nord"` is one theme always.

Built in: `creator` (the default), `aura`, `ayu`, `carbonfox`, `catppuccin`, `catppuccin-frappe`,
`catppuccin-macchiato`, `cobalt2`, `cursor`, `dracula`, `everforest`, `flexoki`, `github`,
`gruvbox`, `kanagawa`, `material`, `monokai`, `nightowl`, `nord`, `one-dark`, `osaka-jade`,
`palenight`, `rosepine`, `solarized`, `synthwave84`, `tokyonight`, `vercel`, `vesper`, `zenburn`.

The light themes are `ayu-light`, `catppuccin-light`, `creator-light`, `cursor-light`,
`dracula-light`, `everforest-light`, `flexoki-light`, `github-light`, `gruvbox-light`,
`kanagawa-light`, `material-light`, `nightowl-light`, `nord-light`, `one-dark-light`,
`rosepine-light`, `solarized-light`, `tokyonight-light`, `vercel-light`.
`terminal` takes the terminal’s own colours.

### The document's background

Each document has a background of its own: a colour, shown or hidden. Themes leave it alone.

- `g` (or ◐ by the stage's toggles, or the eye beside its colour in the rail) shows or hides it.
  Click its swatch to pick its colour.
- Hidden, the stage shows a light grey with a grid of dots.
- The background setting is kept in the document, and a .lottie export keeps it in its
  manifest, where dotLottie players read it. It does not
  become a layer. Picture, SVG and video exports can use it; see [Export](https://terminal.lottiefiles.com/docs/export.md).
- A file from LottieFiles takes the background it has there, when it has none of its own.
- A Creator document's background is kept here, not in Creator: it's never an edit to sync.

### A theme of your own

A JSON file in `~/.config/motion/themes/`, named for the theme. One named as a built-in theme
takes its place (`nord.json` is `nord`); one named as a light side (`github-light.json`) takes
only that side.


```json
{
  "colours": { "night": "#1a1b26", "storm": "#24283b", "fg": "#c0caf5", "blue": "#7aa2f7",
               "day": "#e1e2e7", "ink": "#3760bf", "deepblue": "#2e7de9" },
  "dark": { "background": "night", "panel": "storm", "text": "fg", "accent": "blue" },
  "light": { "background": "day", "text": "ink", "accent": "deepblue" }
}
```

- `colours` names colours for both sides.
- `dark` and `light` are each a whole theme: a file with both is two themes, `name` and
  `name-light`.
- A colour is `#rrggbb`, `#rgb`, a name from `colours`, or `"none"` (the terminal's own, for
  `background` and `text`).
- A side needs `background`, `text` and `accent`. A key the app doesn't know is an error, so a
  misspelt one shows.

| key | what it colours | when unset |
|---|---|---|
| `background` | behind everything: between the panels, the bottom line | (needed) |
| `panel` | the panels | near the background, toward the text |
| `raised` | menus, boxes, buttons, the rail's rows | a step from the panel |
| `hover` | what the pointer is over | a step from `raised` |
| `row` | a row the pointer is over | between the panel and `raised` |
| `layer` | the rows of the layer selected on the stage | the panel, tinted by `selection` |
| `text` | text | (needed) |
| `muted` | labels | between the text and the panel |
| `faint` | what matters least, and lines | between `muted` and the panel |
| `rule` | hairlines between the rail's sections | the panel, toward the text |
| `accent` | what is on, what the pointer is over, keys | (needed) |
| `accent_bg` | behind what is on | the background, tinted by `accent` |
| `accent_dim` | an eased move on the score | between the panel and `accent` |
| `selection` | what is selected, and warnings | creator's amber |
| `selection_idle` | what is selected on the side without the keys (the stage, or the score) | between `text` and the panel |
| `error` | errors | creator's red |
| `copilot` | the copilot's (or anyone else's) changes | creator's violet |
| `copilot_bg` | a track the copilot just changed | the background, tinted by `copilot` |
| `sound` | sound's waveforms | creator's blue |
| `video` | video's lanes | creator's coral |
| `token` | tokens (values an app sets) | creator's green |
| `token_bg` | behind a token | the background, tinted by `token` |
| `tint` | the copilot's panel while it works | the background, tinted by `copilot` |
| `note` | notes for the copilot, an update's news | `selection` |
| `done` | the copilot's finished steps | `token` |
| `state` | state machines | `video` |
| `state_bg` | behind a state | the background, tinted by `state` |

## Settings

`F2` opens the Settings page from anywhere (`⌘,` in the app's own window, **Settings** on Home or
in the palette, also found by "preferences"); `esc` or **Back** goes back to where it was opened,
the document as it was.

- **App**: appearance (mode, dark and light themes), the editor (snapping, the grid and its
  spacing, the score's and rail's sizes back to automatic), privacy (usage stats: off stops
  sending at once, on applies from the next launch), the [AI features](https://terminal.lottiefiles.com/docs/home-and-screen/#ai-features) (one switch
  for all of them) and the voice model LottieFiles' voices are made with, the copilot's agent and model (a conversation under way keeps its agent; the
  choice is for the next one), the agent, model and style for new ideas and films (only new ones:
  threads kept keep theirs), updates (check now, what's new, restart when one is ready), and,
  under Advanced, read-only, the folders and the environment variables in use.
- **Accounts**: the LottieFiles sign-in (signing out signs the ⌃L view out at once; a save under
  way must finish first), the Creator MCP connection apart from it (close its documents before
  signing out), the workspace ⌃L opens, and whether GitHub and ElevenLabs are set up (never the
  credential). Both sign-ins show **Open to sign in** with a link (`y` copies it) and **Cancel**
  while waiting for the browser.

`↑` `↓` choose a row, `←` `→` change it (`enter` presses a button), `[` `]` go to the section
before or after, `tab` switches App and Accounts, `y` copies a value. The few rows an environment
variable decides (usage stats with `DO_NOT_TRACK`, updates with `MOTION_NO_UPDATE`, the LottieFiles
sign-in with `LOTTIEFILES_TOKEN`) are shown read-only, with the variable's name; every other
preference is the page's alone. A file the page can't read is left as it is, and its rows are
read-only until it's fixed.

Every preference is kept in `~/.config/motion/settings.json`, to change in the app or by hand: the
theme, snapping and the grid, usage stats, the AI switch, the voice model, the copilot's choices and
the agents'.
Sign-ins are kept apart (`lottiefiles.json`, `token.json`), and so are the app's own records:
`layout.json` (the panels' sizes), `update.json`, and `telemetry.json` (the
install's random id). The app changes only what you change in it and leaves the rest of the file as
it is. A file it can't read (a stray comma) it leaves alone: the bottom line says why, and the
defaults are used until it's fixed. A value that isn't one (`"snapping": "yes"`) is said too, its
default used, and choosing it in Settings (or ⇧K for the theme) puts it right; the other settings
are kept. Usage stats aren't sent while their setting can't be read.

```json
{
  "theme": { "mode": "system", "dark": "creator", "light": "creator-light" },
  "snapping": true,
  "grid": false,
  "grid_spacing": 10,
  "telemetry": false,
  "ai": true,
  "voice": "fish",
  "copilot": { "backend": "claude", "model": "opus" },
  "agents": { "agent": { "backend": "claude", "model": "opus" }, "style": "bright-science" }
}
```

| Key | What it is |
|---|---|
| `theme` | a theme's name, or `{"mode", "dark", "light"}` ([Interface themes](https://terminal.lottiefiles.com/docs/home-and-screen/#interface-themes)) |
| `snapping`, `grid` | `true` or `false` (snapping on, the grid off unless set) |
| `grid_spacing` | the grid's spacing, 1 to 1000 composition pixels (10 unless set) |
| `telemetry` | `false`: no usage stats ([Usage stats](https://terminal.lottiefiles.com/docs/home-and-screen/#usage-stats)) |
| `ai` | `false`: every AI feature off ([below](https://terminal.lottiefiles.com/docs/home-and-screen/#ai-features)) |
| `voice` | the voice model: `fish`, `fish-drama` or `elevenlabs` (LottieFiles' pick unless set) |
| `copilot` | the copilot's agent (`claude`, `codex` or `kimi`) and its model, by the name its command line takes (`sonnet`, `gpt-6.1-sol`, `kimi-code/k3`; none: the agent's own) |
| `agents` | new ideas' agent and a film's crew (`{"backend", "model"}` each), and a new film's `style` |

### Settings rows

| Section | Rows and choices |
|---|---|
| **Appearance** | **Mode**: System, Dark, Light; **Dark theme**, **Light theme**: the installed interface themes |
| **Editor** | **Snapping**, **Grid**: On or Off; **Grid spacing**: 1–1000 px; **Score height**, **Rail width**: **Automatic** restores their sizes |
| **Privacy** | **Anonymous usage stats**: On or Off |
| **AI** | **AI features**: On or Off; **Voice**: Recommended, Fish Audio S2.1 Pro, Fish Audio Drama 3, ElevenLabs v4 |
| **Copilot** | **Agent**: an installed Claude Code, Codex or Kimi Code; **Model**: the models the agent lists for your account, or **From Codex settings** (and the like) for the agent's own |
| **Agents** | **Agent for new ideas**, **Model for new ideas**, **Model for new films**, **Style for new films** (including **Learn from attachments**); **Parallel shots** is read-only when set by `MOTION_FILM_CREW` |
| **Updates** | **Version**, **Last check**, **Status**; **Check now**, **What’s new**, **Restart** when an update is ready |
| **Advanced** | Settings, layout and cache folders; active environment overrides, read-only |
| **Accounts** | **LottieFiles**, **Creator MCP** sign-in or sign-out; **Open to sign in**, **Cancel** while waiting; **Workspace**; **GitHub**, **ElevenLabs** connection status |

![Settings shows Appearance, Editor, Privacy and AI preferences with their current values.](https://terminal.lottiefiles.com/docs/assets/shots/start-settings.png)

### AI features

One switch turns every AI feature off, or on again: **AI features** on the Settings page (App,
under AI; **AI features on or off** in the palette too), kept as `"ai"` in `settings.json` (on
unless it says `false`). Off, the copilot, zen's conversation, notes for the copilot, Agents Mode
and the Copilot example are gone, as if they weren't there: no key, palette entry, home row or
button for them, zen is the stage alone, and Settings shows neither the Copilot and Agents
sections nor ElevenLabs. Agents in other apps can't find or use it either: the app stops
listening for them, and `creator-tui mcp` doesn't start or take calls ([Other AI apps](https://terminal.lottiefiles.com/docs/mcp.md)).
No agent is started and nothing is sent to an AI service. Turning them off ends the copilot's
conversation and the agents at work; on again, they're back at once, without a restart.

```json
{ "ai": false }
```

### Environment variables

| | |
|---|---|
| `MOTION_AUTH_DIR=dir` | where the sign-in, settings and records are kept, in place of `~/.config/motion` |
| `MOTION_GRAPHICS=kitty\|sixel\|iterm\|blocks\|sextants\|quadrants\|octants` | how the stage is drawn ([Terminals](https://terminal.lottiefiles.com/docs/terminals.md)) |
| `MOTION_NO_UPDATE=1` | no looking for or installing updates |
| `MOTION_NO_AUDIO=1` | no sound |
| `DO_NOT_TRACK=1` | no usage stats |
| `MOTION_SESSION=path` | where the documents open are kept between runs ([Documents and tabs](https://terminal.lottiefiles.com/docs/home-and-screen/#documents-and-tabs)) |
| `MOTION_RECENT=path`, `MOTION_LAYOUT=path` | where the recent files and the panels' sizes are kept |
| `MOTION_AGENTS_DIR=dir` | where [Agents](https://terminal.lottiefiles.com/docs/agents.md)' threads are kept |
| `MOTION_FILM_CREW=8` | how many shots of a [film](https://terminal.lottiefiles.com/docs/agents.md#films) are built at once |
| `ELEVENLABS_API_KEY=key` | a film's voice and music, and what a watched video says, by ElevenLabs with your own key |
| `MOTION_YTDLP=path` | the yt-dlp videos are watched with, in place of the one fetched |
| `MOTION_WATCH_CACHE=dir`, `MOTION_VIDEO_CACHE=dir`, `MOTION_LF_CACHE=dir`, `MOTION_FONT_CACHE=dir`, `MOTION_CAPTURE_CACHE=dir` | where videos watched, video layers' proxies, LottieFiles' files and fonts fetched are cached, and where capturing's browsers with no window keep their profiles while they run (a `browsers` folder in it) |
| `GITHUB_TOKEN`, `GH_TOKEN` | the token [templates](https://terminal.lottiefiles.com/docs/templates-and-styles.md#templates) ask GitHub with, in place of the GitHub CLI's |
| `LOTTIEFILES_TOKEN=token` | signed in to [LottieFiles](https://terminal.lottiefiles.com/docs/lottiefiles.md) without the browser |
| `MOTION_NO_BROWSER=1` | no browser opened to sign in: the link is said instead |
| `MOTION_STAGE_MPX=3` | the most pixels the stage is drawn with, in millions (0: every one) |
| `MOTION_NO_PIXEL_MOUSE=1` | the mouse by cells, not pixels ([The mouse](https://terminal.lottiefiles.com/docs/editing.md#the-mouse)) |


## Usage stats

Creator Terminal sends anonymous usage stats, so we can see what's used, what's slow and what
breaks:

- the commands, features, keys and buttons used (counted, never what's typed);
- exports (format, how long, whether they worked) and the copilot's turns (how long, how many
  edits);
- frame times, the terminal and system;
- warnings and crashes, with names, paths and numbers taken out.

Never your files, their names or contents, your prompts, or who you are: an install is a random
id. The first run says so.

```sh
creator-tui telemetry        # what's sent, and whether it is
creator-tui telemetry off    # stop (DO_NOT_TRACK=1 does too)
```

They go to LottieFiles and are kept private.