# Command reference (/docs/cli/reference) Syntax, arguments, and options for Reela commands. Run `reela -h` for help in your installed version. ## login / logout / whoami / status ```bash reela login reela logout reela whoami reela status ``` - `login` signs in through browser authorization. Open the displayed URL, enter the code if requested, and wait for the command to finish. - `logout` signs out of the selected profile. - `whoami` shows the signed-in account. - `status` checks account and delivery status. ```bash reela --profile work login reela --profile work whoami ``` ## create Create a video from a prompt and optional media files. ```bash reela create [PROMPT] --visual [OPTIONS] ``` Provide a positional prompt or `--prompt-file`. At least one `--visual` is required. | Option | Description | | --- | --- | | `--prompt-file ` | Read the prompt from a file instead of a positional prompt. | | `--visual ` | Visual type. Repeat for multiple types; see below. | | `--duration ` | Video duration. Default: `30`. | | `--layout ` | `landscape` (default), `portrait`, or `square`. | | `--tier ` | Quality and cost option from `reela tiers list`. | | `--avatar ` | Avatar to include. Repeat for multiple avatars. | | `--file ` | Attach a local file with a role. Repeat for multiple files. | | `--session ` | Group related videos under a descriptive project title. | | `--music-video` | Generate a song and music video. Do not combine with background-music files. | | `--dry-run` | Validate and estimate credits without uploading files or creating a task. | ### Visual types and file roles - `ai-video`: generate shots; optionally attach `reference-image:<path>` for style. - `avatar`: include a presenter selected with `--avatar <id>`. - `original-clip`: edit footage without its audio; attach `video-source:<path>`. - `original-sync`: keep footage audio; attach `video-audio:<path>`. - `image-video`: animate an image; attach `original-image:<path>`. Use `background-music:<path>` for your own music. Repeat flags instead of comma-joining values. ### Examples ```bash reela create "A product demo" --visual ai-video --layout portrait --dry-run reela create --prompt-file brief.txt --visual image-video --file original-image:photo.png --dry-run ``` Review estimated credits first. Start the daemon and configure your delivery subscription before removing `--dry-run` to submit. Submission can consume credits; Reela generates the video in the background and delivers the finished result through your subscription. See the daemon / subscribe section below. ## tasks List tasks and inspect individual task details or output versions. For long-running video generation, use daemon completion subscriptions to receive finished results automatically. ```bash reela tasks list [--status <STATUS>] [--limit <N>] [--offset <N>] [--sort <ORDER>] reela tasks get <TASK_ID> reela tasks versions <TASK_ID> --origin brand [--limit <N>] [--offset <N>] reela tasks download <TASK_ID> [--video <ID>] [--out-dir <DIR>] ``` - `list`: defaults to 20 results, offset 0, sorted by `created_at:desc`. Status filters: `cancelled`, `pending`, `processing`, `failed`, `partial`, `completed`. - `get`: show task status, progress, and the creation prompt when available. - `versions`: list Brand output versions, including unfinished outputs. Requires `--origin brand`. Limit: 1–100 (default 20); offset defaults to 0. - `download`: download the finished video to the configured directory or `--out-dir` (short form: `-o`). Use `--video` to select a completed Brand output. ```bash reela tasks list --status completed --output json ``` ## collection List videos in an existing collection, including titles and descriptions. ```bash reela collection list [--session <TITLE>] reela collection list --session "Product launch" --output json ``` `REELA_COLLECTION_ID` takes priority when set. Otherwise, the command looks up the session in the selected profile. The default session is `reela-YYYY-MM-DD` using the local date, not the last used session. This command does not create a collection; use `create` to start one. Completed videos may include download URLs. Treat these links as sensitive and do not publish them; do not assume every link requires authentication or has the same expiry. ## avatar ```bash reela avatar list reela avatar get <ID> ``` `avatar list` lists available avatars; `avatar get` shows an avatar’s details. Use its ID with `create --avatar`. ## tiers List generation options and the default tier for the selected profile. ```bash reela tiers list reela tiers list --output json reela --profile work tiers list ``` Plain output shows each tier’s quoted label, description, and default marker. JSON output includes: - `default_tier`: the default tier label, when available. - `tiers`: the list of choices, with `label`, `content` (description), and `is_default` for each entry. Use the exact label as `create --tier`, preserving capitalization and quoting labels that contain spaces. Tier descriptions explain the available generation choices. Account access is checked when you validate or submit a request. ```bash reela create "A product demo" --visual ai-video \ --tier "<tier-label>" --dry-run --output json ``` Replace `<tier-label>` with a label returned by `tiers list`. The preview returns `credits_cost` and `quota_after` without creating a task. Remove `--dry-run` to submit with the same options. Without `--tier`, `create` uses the default available to the CLI. If no default is available, refresh with `tiers list` or supply `--tier`. Select the same profile when listing tiers and creating the video. ## brand List and apply existing brand packages. ```bash reela brand list [--limit <N>] [--offset <N>] reela brand apply <BRAND_ID> --task <TASK_ID> [--inputs '<JSON>'] ``` `list` defaults to 20 results and offset 0; the limit must be 1–100. `apply` applies a brand package and waits up to 10 minutes for the finished video. Use `--inputs` to provide values required by your brand package. It accepts a JSON object with string, number, or boolean values; arrays, nested objects, and null are not supported. Parameter names are defined by the package. For example: ```bash reela brand apply <BRAND_ID> --task <TASK_ID> \ --inputs '{"AUTHOR_PROFILE_IMAGE_URL":"https://example.com/avatar.jpg","AUTHOR_NAME":"Alex"}' ``` Missing required template values are rejected before rendering. Supply the missing values before applying again. Do not include credentials or secrets in these parameters. If waiting is interrupted, the operation may continue. Check output versions before applying again: ```bash reela tasks versions <task-id> --origin brand reela tasks download <task-id> --video <video-id> ``` ## edit Export edit JSON to continue editing within Reela, or export a standalone Remotion project for unrestricted local editing. ```bash reela edit versions <TASK_ID> reela edit export-json <TASK_ID> --file <PATH> [--version <N>] reela edit export-remotion <TASK_ID> [--video <VIDEO_ID>] [--out-dir <DIR>] reela edit validate <FILE> reela edit save <FILE> reela edit render <FILE> ``` - `versions`: list editable versions, including drafts and failed renders. - `export-json`: export the latest or selected edit version as JSON for editing within Reela. Edit the file, validate it, then use `save` or `render`. - `export-remotion`: export a standalone Remotion project for unrestricted local editing. Without `--video`, it exports the current edit; use `--video` to select a video version. `--out-dir` (short form: `-o`) is the project directory itself, not its parent. Without it, a project folder is created in the configured download directory. Existing destinations are preserved by adding a numeric suffix. JSON output contains the final directory `path`. - `validate`: check the edit JSON for errors without uploading its contents. Requires sign-in and an internet connection. - `save`: save the draft without rendering. Open the returned preview URL to review it. - `render`: save and wait for rendering to finish. Success returns the task ID and preview URL only after the rendered output is saved. The service waits up to ten minutes; the CLI allows ten minutes thirty seconds for the response. A confirmed render failure exits with code 10; a timeout exits with code 6. Submissions are not automatically retried. Interrupting or timing out does not cancel rendering; check `reela edit versions <task-id>` before rendering again. ```bash reela edit export-json <task-id> --file edit.json reela edit validate edit.json reela edit save edit.json ``` Remotion export waits for packaging, downloads and unpacks the project, and does not retain the ZIP. Packaging can take up to ten minutes. Submissions are not automatically retried; interrupting or timing out the wait does not cancel background packaging. The exported project cannot be imported back into Reela and does not use the `validate`, `save`, or `render` commands. ## show Download and edit a Show workspace containing `show.yaml`, `subjects.yaml`, and `episodes/*.md`. ```bash reela show list [--limit <N>] [--offset <N>] reela show download <SHOW_ID> [--out-dir <DIR>] [--force] reela show validate reela show update [--dry-run] [--yes] ``` `list` defaults to 20 results and offset 0. Run `validate` and `update` from the downloaded workspace directory. `update --dry-run` previews without writing locally or remotely; `--yes` submits without interactive confirmation. **Destructive options:** `download --force` deletes all existing files in the target directory, including unrelated files. `update` submits the complete local workspace: removing an Episode file deletes it remotely, and local editable content overwrites remote content without a version check or merge. Generating or pausing Shows cannot be updated. ```bash reela show download <show-id> --out-dir ./my-show cd my-show reela show validate reela show update --dry-run reela show update ``` ### show subject ```bash reela show subject download (--all | --subject-id <ID>) [--history] [--force] reela show subject replace-image <SUBJECT_ID> --file <PATH> reela show subject regenerate <SUBJECT_ID> --prompt-file <PATH> --model <MODEL> [--reference-image-id <ID>] [--yes] ``` - `download`: download images for all Subjects or a single Subject in the current workspace. `--history` includes historical images; `--force` overwrites existing image files. - `replace-image`: upload a static JPEG, PNG, or WebP image (maximum 20 MiB and 40 megapixels), preserving image history and existing videos. - `regenerate`: generate one image and wait up to 10 minutes. The prompt file must be UTF-8. `--reference-image-id` selects an image from the current workspace; `--yes` authorizes generation without interactive confirmation. Show downloads contain structured files, not images; download Subject images separately. To select a historical image, edit `current_image_id` in `subjects.yaml`, then update. Interrupting image generation only stops waiting, not background generation. Running it again can generate and charge again. ## config Manage settings and account profiles. ```bash reela config list reela config get <KEY> reela config set <KEY> <VALUE> reela config profiles list reela config profiles create <NAME> reela config profiles show [NAME] reela config profiles use <NAME> reela config profiles delete <NAME> ``` Settings apply to the selected profile. Use `config list` to discover keys and current values. `profiles use` changes the default profile; `--profile` selects one for a single command. ```bash reela config set delivery.download ~/Videos/reela reela config profiles create work reela --profile work login reela config profiles use work ``` ## daemon / subscribe Manage local automatic delivery on Linux and macOS. These commands are not available on Windows. ```bash reela daemon start [--foreground] [--keep-backlog] reela daemon stop reela daemon status reela daemon install reela daemon uninstall reela daemon logs [--tail <N>] ``` - `start`: start automatic delivery. `--foreground` keeps it attached to the terminal. If this profile has no saved delivery progress, `--keep-backlog` also delivers earlier completed videos that are still available for automatic delivery. Otherwise, delivery resumes from saved progress. - `stop` stops delivery; `status` shows its current status. - `install` enables startup at sign-in; `uninstall` disables automatic startup. - `logs` shows recent logs; `--tail` defaults to 20 lines. ### subscribe ```bash reela subscribe list reela subscribe status reela subscribe add download [--dir <DIR>] reela subscribe add email [--address <EMAIL>] reela subscribe add script --path <PATH> [--timeout-seconds <N>] [--max-retries <N>] reela subscribe remove <METHOD> ``` Methods are `download`, `email`, or `script`. Email defaults to the account email. A script must be a trusted executable that reads one JSON object from stdin and exits 0 on success. `--max-retries` is the maximum total delivery attempts; use `reela subscribe add -h` for the script payload. Adding a method attempts to start a stopped daemon. After changing delivery settings, restart an already-running daemon to load them: for a manually started daemon, use `reela daemon stop` followed by `reela daemon start`; for service-managed startup, restart through your service manager. ```bash reela subscribe add download --dir ~/Videos/reela reela subscribe status ``` ## update Update the installed CLI and check its version. ```bash reela update reela --version ```