Guide: Using the relottie CLI

relottie provides a command-line interface (CLI) tool, @lottiefiles/relottie-cli, allowing you to inspect and process Lottie files directly from your terminal or within scripts.

This is useful for batch processing, integrating relottie into build systems, or performing quick checks without writing a full Node.js script.

Installation

Install the CLI globally or locally within your project:

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

# Local installation (recommended for projects)
npm install --save-dev @lottiefiles/relottie-cli
# or
yarn add --dev @lottiefiles/relottie-cli

If installed locally, you'll typically run it via npx relottie ... or add it to your package.json scripts.

Basic Usage

The basic syntax involves providing input files (or globs) and specifying an output location if needed.

# Process a single file, output to stdout
relottie input.json

# Process a single file, write to output.json
relottie input.json --output output.json
# or shorthand
relottie input.json -o output.json

# Process multiple files using a glob, rewrite them in place
# Note: Use quotes around globs to prevent shell expansion
relottie "src/**/*.json" -o

# Use stdin and stdout (piping)
cat input.json | relottie > output.json

Command-Line Options

The CLI offers various options to control processing. For the definitive list, run relottie --help. Many of these options are powered by the underlying unified-args library.

-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.

Using Plugins with the CLI

You can activate plugins directly from the command line using the --use or -u flag. You might need to install the plugin package first (npm install some-relottie-plugin).

# Install a metadata plugin (example)
npm install @lottiefiles/relottie-metadata

# Use the metadata plugin via CLI
# (Note: Metadata is usually attached to vfile.data,
# so direct CLI output might not show it without specific reporters/plugins)
relottie input.json --use @lottiefiles/relottie-metadata

# Using a hypothetical custom plugin named 'my-local-plugin.js'
relottie input.json -u ./my-local-plugin.js -o output.json

Often, it's more convenient to manage plugins using configuration files.

Configuration Files

Instead of passing options via the command line, relottie-cli automatically searches for and uses configuration files. This is the recommended way to manage plugins and settings for a project.

Search Order

When processing a file, relottie-cli searches upwards from the file's directory for the first configuration file it finds, in this order of precedence:

.relottierc (JSON)
.relottierc.json (JSON - Caution: Avoid if possible, as Lottie files are also .json)
.relottierc.cjs (CommonJS)
.relottierc.mjs (ES Module)
.relottierc.js (Auto-detects CJS/ESM based on package.json type field)
.relottierc.yaml (YAML)
.relottierc.yml (YAML)
package.json (using a relottieConfig field)

Configuration Examples

1. Using package.json (relottieConfig):

// package.json
{
  "name": "my-lottie-project",
  // ... other fields
  "relottieConfig": {
    "settings": {
      "parse": {
        "position": false // Example parser option
      }
    },
    "plugins": [
      "@lottiefiles/relottie-metadata",
      "./path/to/my-custom-plugin.js"
      // Add other plugins here
    ]
  }
}

(Remember: No comments allowed in actual package.json files)

2. Using .relottierc.js (ES Module example):

// .relottierc.js
import relottieMetadata from "@lottiefiles/relottie-metadata";
import myCustomPlugin from "./path/to/my-custom-plugin.js";

const relottieConfig = {
  settings: {
    parse: {
      position: false,
    },
  },
  plugins: [relottieMetadata, myCustomPlugin],
};

export default relottieConfig;

3. Using .relottierc.yml (YAML example):

# .relottierc.yml
settings:
  parse:
    position: false
plugins:
  - "@lottiefiles/relottie-metadata"
  - "./path/to/my-custom-plugin.js"

Ignoring Files (`.relottieignore`)

Similar to .gitignore, you can create a .relottieignore file in your project root or subdirectories to specify files or patterns that relottie-cli should ignore during processing.

Example Workflow: Generate LAST AST from Lottie JSON

Let's set up an npm script to convert all Lottie files in a lottie-src directory to their LAST representation in an lottie-ast directory.

Install CLI: npm install --save-dev @lottiefiles/relottie-cli
Create Lottie source file: lottie-src/animation.json

Configure package.json:

{
  "name": "last-generator",
  "scripts": {
    "generate:last": "relottie \"lottie-src/**/*.json\" --tree-out --output lottie-ast --ext json"
  },
  "devDependencies": {
    "@lottiefiles/relottie-cli": "^..."
  },
  "relottieConfig": {
    "settings": {
      "parse": { "position": false } // Optional: exclude position data
    }
  }
}

Run the script: npm run generate:last

This will process lottie-src/animation.json, apply any configuration from relottieConfig, and output the resulting LAST tree as lottie-ast/animation.json because of the --tree-out flag.

Next Steps

Explore specific plugins you can use from the command line in the API Reference section.
Consult the unified-args documentation for more details on the CLI argument parsing.

Guide to Using the relottie CLI