---
name: rotato-cli
description: Use the locally installed Rotato macOS CLI to inspect `.rotato` projects and render snapshots or movies. Use when a user asks an AI agent to automate Rotato renders, batch-generate app screenshots or mockup videos, inspect Rotato project structure, replace screen media or overlays during render, target multi-device scenes, or diagnose Rotato CLI invocation failures. Always discover the installed CLI and read its current help before relying on remembered flags.
---

# Rotato CLI

## Overview

Use this skill as a bootstrap for the local `rotato` command. The installed Rotato app owns the real CLI contract, so always ask the machine what is available before constructing commands.

Latest canonical skill file: `https://rotato.app/.well-known/agent-skills/rotato-cli/SKILL.md`

## Discovery First

Start every Rotato CLI task with:

```bash
command -v rotato
rotato --help
```

If `rotato` is missing, stop and report that the CLI is not installed or not on `PATH`. Do not invent installation steps unless the user asks.

Treat the current `rotato --help` output as authoritative for commands, flags, presets, codecs, output formats, and option compatibility. This skill intentionally avoids pinning a Rotato version because users may have a newer app than the skill.

## Safe Workflow

1. Confirm `rotato` exists and read `rotato --help`.
2. Validate that every input project, media file, and output directory exists before rendering.
3. Run `inspect` before any task that depends on device order, 2D overlay ids, scene structure, or project capabilities.
4. Prefer explicit targeting for agent automation, such as per-device indexes from `inspect`, over positional assumptions.
5. Render to the output formats supported by the discovered CLI.
6. Report the exact command run, output path, and any Rotato app handoff error.

## App Handoff

The CLI queues work into the Rotato macOS app. A syntactically valid command can still fail if Rotato is not installed, cannot launch, a different Rotato instance is running, or the command targets the wrong app bundle.

When the user did not ask to launch Rotato, prefer the discovered no-launch or require-running option if the help output provides one. If the command fails because Rotato is not running or LaunchServices cannot open the app, report the exact error and ask whether to open Rotato or target a specific app build.

## Common Shape

The CLI currently has this general shape, but confirm it with `rotato --help` every time:

- `rotato inspect <project.rotato>` for project structure.
- `rotato inspect <project.rotato> --json` for machine-readable project structure.
- `rotato render <project.rotato> --output <path>` for snapshots or movies.
- Render-time screen media replacement.
- Render-time 2D text and image overlay replacement.
- Render settings such as preset, frame rate, size, codec, quality, and jittering.

2D overlay replacements are render-only unless the discovered CLI says otherwise; do not assume they modify the `.rotato` document.

## Multi-Device Work

For multi-device scenes, inspect first and use the CLI's reported scene order or device identifiers. If the CLI reports indexes, treat them as scene-order positions for this project state, not stable user-facing device IDs.

Do not mix shorthand screen-media ordering with explicit per-device targeting unless the current help says that combination is supported.

## Failure Handling

If a command fails, separate these causes:

- CLI missing from `PATH`.
- Input project or media paths do not exist.
- Output directory does not exist.
- Unsupported or stale flag from an older skill/model memory.
- Rotato app handoff failed.
- Rotato accepted the job but the render or inspect operation failed.
- The job timed out.

For failures caused by app launch or app availability, do not guess project contents. Ask for the app to be opened, for permission to launch it, or for the intended Rotato app path.