---
title: "How the command line behaves"
description: "People at a shell, scripts and agents all run creator-tui. Its commands follow Vercel's CLI design guidelines where they help all three act with confidence. This page lists the rules the command line follows, and the ones it leaves out, with why. Command line lists every command and flag."
canonical: "https://terminal.lottiefiles.com/docs/cli-design/"
last_updated: 2026-11-07
---

# How the command line behaves

People at a shell, scripts and agents all run `creator-tui`. Its commands follow
[Vercel's CLI design guidelines](https://vercel.com/design/cli) where they help all three act with
confidence. This page lists the rules the command line follows, and the ones it leaves out, with
why. [Command line](https://terminal.lottiefiles.com/docs/cli.md) lists every command and flag.

## The rules it follows

1. **A command says what it acted on, what changed and what to do next.** `export` names each
   file it wrote, `uninstall` each folder it removed or left, and an error, where one helps, the
   command to try.
2. **stdout is the answer.** Results go to stdout. Progress, warnings and errors go to stderr, so
   `creator-tui export hero.json | …` or `creator-tui update --check | …` reads only the answer.
3. **`--json` is a contract.** A command given `--json` prints one JSON document on stdout, with
   the fields [Command line](https://terminal.lottiefiles.com/docs/cli.md) lists. When `tokens`, `states`, `export` or
   `update --check` fails with `--json`, that document is the failure (see
   [Exit codes and errors](https://terminal.lottiefiles.com/docs/cli.md#exit-codes-and-errors)), so a script reading stdout always gets
   one document and the exit code says which kind. Vercel puts the failure on stderr; here it's on
   stdout, beside the same failure in words on stderr.
4. **Help works before sign-in, settings or the network, and does nothing else.** `--help`,
   `-h`, `help COMMAND` and `--version` print to stdout and exit 0. Every public command's help is
   kept in the tests: a flag or summary that disappears, or a new one, fails them until the change
   is recorded on purpose.
5. **The exit code says how it ended.** 0 for done (an empty list and help too), 1 for a failure,
   2 for a mistake in what was typed, 130 for a stop with Ctrl+C.
6. **An error says what failed, why, and what to try.** `Error:` and what failed, each cause on
   a line under it, then `try:` and a command where one helps. Never a program's debug dump.
7. **A mistyped command is said as one.** A first word that's no command, no file and no `lf:`
   path or LottieFiles link opens nothing: no editor, no window, no look for an update. A plain
   word ends in 2 with the closest command (or `--help`); one with a dot or a folder in it is a
   file that isn't there, and ends in 1 as every command does on one.
8. **What was typed is checked before the work.** A value a command doesn't take (`telemetry
   maybe`, `export -f mp3`, `--set` without `=`) ends in 2 with the values it takes or its help,
   before a file is read.
9. **It reports what happened.** An export that couldn't write a format or a row says which, and
   ends in 1. A format skipped for want of ffmpeg is said too, and isn't a failure.
10. **Secrets stay out of what it prints.** A sign-in's token is kept in the app's folder, and
    `LOTTIEFILES_TOKEN` hands one to a script.
11. **One thing, one name.** Each command and flag has one name. A flag's short form (`-o`, `-f`,
    `-m`) is a lasting shortcut, listed beside it.

The app's own lines and `--json` documents have no colour. Only help, and an option a command
doesn't have or a value outside its list, may be coloured, on a terminal, and `NO_COLOR=1` turns
that off.

## What it leaves out, and why

- **Vercel's command grammar** (`<group> <action> <resource>`). Creator Terminal opens a studio
  rather than managing a cloud account. Plain verbs (`export`, `pull`, `play`) and one `plugin`
  group are how people and agents talk about it.
- **Teams, scopes and project pins** (`--scope`). A LottieFiles sign-in and `lf:` paths name
  everything a command works on.
- **Purchases and billing.** The command line sells nothing.
- **Commands from `PATH`** (`creator-tui-<name>`). Plugins are packages installed in the app,
  made, tried and installed with `creator-tui plugin`.
- **A full catalogue of failure reasons.** A failure's JSON has a `reason` from a short list that
  grows when a script needs to tell two failures apart.
- **Tips, update notices and an accessible mode in the command line.** The editor says what's
  new and what to try; the command line prints only what was asked.
- **`--json` on `play`, `mcp` and the editor.** They're for people (`play`, the editor) or speak
  a protocol of their own (`mcp`).

## Not yet

- `--json` on `docs`, `pull`, `push`, `cdn`, `login`, `capture`, `telemetry` and `plugin new`,
  `install` and `remove`.
- A failure as JSON from the other `--json` commands (`whoami`, `ls`, `share`, `invites`,
  `plugin`), and from an option a command doesn't have or a value outside its list.
- `--yes` for commands that ask, and `--no-color`.
- `next` as a list of arguments a script runs without a shell, beside the command line it shows.
- A test that the flags in each command's help match [Command line](https://terminal.lottiefiles.com/docs/cli.md).
- The editor's flags (`--no-sound`, `--team`, `--solo`) shown only on the commands they change.