# Relottie CLI - Command Line Interface
Learn to use the relottie-cli package to inspect and transform Lottie JSON files from the command line, and explore options and configuration.

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

```bash
# 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

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

- **`[options]`**: Flags to control behavior (see below).
- **`[path | glob ...]`**: One or more file paths or [glob patterns](https://github.com/isaacs/node-glob) 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`](https://github.com/unifiedjs/unified-args#cli).

## 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](/docs/tools/relottie/guides/using-the-cli#configuration-files) 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

```bash
# 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](/docs/tools/relottie/guides/using-the-cli):** Practical guide with workflows.
- **[`unified-args`](https://github.com/unifiedjs/unified-args#cli):** The underlying CLI argument parsing library.