API Reference: @lottiefiles/relottie-cli

The @lottiefiles/relottie-cli package provides a command-line interface for using the relottie processor and plugins to inspect and transform Lottie files directly from your terminal.

Installation

You can install the CLI tool globally to use it anywhere, or locally within a specific project (recommended).

# Global installation
npm install -g @lottiefiles/relottie-cli

# Local installation
npm install --save-dev @lottiefiles/relottie-cli
# or
yarn add --dev @lottiefiles/relottie-cli

When installed locally, use npx relottie ... or run it via npm scripts.

Usage

relottie [options] [path | glob ...]

• [options]: Flags to control behavior (see below).

• [path | glob ...]: One or more file paths or glob patterns identifying the Lottie JSON files to process. If omitted, reads from stdin.

Command-Line Options

This is a summary of key options based on the source documentation. For the definitive list, run relottie --help.

• -h, --help: Output usage information.

• -v, --version: Output version number.

• -o, --output [path]: Specify output location.

  • If path is a directory, files are written to that directory.

  • If path is omitted (just -o), files are overwritten in place.

  • If the flag is omitted entirely, output goes to stdout.

• -u, --use <plugin>: Use a plugin. Specify the plugin name or path. Can be used multiple times. Plugins are resolved relative to the current directory or as node modules.

• -w, --watch: Watch input files for changes and reprocess automatically.

• -r, --rc-path <path>: Specify the path to a configuration file (e.g., .relottierc.js). Disables the automatic search for config files.

• -i, --ignore-path <path>: Specify the path to an ignore file (like .relottieignore). Disables the automatic search for ignore files.

• -s, --setting <settings>: Specify processor settings (e.g., -s parse.position=false).

• -e, --ext <extensions>: Specify file extensions to process when searching directories (default includes .json).

• -t, --tree: Treat both input and output as syntax trees (LAST JSON format). Equivalent to --tree-in --tree-out.

• --tree-in: Specify that the input should be parsed as a LAST syntax tree.

• --tree-out: Output the result as a LAST syntax tree (JSON format) instead of Lottie JSON.

• --inspect: Output a detailed, formatted inspection of the resulting LAST syntax tree.

• --report <reporter>: Specify a custom reporter for output messages.

• --file-path <path>: Specify path to process input as (useful when reading from stdin).

• --ignore-pattern <globs>: Specify glob patterns for files/folders to ignore.

• --silently-ignore: Do not fail if explicitly given files are ignored.

• --[no-]stdout: Force (--stdout) or disable (--no-stdout) writing to stdout.

• --[no-]color: Force (--color) or disable (--no-color) color in reports.

• --[no-]config: Disable (--no-config) or enable (--config) searching for configuration files.

• --[no-]ignore: Disable (--no-ignore) or enable (--ignore) searching for ignore files.

• -q, --quiet: Output only warnings and errors.

• -S, --silent: Output only errors.

• -f, --frail: Exit with status code 1 if warnings occur.

Underlying options parsing is handled by unified-args.

Configuration

Using configuration files is generally preferred over CLI flags for managing plugins and settings in a project.

• Files: .relottierc, .relottierc.json, .relottierc.js (or .cjs, .mjs), .relottierc.yaml (or .yml), or package.json (with a relottieConfig field).

• Search: The CLI searches upwards from the processed file's directory for these files.

• Details: See the Using the CLI Guide for search order and examples.

Ignoring Files

Create a .relottieignore file (similar syntax to .gitignore) to specify files/patterns for the CLI to ignore.

Examples

# Process input.json using my-plugin.js and write to output.json
relottie input.json -u ./my-plugin.js -o output.json

# Process input.json and output the LAST tree structure
relottie input.json --tree-out

# Process all .json files in src/, overwriting them, using config files
relottie "src/**/*.json" -o

# Pipe input, use a plugin, output LAST tree
cat input.json | relottie -u some-plugin --tree-out > output-tree.json

Related

• Guide: Using the CLI: Practical guide with workflows.

• unified-args: The underlying CLI argument parsing library.