---
title: Video CLI
description: Commands and options for the Cuitty Video command-line workflow.
section: Video
order: 3
updatedAt: 2026-05-24
slug: video/cli
---
# Video CLI

The `cuitty-video` CLI validates, previews, renders, and backs up Video compositions.

In a published install, run the binary directly:

```bash
cuitty-video --help
```

Inside the local workspace, run the CLI source with Bun:

```bash
cd ~/Code/cuitty/video
bun --cwd packages/cli src/index.ts --help
```

## Commands

| Command | Purpose |
| --- | --- |
| `init [directory]` | Create a starter project with a sample composition. |
| `preview <file>` | Parse a YAML or JSON composition and print timeline details. |
| `validate <file>` | Validate schema and lint checks without rendering. |
| `render <file>` | Render a composition to a video file. |
| `backup <file>` | Back up a rendered video through the Persist integration. |
| `login` | Authenticate with Cuitty. |
| `logout` | Remove the local Cuitty auth session. |
| `whoami` | Print the current auth identity. |

## Render

```bash
cuitty-video render composition.yaml -o output.mp4 --codec h264 --crf 18
```

Options:

| Option | Description |
| --- | --- |
| `-o, --output <path>` | Output path. Defaults to `<input>.mp4`. |
| `--codec <codec>` | `h264`, `h265`, `vp9`, `prores`, or `gif`. |
| `--crf <number>` | Constant Rate Factor. Lower is higher quality. |
| `--concurrency <number>` | Parallel frame renders. |
| `--preset-dir <path>` | Directory containing reusable preset YAML files. |
| `--dry-run` | Parse and validate only. Do not render. |

Use `--dry-run` in CI checks that should validate authoring changes without requiring FFmpeg.

## Preview

```bash
cuitty-video preview composition.yaml
cuitty-video preview composition.yaml --frame 60
cuitty-video preview composition.yaml --open
```

`--frame` prints the clips visible at one frame. `--open` starts a local browser preview.

## Validate

```bash
cuitty-video validate composition.yaml --strict
cuitty-video validate composition.yaml --preset-dir ./presets --json
```

Validation checks the DSL shape, timeline bounds, empty layers, overlapping clips, and unknown render types.

## Init

```bash
cuitty-video init my-video
cd my-video
cuitty-video preview composition.yaml
cuitty-video render composition.yaml
```

Use `init` for a local starting point, then move reusable presets and data-driven scenes into version control.

## Backup

```bash
cuitty-video backup output.mp4 -e http://localhost:3456
```

`backup` is the bridge from rendered artifacts into Cuitty storage workflows.