Commands
Complete reference for every Melies CLI command. Each command supports quality presets, AI actors, and visual style flags.
melies login
Authenticate and store your token locally. Opens a browser for OAuth by default.
For CI environments or AI agents, pass a token directly with --token. Tokens are stored in ~/.meliesrc.
Set MELIES_TOKEN as an environment variable for automated pipelines. It takes precedence over the stored config.
melies credits
Check your credit balance and usage history. Use the -g flag to group usage by day, week, or month to understand your spending patterns.
melies models
List available AI models with pricing. No authentication needed. Filter by type to narrow results.
See the Models page for the full catalog with specs and comparisons.
melies image<prompt>
Generate an image from a text prompt. Supports AI actors, visual styles, and smart model selection via quality presets.
Combine style flags for richer results. For example, --art-style ghibli --lighting golden --mood romantic all apply to one generation.
Parameters
--actor | Built-in AI actor for consistent characters | See reference |
--ref | Custom actor/object reference ID | See reference |
--fast / --quality / --best | Smart model selection presets | See reference |
--art-style | Art style: ghibli, noir, anime, watercolor, concept... | See reference |
--lighting | Lighting: golden, soft, noir, rembrandt, neon... | See reference |
--mood | Mood: romantic, mysterious, epic, ethereal... | See reference |
--camera | Camera angle: eye-level, low, high, dutch, ots... | See reference |
--shot | Shot size: close-up, medium, wide, full-body... | See reference |
--expression | Expression: smile, serious, surprised, villain-smirk... | See reference |
--color-grade | Color grading: teal-orange, mono, warm, filmic... | See reference |
--era | Historical era: victorian, 1980s, modern, dystopian... | See reference |
--time | Time of day: dawn, golden, dusk, night... | See reference |
--weather | Weather: clear, fog, rain, storm, snow... | See reference |
--sref | Style reference code (see melies styles) | |
--dry-run | Preview prompt, model, and cost without generating | |
--seed | Seed for reproducible generation | |
-o, --output | Save file to path (use with --sync) | |
-m, --model | Model override (overrides quality presets) | See reference |
-a, --aspectRatio | Ratio: 1:1, 16:9, 9:16, 4:3, 3:4 | |
-n, --numOutputs | Number of images, 1 to 4 (default: 1) | |
-i, --imageUrl | Reference image URL for image-to-image | |
-s, --sync | Wait for completion and return the URL |
Use --dry-run to preview the exact prompt, model, and cost before spending credits.
melies video<prompt>
Generate a video from a text prompt. Supports the same style flags as image. Pass an image URL with -i for image-to-video generation.
Parameters
--actor | Built-in AI actor for consistent characters | See reference |
--fast / --quality / --best | Smart model selection presets | See reference |
--movement | Camera movement: dolly-in, pan-left, orbit-360, crane-up, handheld... | See reference |
--lighting, --mood, --camera... | Same visual style flags as image | See reference |
-d, --duration | Duration in seconds (model-dependent) | |
-i, --imageUrl | Reference image URL for image-to-video | |
-m, --model | Model override | See reference |
-a, --aspectRatio | Ratio: 16:9, 9:16, 1:1 | |
-s, --sync | Wait for completion (timeout: 5 min) |
melies poster<title>
Generate a movie poster with 20 style presets. No prompt engineering needed. Just provide a title, pick a style, and optionally add a logline and genre.
Parameters
--style | Poster style: cinematic, anime, noir, horror, sci-fi... | See reference |
--actor | Built-in AI actor for the poster | See reference |
-l, --logline | Short synopsis for the poster | |
-g, --genre | Genre: horror, sci-fi, comedy, drama, action, etc. | |
--fast / --quality / --best | Quality presets | See reference |
--dry-run | Preview prompt and cost | |
-s, --sync | Wait for completion and return the URL |
melies thumbnail<prompt>
Generate YouTube thumbnails. Forces 16:9 aspect ratio with thumbnail-optimized defaults. Great for generating multiple variations at once with -n 4.
Parameters
--actor | Built-in AI actor | See reference |
--expression | Facial expression for the actor | See reference |
--lighting, --mood... | Same visual style flags as image | See reference |
-n, --numOutputs | Number of thumbnails, 1 to 4 |
melies pipeline<prompt>
Generate an image and then animate it into a video. Both steps in one command. Returns { imageUrl, videoUrl }.
Parameters
--im / --vm | Override image or video model | |
--movement | Camera movement for the video step | See reference |
-d, --duration | Video duration in seconds | |
--actor, style flags, quality presets | Applied to both steps |
Sync defaults to true. Override image or video models separately with --im and --vm.
melies upscale<imageUrl>
Upscale an image to higher resolution. Choose between speed (esrgan) and quality (clarity). 4x scale costs double.
Parameters
-m, --model | esrgan (3cr), clarity (8cr), seedvr2 (5cr) |
--scale | 2x or 4x (4x costs double) |
melies remove-bg<imageUrl>
Remove the background from an image. Returns a transparent PNG. Costs 3 credits.
melies actors
Browse 148 built-in AI actors. Filter by type, gender, or age. Search by keywords. See the full Actor Catalog for browsable photos.
melies styles
Browse and search style references (sref codes) for visual consistency. See the Styles page for the full gallery.
melies status<assetId>
Check the status of a generation job. Returns the asset ID, status (pending, completed, failed), URL, prompt, and model.
Use this when running commands without --sync. Poll until status is completed to get the output URL.
melies assets
List your recently generated assets. Filter by type and paginate through results.
Parameters
-l, --limit | Number of assets (default: 20, max: 100) |
-o, --offset | Pagination offset |
-t, --type | Filter: text_to_image, text_to_video, poster_generator |
melies ref
Manage AI actor and object references for consistent characters across generations. Create a reference from an image, then use it with --ref in any generation command.
References work with images, videos, posters, and pipelines. They ensure the same face/object appears across all your generations.
Use references in generation commands: